"
def main():
config = Config(retries={"total_max_attempts": 1, "mode": "standard"}, read_timeout=None)
client = boto3.client("neptune-graph", config=config)
try:
print("\n--- Running OpenCypher query without parameters ---")
run_open_cypher_query(client, GRAPH_ID)
print("\n--- Running OpenCypher query with parameters ---")
run_open_cypher_query_with_params(client, GRAPH_ID)
print("\n--- Running OpenCypher explain query ---")
run_open_cypher_explain_query(client, GRAPH_ID)
except Exception as e:
print(f"Unexpected error in main: {e}")
def run_open_cypher_query(client, graph_id):
"""
Run an OpenCypher query without parameters.
"""
try:
resp = client.execute_query(
graphIdentifier=graph_id,
queryString="MATCH (n {code: 'ANC'}) RETURN n",
language='OPEN_CYPHER'
)
print(resp['payload'].read().decode('UTF-8'))
except client.exceptions.InternalServerException as e:
print(f"InternalServerException: {e.response['Error']['Message']}")
except ClientError as e:
print(f"ClientError: {e.response['Error']['Message']}")
except Exception as e: # <--- ADD THIS BLOCK
print(f"Unexpected error: {e}")
def run_open_cypher_query_with_params(client, graph_id):
"""
Run an OpenCypher query with parameters.
"""
try:
parameters = {'code': 'ANC'}
resp = client.execute_query(
graphIdentifier=graph_id,
queryString="MATCH (n {code: $code}) RETURN n",
language='OPEN_CYPHER',
parameters=parameters
)
print(resp['payload'].read().decode('UTF-8'))
except client.exceptions.InternalServerException as e:
print(f"InternalServerException: {e.response['Error']['Message']}")
except ClientError as e:
print(f"ClientError: {e.response['Error']['Message']}")
except Exception as e: # <--- ADD THIS BLOCK
print(f"Unexpected error: {e}")
def run_open_cypher_explain_query(client, graph_id):
"""
Run an OpenCypher explain query (explainMode = "debug").
"""
try:
resp = client.execute_query(
graphIdentifier=graph_id,
queryString="MATCH (n {code: 'ANC'}) RETURN n",
language='OPEN_CYPHER',
explainMode='DETAILS'
)
print(resp['payload'].read().decode('UTF-8'))
except ClientError as e:
print(f"Neptune error: {e.response['Error']['Message']}")
except BotoCoreError as e:
print(f"Unexpected Boto3 error: {str(e)}")
except Exception as e: # <-- Add this generic catch
print(f"Unexpected error: {str(e)}")
if __name__ == "__main__":
main()
```
+ API の詳細については、AWS SDK for Python (Boto3) API リファレンスの「[ExecuteQuery](https://docs.aws.amazon.com/goto/boto3/neptune-2014-10-31/ExecuteQuery)」を参照してください。**
### `StartDBCluster`
次のコード例は、`StartDBCluster` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/neptune#code-examples)での設定と実行の方法を確認してください。
```
def start_db_cluster(neptune_client, cluster_identifier: str):
"""
Starts an Amazon Neptune DB cluster and waits until it reaches 'available'.
Args:
neptune_client (boto3.client): The Neptune client.
cluster_identifier (str): The DB cluster identifier.
Raises:
ClientError: Propagates AWS API issues like resource not found.
RuntimeError: If cluster doesn't reach 'available' within timeout.
"""
try:
# Initial wait in case the cluster was just stopped
time.sleep(30)
neptune_client.start_db_cluster(DBClusterIdentifier=cluster_identifier)
except ClientError as err:
code = err.response["Error"]["Code"]
message = err.response["Error"]["Message"]
if code == "AccessDeniedException":
print("Access denied. Please ensure you have the necessary permissions.")
else:
print(f"Couldn't start DB cluster. Here's why: {code}: {message}")
raise
start_time = time.time()
paginator = neptune_client.get_paginator('describe_db_clusters')
while True:
try:
pages = paginator.paginate(DBClusterIdentifier=cluster_identifier)
clusters = []
for page in pages:
clusters.extend(page.get('DBClusters', []))
except ClientError as err:
code = err.response["Error"]["Code"]
message = err.response["Error"]["Message"]
if code == "DBClusterNotFound":
print(f"Cluster '{cluster_identifier}' not found while polling. It may have been deleted.")
else:
print(f"Couldn't describe DB cluster. Here's why: {code}: {message}")
raise
status = clusters[0].get('Status') if clusters else None
elapsed = time.time() - start_time
print(f"\rElapsed: {int(elapsed)}s – Cluster status: {status}", end="", flush=True)
if status and status.lower() == 'available':
print(f"\n🎉 Cluster '{cluster_identifier}' is available.")
return
if elapsed > TIMEOUT_SECONDS:
raise RuntimeError(f"Timeout waiting for cluster '{cluster_identifier}' to become available.")
time.sleep(POLL_INTERVAL_SECONDS)
```
+ API の詳細については、AWS SDK for Python (Boto3) API リファレンスの「[StartDBCluster](https://docs.aws.amazon.com/goto/boto3/neptune-2014-10-31/StartDBCluster)」を参照してください。**
### `StopDBCluster`
次のコード例は、`StopDBCluster` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/neptune#code-examples)での設定と実行の方法を確認してください。
```
def stop_db_cluster(neptune_client, cluster_identifier: str):
"""
Stops an Amazon Neptune DB cluster and waits until it's fully stopped.
Args:
neptune_client (boto3.client): The Neptune client.
cluster_identifier (str): The DB cluster identifier.
Raises:
ClientError: For AWS API errors (e.g., resource not found).
RuntimeError: If the cluster doesn't stop within the timeout.
"""
try:
neptune_client.stop_db_cluster(DBClusterIdentifier=cluster_identifier)
except ClientError as err:
code = err.response["Error"]["Code"]
message = err.response["Error"]["Message"]
if code == "AccessDeniedException":
print("Access denied. Please ensure you have the necessary permissions.")
else:
print(f"Couldn't stop DB cluster. Here's why: {code}: {message}")
raise
start_time = time.time()
paginator = neptune_client.get_paginator('describe_db_clusters')
while True:
try:
pages = paginator.paginate(DBClusterIdentifier=cluster_identifier)
clusters = []
for page in pages:
clusters.extend(page.get('DBClusters', []))
except ClientError as err:
code = err.response["Error"]["Code"]
message = err.response["Error"]["Message"]
if code == "DBClusterNotFound":
print(f"Cluster '{cluster_identifier}' not found while polling. It may have been deleted.")
else:
print(f"Couldn't describe DB cluster. Here's why: {code}: {message}")
raise
status = clusters[0].get('Status') if clusters else None
elapsed = time.time() - start_time
print(f"\rElapsed: {int(elapsed)}s – Cluster status: {status}", end="", flush=True)
if status and status.lower() == 'stopped':
print(f"\nCluster '{cluster_identifier}' is now stopped.")
return
if elapsed > TIMEOUT_SECONDS:
raise RuntimeError(f"Timeout waiting for cluster '{cluster_identifier}' to stop.")
time.sleep(POLL_INTERVAL_SECONDS)
```
+ API の詳細については、AWS SDK for Python (Boto3) API リファレンスの「[StopDBCluster](https://docs.aws.amazon.com/goto/boto3/neptune-2014-10-31/StopDBCluster)」を参照してください。**
# SDK for Python (Boto3) を使用した Organizations の例
次のコード例は、Organizations AWS SDK for Python (Boto3) で を使用してアクションを実行し、一般的なシナリオを実装する方法を示しています。
*アクション*はより大きなプログラムからのコードの抜粋であり、コンテキスト内で実行する必要があります。アクションは個々のサービス機能を呼び出す方法を示していますが、コンテキスト内のアクションは、関連するシナリオで確認できます。
各例には完全なソースコードへのリンクが含まれており、コードの設定方法と実行方法に関する手順を確認できます。
**Topics**
+ [アクション](#actions)
## アクション
### `AttachPolicy`
次のコード例は、`AttachPolicy` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/organizations#code-examples)での設定と実行の方法を確認してください。
```
def attach_policy(policy_id, target_id, orgs_client):
"""
Attaches a policy to a target. The target is an organization root, account, or
organizational unit.
:param policy_id: The ID of the policy to attach.
:param target_id: The ID of the resources to attach the policy to.
:param orgs_client: The Boto3 Organizations client.
"""
try:
orgs_client.attach_policy(PolicyId=policy_id, TargetId=target_id)
logger.info("Attached policy %s to target %s.", policy_id, target_id)
except ClientError:
logger.exception(
"Couldn't attach policy %s to target %s.", policy_id, target_id
)
raise
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[AttachPolicy](https://docs.aws.amazon.com/goto/boto3/organizations-2016-11-28/AttachPolicy)」を参照してください。
### `CreatePolicy`
次のコード例は、`CreatePolicy` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/organizations#code-examples)での設定と実行の方法を確認してください。
```
def create_policy(name, description, content, policy_type, orgs_client):
"""
Creates a policy.
:param name: The name of the policy.
:param description: The description of the policy.
:param content: The policy content as a dict. This is converted to JSON before
it is sent to AWS. The specific format depends on the policy type.
:param policy_type: The type of the policy.
:param orgs_client: The Boto3 Organizations client.
:return: The newly created policy.
"""
try:
response = orgs_client.create_policy(
Name=name,
Description=description,
Content=json.dumps(content),
Type=policy_type,
)
policy = response["Policy"]
logger.info("Created policy %s.", name)
except ClientError:
logger.exception("Couldn't create policy %s.", name)
raise
else:
return policy
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[CreatePolicy](https://docs.aws.amazon.com/goto/boto3/organizations-2016-11-28/CreatePolicy)」を参照してください。
### `DeletePolicy`
次のコード例は、`DeletePolicy` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/organizations#code-examples)での設定と実行の方法を確認してください。
```
def delete_policy(policy_id, orgs_client):
"""
Deletes a policy.
:param policy_id: The ID of the policy to delete.
:param orgs_client: The Boto3 Organizations client.
"""
try:
orgs_client.delete_policy(PolicyId=policy_id)
logger.info("Deleted policy %s.", policy_id)
except ClientError:
logger.exception("Couldn't delete policy %s.", policy_id)
raise
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[DeletePolicy](https://docs.aws.amazon.com/goto/boto3/organizations-2016-11-28/DeletePolicy)」を参照してください。
### `DescribePolicy`
次のコード例は、`DescribePolicy` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/organizations#code-examples)での設定と実行の方法を確認してください。
```
def describe_policy(policy_id, orgs_client):
"""
Describes a policy.
:param policy_id: The ID of the policy to describe.
:param orgs_client: The Boto3 Organizations client.
:return: The description of the policy.
"""
try:
response = orgs_client.describe_policy(PolicyId=policy_id)
policy = response["Policy"]
logger.info("Got policy %s.", policy_id)
except ClientError:
logger.exception("Couldn't get policy %s.", policy_id)
raise
else:
return policy
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[DescribePolicy](https://docs.aws.amazon.com/goto/boto3/organizations-2016-11-28/DescribePolicy)」を参照してください。
### `DetachPolicy`
次のコード例は、`DetachPolicy` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/organizations#code-examples)での設定と実行の方法を確認してください。
```
def detach_policy(policy_id, target_id, orgs_client):
"""
Detaches a policy from a target.
:param policy_id: The ID of the policy to detach.
:param target_id: The ID of the resource where the policy is currently attached.
:param orgs_client: The Boto3 Organizations client.
"""
try:
orgs_client.detach_policy(PolicyId=policy_id, TargetId=target_id)
logger.info("Detached policy %s from target %s.", policy_id, target_id)
except ClientError:
logger.exception(
"Couldn't detach policy %s from target %s.", policy_id, target_id
)
raise
```
+ API の詳細については、[AWS SDK for Python (Boto3) API リファレンス](https://docs.aws.amazon.com/goto/boto3/organizations-2016-11-28/DetachPolicy) の「*DetachPolicy*」を参照してください。
### `ListPolicies`
次のコード例は、`ListPolicies` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/organizations#code-examples)での設定と実行の方法を確認してください。
```
def list_policies(policy_filter, orgs_client):
"""
Lists the policies for the account, limited to the specified filter.
:param policy_filter: The kind of policies to return.
:param orgs_client: The Boto3 Organizations client.
:return: The list of policies found.
"""
try:
response = orgs_client.list_policies(Filter=policy_filter)
policies = response["Policies"]
logger.info("Found %s %s policies.", len(policies), policy_filter)
except ClientError:
logger.exception("Couldn't get %s policies.", policy_filter)
raise
else:
return policies
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[ListPolicies](https://docs.aws.amazon.com/goto/boto3/organizations-2016-11-28/ListPolicies)」を参照してください。
# SDK for Python (Boto3) を使用したパートナーセントラルの例
次のコード例は、 Partner Central AWS SDK for Python (Boto3) で を使用してアクションを実行し、一般的なシナリオを実装する方法を示しています。
*アクション*はより大きなプログラムからのコードの抜粋であり、コンテキスト内で実行する必要があります。アクションは個々のサービス機能を呼び出す方法を示していますが、コンテキスト内のアクションは、関連するシナリオで確認できます。
*シナリオ*は、1 つのサービス内から、または他の AWS のサービスと組み合わせて複数の関数を呼び出し、特定のタスクを実行する方法を示すコード例です。
各例には完全なソースコードへのリンクが含まれており、コードの設定方法と実行方法に関する手順を確認できます。
**Topics**
+ [アクション](#actions)
+ [シナリオ](#scenarios)
## アクション
### `AssignOpportunity`
次のコード例は、`AssignOpportunity` を使用する方法を示しています。
**SDK for Python (Boto3)**
既存のオポチュニティを他のユーザーに再割り当てします。
```
#!/usr/bin/env python
"""
Purpose
PC-API-07 Assigning a new owner
"""
import logging
import boto3
import utils.helpers as helper
from botocore.client import ClientError
from utils.constants import CATALOG_TO_USE
serviceName = "partnercentral-selling"
partner_central_client = boto3.client(
service_name=serviceName,
region_name='us-east-1'
)
def assign_opportunity(identifier):
assign_opportunity_request ={
"Catalog": CATALOG_TO_USE,
"Identifier": identifier,
"Assignee": {
"BusinessTitle": "OpportunityOwner",
"Email": "test@test.com",
"FirstName": "John",
"LastName": "Doe"
}
}
try:
# Perform an API call
response = partner_central_client.assign_opportunity(**assign_opportunity_request)
return response
except ClientError as err:
# Catch all client exceptions
print(err.response)
def usage_demo():
identifier = "O4236468"
logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
print("-" * 88)
print("Assigning a new owner to an opportunity.")
print("-" * 88)
helper.pretty_print_datetime(assign_opportunity(identifier))
if __name__ == "__main__":
usage_demo()
```
+ API の詳細については、AWS SDK for Python (Boto3) API リファレンスの「[AssignOpportunity](https://docs.aws.amazon.com/goto/boto3/partnercentral-selling-2022-07-26/AssignOpportunity)」を参照してください。**
### `AssociateOpportunity`
次のコード例は、`AssociateOpportunity` を使用する方法を示しています。
**SDK for Python (Boto3)**
オポチュニティとさまざまな関連エンティティとの正式な関連付けを作成します。
```
#!/usr/bin/env python
"""
Purpose
PC-API -11 Associating a product
PC-API -12 Associating a solution
PC-API -13 Associating an offer
"""
import logging
import boto3
import utils.helpers as helper
from botocore.client import ClientError
from utils.constants import CATALOG_TO_USE
serviceName = "partnercentral-selling"
partner_central_client = boto3.client(
service_name=serviceName,
region_name='us-east-1'
)
def associate_opportunity(entity_type, entity_identifier, opportunityIdentifier):
associate_opportunity_request ={
"Catalog": CATALOG_TO_USE,
"OpportunityIdentifier" : opportunityIdentifier,
"RelatedEntityType" : entity_type,
"RelatedEntityIdentifier" : entity_identifier
}
try:
# Perform an API call
response = partner_central_client.associate_opportunity(**associate_opportunity_request)
return response
except ClientError as err:
# Catch all client exceptions
print(err.response)
def usage_demo():
#entity_type = Solutions | AWSProducts | AWSMarketplaceOffers
entity_type = "Solutions"
entity_identifier = "S-0059717"
opportunityIdentifier = "O5465588"
logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
print("-" * 88)
print("Associate Opportunity.")
print("-" * 88)
helper.pretty_print_datetime(associate_opportunity(entity_type, entity_identifier, opportunityIdentifier))
if __name__ == "__main__":
usage_demo()
```
+ API の詳細については、AWS SDK for Python (Boto3) API リファレンスの「[AssociateOpportunity](https://docs.aws.amazon.com/goto/boto3/partnercentral-selling-2022-07-26/AssociateOpportunity)」を参照してください。**
### `CreateOpportunity`
次のコード例は、`CreateOpportunity` を使用する方法を示しています。
**SDK for Python (Boto3)**
オポチュニティを作成します。
```
#!/usr/bin/env python
import boto3
import logging
import sys
import os
sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
import utils.helpers as helper
import utils.stringify_details as sd
from botocore.client import ClientError
from utils.constants import CATALOG_TO_USE
serviceName = "partnercentral-selling"
def create_opportunity(partner_central_client):
create_opportunity_request = helper.remove_nulls(sd.stringify_json("src/create_opportunity/createOpportunity.json"))
try:
# Perform an API call
response = partner_central_client.create_opportunity(**create_opportunity_request)
helper.pretty_print_datetime(response)
# Retrieve the opportunity details
get_response = partner_central_client.get_opportunity(
Identifier=response["Id"],
Catalog=CATALOG_TO_USE
)
helper.pretty_print_datetime(get_response)
return response
except ClientError as err:
# Catch all client exceptions
print(err.response)
def usage_demo():
logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
print("-" * 88)
print("Create Opportunity.")
print("-" * 88)
partner_central_client = boto3.client(
service_name=serviceName,
region_name='us-east-1'
)
create_opportunity(partner_central_client)
if __name__ == "__main__":
usage_demo()
```
+ API の詳細については、AWS SDK for Python (Boto3) API リファレンスの「[CreateOpportunity](https://docs.aws.amazon.com/goto/boto3/partnercentral-selling-2022-07-26/CreateOpportunity)」を参照してください。**
### `DisassociateOpportunity`
次のコード例は、`DisassociateOpportunity` を使用する方法を示しています。
**SDK for Python (Boto3)**
オポチュニティと関連エンティティ間の既存の関連付けを削除します。
```
#!/usr/bin/env python
"""
Purpose
PC-API -14 Removing a Solution
PC-API -15 Removing an offer
PC-API -16 Removing a product
"""
import logging
import boto3
import utils.helpers as helper
from botocore.client import ClientError
from utils.constants import CATALOG_TO_USE
serviceName = "partnercentral-selling"
partner_central_client = boto3.client(
service_name=serviceName,
region_name='us-east-1'
)
def disassociate_opportunity(entity_type, entity_identifier, opportunityIdentifier):
disassociate_opportunity_request ={
"Catalog": CATALOG_TO_USE,
"OpportunityIdentifier" : opportunityIdentifier,
"RelatedEntityType" : entity_type,
"RelatedEntityIdentifier" : entity_identifier
}
try:
# Perform an API call
response = partner_central_client.disassociate_opportunity(**disassociate_opportunity_request)
return response
except ClientError as err:
# Catch all client exceptions
print(err.response)
def usage_demo():
#entity_type = Solutions | AWSProducts | AWSMarketplaceOffers
entity_type = "Solutions"
entity_identifier = "S-0049999"
opportunityIdentifier = "O4397574"
logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
print("-" * 88)
print("Get updated Opportunity.")
print("-" * 88)
helper.pretty_print_datetime(disassociate_opportunity(entity_type, entity_identifier, opportunityIdentifier))
if __name__ == "__main__":
usage_demo()
```
+ API の詳細については、AWS SDK for Python (Boto3) API リファレンスの「[DisassociateOpportunity](https://docs.aws.amazon.com/goto/boto3/partnercentral-selling-2022-07-26/DisassociateOpportunity)」を参照してください。**
### `GetAwsOpportunitySummary`
次のコード例は、`GetAwsOpportunitySummary` を使用する方法を示しています。
**SDK for Python (Boto3)**
AWS オポチュニティの概要を取得します。
```
#!/usr/bin/env python
"""
Purpose
PC-API-25 Retrieves a summary of an AWS Opportunity. LifeCycle.ReviewStatus=Approved
"""
import logging
import boto3
import utils.helpers as helper
from botocore.client import ClientError
from utils.constants import CATALOG_TO_USE
serviceName = "partnercentral-selling"
partner_central_client = boto3.client(
service_name=serviceName,
region_name='us-east-1'
)
def get_opportunity(identifier):
get_opportunity_request ={
"Catalog": CATALOG_TO_USE,
"RelatedOpportunityIdentifier": identifier
}
try:
# Perform an API call
response = partner_central_client.get_aws_opportunity_summary(**get_opportunity_request)
return response
except ClientError as err:
# Catch all client exceptions
print(err.response)
def usage_demo():
identifier = "O5465588"
logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
print("-" * 88)
print("Get AWS Opportunity summary.")
print("-" * 88)
helper.pretty_print_datetime(get_opportunity(identifier))
if __name__ == "__main__":
usage_demo()
```
+ API の詳細については、AWS SDK for Python (Boto3) API リファレンスの「[GetAwsOpportunitySummary](https://docs.aws.amazon.com/goto/boto3/partnercentral-selling-2022-07-26/GetAwsOpportunitySummary)」を参照してください。**
### `GetEngagementInvitation`
次のコード例は、`GetEngagementInvitation` を使用する方法を示しています。
**SDK for Python (Boto3)**
がパートナー AWS と共有しているエンゲージメントの招待の詳細を取得します。
```
#!/usr/bin/env python
"""
Purpose
PC-API-22 GetOpportunityEngagementInvitation - Retrieves details of a specific engagement invitation.
This operation allows partners to view the invitation and its associated information,
such as the customer, project, and lifecycle details.
"""
import json
import logging
import boto3
import utils.helpers as helper
from utils.constants import CATALOG_TO_USE
serviceName = "partnercentral-selling"
partner_central_client = boto3.client(
service_name=serviceName,
region_name='us-east-1'
)
def get_opportunity_engagement_invitation(identifier):
get_opportunity_engagement_invitation_request ={
"Catalog": CATALOG_TO_USE,
"Identifier": identifier
}
try:
# Perform an API call
response = partner_central_client.get_engagement_invitation(**get_opportunity_engagement_invitation_request)
return response
except Exception as err:
# Catch all client exceptions
print(json.dumps(err.response))
def usage_demo():
identifier = "arn:aws:partnercentral-selling:us-east-1:aws:catalog/Sandbox/engagement-invitation/engi-0000000IS0Qga"
logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
print("-" * 88)
print("Given the ARN identifier, retrieve details of Opportunity Engagement Invitation.")
print("-" * 88)
helper.pretty_print_datetime(get_opportunity_engagement_invitation(identifier))
if __name__ == "__main__":
usage_demo()
```
+ API の詳細については、AWS SDK for Python (Boto3) API リファレンス の「[GetEngagementInvitation](https://docs.aws.amazon.com/goto/boto3/partnercentral-selling-2022-07-26/GetEngagementInvitation)」を参照してください。**
### `GetOpportunity`
次のコード例は、`GetOpportunity` を使用する方法を示しています。
**SDK for Python (Boto3)**
オポチュニティを取得します。
```
#!/usr/bin/env python
"""
Purpose
PC-API -08 Get updated Opportunity given opportunity id
"""
import logging
import boto3
import utils.helpers as helper
from botocore.client import ClientError
from utils.constants import CATALOG_TO_USE
serviceName = "partnercentral-selling"
partner_central_client = boto3.client(
service_name=serviceName,
region_name='us-east-1'
)
def get_opportunity(identifier):
get_opportunity_request ={
"Catalog": CATALOG_TO_USE,
"Identifier": identifier
}
try:
# Perform an API call
response = partner_central_client.get_opportunity(**get_opportunity_request)
return response
except ClientError as err:
# Catch all client exceptions
print(err.response)
def usage_demo():
identifier = "O5465588"
logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
print("-" * 88)
print("Get updated Opportunity.")
print("-" * 88)
helper.pretty_print_datetime(get_opportunity(identifier))
if __name__ == "__main__":
usage_demo()
```
+ API の詳細については、AWS SDK for Python (Boto3) API リファレンスの「[GetOpportunity](https://docs.aws.amazon.com/goto/boto3/partnercentral-selling-2022-07-26/GetOpportunity)」を参照してください。**
### `ListEngagementInvitations`
次のコード例は、`ListEngagementInvitations` を使用する方法を示しています。
**SDK for Python (Boto3)**
パートナーに送信されたエンゲージメントの招待の一覧を取得します。
```
#!/usr/bin/env python
"""
Purpose
PC-API-21 ListEngagementInvitations - Retrieves a list of engagement invitations based on specified criteria.
This operation allows partners to view all invitations to engagement.
"""
import json
import logging
import boto3
import utils.helpers as helper
from utils.constants import CATALOG_TO_USE
serviceName = "partnercentral-selling"
partner_central_client = boto3.client(
service_name=serviceName,
region_name='us-east-1'
)
def list_engagement_invitations():
list_engagement_invitations_request ={
"Catalog": CATALOG_TO_USE,
"MaxResults": 20
}
try:
# Perform an API call
response = partner_central_client.list_engagement_invitations(**list_engagement_invitations_request)
return response
except Exception as err:
# Catch all client exceptions
print(json.dumps(err.response))
def usage_demo():
logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
print("-" * 88)
print("Retrieve list of Engagement Invitations.")
print("-" * 88)
helper.pretty_print_datetime(list_engagement_invitations())
if __name__ == "__main__":
usage_demo()
```
+ API の詳細については、AWS SDK for Python (Boto3) API リファレンスの「[ListEngagementInvitations](https://docs.aws.amazon.com/goto/boto3/partnercentral-selling-2022-07-26/ListEngagementInvitations)」を参照してください。**
### `ListOpportunities`
次のコード例は、`ListOpportunities` を使用する方法を示しています。
**SDK for Python (Boto3)**
オポチュニティを一覧表示します。
```
#!/usr/bin/env python
"""
Purpose
PC-API -18 Getting list of Opportunities
"""
import json
import logging
import boto3
import utils.helpers as helper
from utils.constants import CATALOG_TO_USE
serviceName = "partnercentral-selling"
partner_central_client = boto3.client(
service_name=serviceName,
region_name='us-east-1'
)
def get_list_of_opportunities():
opportunity_list = []
list_opportunities_request ={
"Catalog": CATALOG_TO_USE,
"MaxResults": 20
}
try:
# Perform an API call
response = partner_central_client.list_opportunities(**list_opportunities_request)
opportunity_list.extend(response["OpportunitySummaries"])
while "NextToken" in response and response["NextToken"] is not None:
list_opportunities_request["NextToken"] = response["NextToken"]
response = partner_central_client.list_opportunities(**list_opportunities_request)
opportunity_list.extend(response["OpportunitySummaries"])
return opportunity_list
except Exception as err:
# Catch all client exceptions
print(json.dumps(err.response))
def usage_demo():
logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
print("-" * 88)
print("Getting list of Opportunities.")
print("-" * 88)
helper.pretty_print_datetime(get_list_of_opportunities())
if __name__ == "__main__":
usage_demo()
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[ListOpportunities](https://docs.aws.amazon.com/goto/boto3/partnercentral-selling-2022-07-26/ListOpportunities)」を参照してください。
### `ListSolutions`
次のコード例は、`ListSolutions` を使用する方法を示しています。
**SDK for Python (Boto3)**
パートナーがパートナーセントラルに登録したパートナーソリューションの一覧を取得します。
```
#!/usr/bin/env python
"""
Purpose
PC-API-10 Getting list of solutions
"""
import logging
import boto3
import utils.helpers as helper
from botocore.client import ClientError
from utils.constants import CATALOG_TO_USE
serviceName = "partnercentral-selling"
partner_central_client = boto3.client(
service_name=serviceName,
region_name='us-east-1'
)
def get_list_of_solutions():
list_solutions_request ={
"Catalog": CATALOG_TO_USE,
"MaxResults": 20
}
try:
# Perform an API call
response = partner_central_client.list_solutions(**list_solutions_request)
return response
except ClientError as err:
# Catch all client exceptions
print(err.response)
def usage_demo():
logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
print("-" * 88)
print("Getting list of solutions.")
print("-" * 88)
helper.pretty_print_datetime(get_list_of_solutions())
if __name__ == "__main__":
usage_demo()
```
+ API の詳細については、AWS SDK for Python (Boto3) API リファレンスの「[ListSolutions](https://docs.aws.amazon.com/goto/boto3/partnercentral-selling-2022-07-26/ListSolutions)」を参照してください。**
### `RejectEngagementInvitation`
次のコード例は、`RejectEngagementInvitation` を使用する方法を示しています。
**SDK for Python (Boto3)**
が AWS 共有した EngagementInvitation を拒否します。
```
#!/usr/bin/env python
"""
Purpose
PC-API-05 AWS Originated AO rejection - RejectOpportunityEngagementInvitation - Rejects a engagement invitation.
This action indicates that the partner does not wish to participate in the engagement and
provides a reason for the rejection.
Upon rejection, a OpportunityEngagementInvitationRejected event is triggered.
Subsequently, the invitation will no longer be available for the partner to act on.
"""
import json
import logging
import boto3
import utils.helpers as helper
from utils.constants import CATALOG_TO_USE
serviceName = "partnercentral-selling"
partner_central_client = boto3.client(
service_name=serviceName,
region_name='us-east-1'
)
def reject_opportunity_engagement_invitation(identifier, reject_reason):
reject_opportunity_engagement_invitation_request ={
"Catalog": CATALOG_TO_USE,
"Identifier": identifier,
"RejectionReason": reject_reason
}
try:
# Perform an API call
response = partner_central_client.reject_engagement_invitation(**reject_opportunity_engagement_invitation_request)
return response
except Exception as err:
# Catch all client exceptions
print(json.dumps(err.response))
def usage_demo():
identifier = "arn:aws:partnercentral:us-east-1::catalog/Sandbox/engagement-invitation/engi-0000002isviga"
reject_reason = "Customer problem unclear"
logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
print("-" * 88)
print("Given the ARN identifier and reject reason, reject the Opportunity Engagement Invitation.")
print("-" * 88)
helper.pretty_print_datetime(reject_opportunity_engagement_invitation(identifier, reject_reason))
if __name__ == "__main__":
usage_demo()
```
+ API の詳細については、AWS SDK for Python (Boto3) API リファレンスの「[RejectEngagementInvitation](https://docs.aws.amazon.com/goto/boto3/partnercentral-selling-2022-07-26/RejectEngagementInvitation)」を参照してください。**
### `StartEngagementByAcceptingInvitationTask`
次のコード例は、`StartEngagementByAcceptingInvitationTask` を使用する方法を示しています。
**SDK for Python (Boto3)**
EngagementInvitation を受け入れることでエンゲージメントを開始します。
```
#!/usr/bin/env python
"""
Purpose
PC-API -11 Associating a product
PC-API -12 Associating a solution
PC-API -13 Associating an offer
"""
import logging
import boto3
import utils.helpers as helper
from botocore.client import ClientError
from utils.constants import CATALOG_TO_USE
serviceName = "partnercentral-selling"
partner_central_client = boto3.client(
service_name=serviceName,
region_name='us-east-1'
)
def get_opportunity(identifier):
get_opportunity_request ={
"Identifier": identifier,
"Catalog": CATALOG_TO_USE
}
try:
# Perform an API call
response = partner_central_client.get_engagement_invitation(**get_opportunity_request)
return response
except ClientError as err:
# Catch all client exceptions
print(err.response)
def start_engagement_by_accepting_invitation_task(identifier):
response = get_opportunity(identifier)
if ( response['Status'] == 'PENDING') :
accept_opportunity_engagement_invitation_request ={
"Catalog": CATALOG_TO_USE,
"Identifier" : identifier,
"ClientToken": "test-123456"
}
try:
# Perform an API call
response = partner_central_client.start_engagement_by_accepting_invitation_task(**accept_opportunity_engagement_invitation_request)
return response
except ClientError as err:
# Catch all client exceptions
print(err.response)
return None
else:
return None
def usage_demo():
identifier = "arn:aws:partnercentral:us-east-1::catalog/Sandbox/engagement-invitation/engi-0000002isusga"
logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
print("-" * 88)
print("Get updated Opportunity.")
print("-" * 88)
helper.pretty_print_datetime(start_engagement_by_accepting_invitation_task(identifier))
if __name__ == "__main__":
usage_demo()
```
+ API の詳細については、AWS SDK for Python (Boto3) API リファレンスの「[StartEngagementByAcceptingInvitationTask](https://docs.aws.amazon.com/goto/boto3/partnercentral-selling-2022-07-26/StartEngagementByAcceptingInvitationTask)」を参照してください。**
### `StartEngagementFromOpportunityTask`
次のコード例は、`StartEngagementFromOpportunityTask` を使用する方法を示しています。
**SDK for Python (Boto3)**
エンゲージメントの招待を受け入れ、パートナーのシステムで対応するオポチュニティを作成することで、既存のオポチュニティからエンゲージメントプロセスを開始します。
```
#!/usr/bin/env python
"""
Purpose
PC-API -11 Associating a product
PC-API -12 Associating a solution
PC-API -13 Associating an offer
"""
import logging
import boto3
import utils.helpers as helper
from botocore.client import ClientError
from utils.constants import CATALOG_TO_USE
serviceName = "partnercentral-selling"
partner_central_client = boto3.client(
service_name=serviceName,
region_name='us-east-1'
)
def start_engagement_from_opportunity_task(identifier):
start_engagement_from_opportunity_task_request ={
"AwsSubmission": {
"InvolvementType": "Co-Sell",
"Visibility": "Full"
},
"Catalog": CATALOG_TO_USE,
"Identifier" : identifier,
"ClientToken": "test-annjqwesdsd99"
}
try:
# Perform an API call
response = partner_central_client.start_engagement_from_opportunity_task(**start_engagement_from_opportunity_task_request)
return response
except ClientError as err:
# Catch all client exceptions
print(err.response)
return None
def usage_demo():
identifier = "O5465588"
logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
print("-" * 88)
print("Start Engagement from Opportunity Task.")
print("-" * 88)
helper.pretty_print_datetime(start_engagement_from_opportunity_task(identifier))
if __name__ == "__main__":
usage_demo()
```
+ API の詳細については、AWS SDK for Python (Boto3) API リファレンスの「[StartEngagementFromOpportunityTask](https://docs.aws.amazon.com/goto/boto3/partnercentral-selling-2022-07-26/StartEngagementFromOpportunityTask)」を参照してください。**
### `UpdateOpportunity`
次のコード例は、`UpdateOpportunity` を使用する方法を示しています。
**SDK for Python (Boto3)**
オポチュニティを更新します。
```
#!/usr/bin/env python
"""
Purpose
PC-API-2 Updating Partner Originated Opportunity
"""
import logging
import boto3
import sys
import os
sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
import utils.helpers as helper
from botocore.client import ClientError
import utils.stringify_details as sd
from utils.constants import CATALOG_TO_USE
serviceName = "partnercentral-selling"
partner_central_client = boto3.client(
service_name=serviceName,
region_name='us-east-1'
)
def get_opportunity(identifier):
get_opportunity_request ={
"Identifier": identifier,
"Catalog": CATALOG_TO_USE
}
try:
# Perform an API call
response = partner_central_client.get_opportunity(**get_opportunity_request)
return response
except ClientError as err:
# Catch all client exceptions
print(err.response)
def update_opportunity():
update_opportunity_request_orig = sd.stringify_json("src/update_opportunity/update_opportunity_technical_validation.json")
update_opportunity_request = helper.remove_nulls(update_opportunity_request_orig)
try:
# Perform an API call
response = partner_central_client.update_opportunity(**update_opportunity_request)
return response
except ClientError as err:
# Catch all client exceptions
print(err.response)
def update_opportunity_if_eligible(identifier):
response = get_opportunity(identifier)
if response is not None:
return update_opportunity()
else:
print("Failed to retrieve opportunity details")
def usage_demo():
identifier = "O5465588"
logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
print("-" * 88)
print("Updating opportunity.")
print("-" * 88)
helper.pretty_print_datetime(update_opportunity_if_eligible(identifier))
if __name__ == "__main__":
usage_demo()
```
+ API の詳細については、AWS SDK for Python (Boto3) API リファレンスの「[UpdateOpportunity](https://docs.aws.amazon.com/goto/boto3/partnercentral-selling-2022-07-26/UpdateOpportunity)」を参照してください。**
## シナリオ
### オポチュニティの関連エンティティを更新する
次のコード例は、以下の操作方法を示しています。
+ 古いエンティティの関連付けを解除します。
+ 新しいエンティティを関連付けます。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/partner-central-api-sample-codes/python_preview/#code-examples)での設定と実行の方法を確認してください。
オポチュニティの関連エンティティを更新する
```
#!/usr/bin/env python
"""
Purpose
PC-API -17 Replacing a solution
"""
import logging
import boto3
import utils.helpers as helper
from botocore.client import ClientError
from utils.constants import CATALOG_TO_USE
serviceName = "partnercentral-selling"
partner_central_client = boto3.client(
service_name=serviceName,
region_name='us-east-1'
)
def replace_solution(original_entity_identifier, new_entity_identifier, opportunityIdentifier):
disassociate_opportunity_request ={
"Catalog": CATALOG_TO_USE,
"OpportunityIdentifier" : opportunityIdentifier,
"RelatedEntityType" : "Solutions",
"RelatedEntityIdentifier" : original_entity_identifier
}
associate_opportunity_request ={
"Catalog": CATALOG_TO_USE,
"OpportunityIdentifier" : opportunityIdentifier,
"RelatedEntityType" : "Solutions",
"RelatedEntityIdentifier" : new_entity_identifier
}
try:
# Perform an API call
response = partner_central_client.disassociate_opportunity(**disassociate_opportunity_request)
response = partner_central_client.associate_opportunity(**associate_opportunity_request)
return response
except ClientError as err:
# Catch all client exceptions
print(err.response)
def usage_demo():
original_entity_identifier = "S-0049999"
new_entity_identifier = "S-0050014"
opportunityIdentifier = "O4397574"
logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
print("-" * 88)
print("Replacing a solution.")
print("-" * 88)
helper.pretty_print_datetime(replace_solution(original_entity_identifier, new_entity_identifier, opportunityIdentifier))
if __name__ == "__main__":
usage_demo()
```
+ API の詳細については、『*AWS SDK for Python (Boto3) API リファレンス*』の以下のトピックを参照してください。
+ [AssociateOpportunity](https://docs.aws.amazon.com/goto/boto3/partnercentral-selling-2022-07-26/AssociateOpportunity)
+ [DisassociateOpportunity](https://docs.aws.amazon.com/goto/boto3/partnercentral-selling-2022-07-26/DisassociateOpportunity)
# SDK for Python (Boto3) を使用する Amazon Pinpoint の例
次のコード例は、Amazon Pinpoint AWS SDK for Python (Boto3) で を使用してアクションを実行し、一般的なシナリオを実装する方法を示しています。
*アクション*はより大きなプログラムからのコードの抜粋であり、コンテキスト内で実行する必要があります。アクションは個々のサービス機能を呼び出す方法を示していますが、コンテキスト内のアクションは、関連するシナリオで確認できます。
各例には完全なソースコードへのリンクが含まれており、コードの設定方法と実行方法に関する手順を確認できます。
**Topics**
+ [アクション](#actions)
## アクション
### `SendMessages`
次のコード例は、`SendMessages` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/pinpoint#code-examples)での設定と実行の方法を確認してください。
E メールメッセージを送信します。
```
import logging
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
def send_email_message(
pinpoint_client,
app_id,
sender,
to_addresses,
char_set,
subject,
html_message,
text_message,
):
"""
Sends an email message with HTML and plain text versions.
:param pinpoint_client: A Boto3 Pinpoint client.
:param app_id: The Amazon Pinpoint project ID to use when you send this message.
:param sender: The "From" address. This address must be verified in
Amazon Pinpoint in the AWS Region you're using to send email.
:param to_addresses: The addresses on the "To" line. If your Amazon Pinpoint account
is in the sandbox, these addresses must be verified.
:param char_set: The character encoding to use for the subject line and message
body of the email.
:param subject: The subject line of the email.
:param html_message: The body of the email for recipients whose email clients can
display HTML content.
:param text_message: The body of the email for recipients whose email clients
don't support HTML content.
:return: A dict of to_addresses and their message IDs.
"""
try:
response = pinpoint_client.send_messages(
ApplicationId=app_id,
MessageRequest={
"Addresses": {
to_address: {"ChannelType": "EMAIL"} for to_address in to_addresses
},
"MessageConfiguration": {
"EmailMessage": {
"FromAddress": sender,
"SimpleEmail": {
"Subject": {"Charset": char_set, "Data": subject},
"HtmlPart": {"Charset": char_set, "Data": html_message},
"TextPart": {"Charset": char_set, "Data": text_message},
},
}
},
},
)
except ClientError:
logger.exception("Couldn't send email.")
raise
else:
return {
to_address: message["MessageId"]
for to_address, message in response["MessageResponse"]["Result"].items()
}
def main():
app_id = "ce796be37f32f178af652b26eexample"
sender = "sender@example.com"
to_address = "recipient@example.com"
char_set = "UTF-8"
subject = "Amazon Pinpoint Test (SDK for Python (Boto3))"
text_message = """Amazon Pinpoint Test (SDK for Python)
-------------------------------------
This email was sent with Amazon Pinpoint using the AWS SDK for Python (Boto3).
For more information, see https://aws.amazon.com/sdk-for-python/
"""
html_message = """
Amazon Pinpoint Test (SDK for Python (Boto3)
This email was sent with
Amazon Pinpoint using the
AWS SDK for Python (Boto3).
"""
print("Sending email.")
message_ids = send_email_message(
boto3.client("pinpoint"),
app_id,
sender,
[to_address],
char_set,
subject,
html_message,
text_message,
)
print(f"Message sent! Message IDs: {message_ids}")
if __name__ == "__main__":
main()
```
SMS メッセージを送信します。
```
import logging
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
def send_sms_message(
pinpoint_client,
app_id,
origination_number,
destination_number,
message,
message_type,
):
"""
Sends an SMS message with Amazon Pinpoint.
:param pinpoint_client: A Boto3 Pinpoint client.
:param app_id: The Amazon Pinpoint project/application ID to use when you send
this message. The SMS channel must be enabled for the project or
application.
:param destination_number: The recipient's phone number in E.164 format.
:param origination_number: The phone number to send the message from. This phone
number must be associated with your Amazon Pinpoint
account and be in E.164 format.
:param message: The content of the SMS message.
:param message_type: The type of SMS message that you want to send. If you send
time-sensitive content, specify TRANSACTIONAL. If you send
marketing-related content, specify PROMOTIONAL.
:return: The ID of the message.
"""
try:
response = pinpoint_client.send_messages(
ApplicationId=app_id,
MessageRequest={
"Addresses": {destination_number: {"ChannelType": "SMS"}},
"MessageConfiguration": {
"SMSMessage": {
"Body": message,
"MessageType": message_type,
"OriginationNumber": origination_number,
}
},
},
)
except ClientError:
logger.exception("Couldn't send message.")
raise
else:
return response["MessageResponse"]["Result"][destination_number]["MessageId"]
def main():
app_id = "ce796be37f32f178af652b26eexample"
origination_number = "+12065550199"
destination_number = "+14255550142"
message = (
"This is a sample message sent from Amazon Pinpoint by using the AWS SDK for "
"Python (Boto 3)."
)
message_type = "TRANSACTIONAL"
print("Sending SMS message.")
message_id = send_sms_message(
boto3.client("pinpoint"),
app_id,
origination_number,
destination_number,
message,
message_type,
)
print(f"Message sent! Message ID: {message_id}.")
if __name__ == "__main__":
main()
```
既存の E メールテンプレートを使用して E メールメッセージを送信します。
```
import logging
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
def send_templated_email_message(
pinpoint_client, project_id, sender, to_addresses, template_name, template_version
):
"""
Sends an email message with HTML and plain text versions.
:param pinpoint_client: A Boto3 Pinpoint client.
:param project_id: The Amazon Pinpoint project ID to use when you send this message.
:param sender: The "From" address. This address must be verified in
Amazon Pinpoint in the AWS Region you're using to send email.
:param to_addresses: The addresses on the "To" line. If your Amazon Pinpoint
account is in the sandbox, these addresses must be verified.
:param template_name: The name of the email template to use when sending the message.
:param template_version: The version number of the message template.
:return: A dict of to_addresses and their message IDs.
"""
try:
response = pinpoint_client.send_messages(
ApplicationId=project_id,
MessageRequest={
"Addresses": {
to_address: {"ChannelType": "EMAIL"} for to_address in to_addresses
},
"MessageConfiguration": {"EmailMessage": {"FromAddress": sender}},
"TemplateConfiguration": {
"EmailTemplate": {
"Name": template_name,
"Version": template_version,
}
},
},
)
except ClientError:
logger.exception("Couldn't send email.")
raise
else:
return {
to_address: message["MessageId"]
for to_address, message in response["MessageResponse"]["Result"].items()
}
def main():
project_id = "296b04b342374fceb661bf494example"
sender = "sender@example.com"
to_addresses = ["recipient@example.com"]
template_name = "My_Email_Template"
template_version = "1"
print("Sending email.")
message_ids = send_templated_email_message(
boto3.client("pinpoint"),
project_id,
sender,
to_addresses,
template_name,
template_version,
)
print(f"Message sent! Message IDs: {message_ids}")
if __name__ == "__main__":
main()
```
既存の SMS テンプレートを使用してテキストメッセージを送信します。
```
import logging
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
def send_templated_sms_message(
pinpoint_client,
project_id,
destination_number,
message_type,
origination_number,
template_name,
template_version,
):
"""
Sends an SMS message to a specific phone number using a pre-defined template.
:param pinpoint_client: A Boto3 Pinpoint client.
:param project_id: An Amazon Pinpoint project (application) ID.
:param destination_number: The phone number to send the message to.
:param message_type: The type of SMS message (promotional or transactional).
:param origination_number: The phone number that the message is sent from.
:param template_name: The name of the SMS template to use when sending the message.
:param template_version: The version number of the message template.
:return The ID of the message.
"""
try:
response = pinpoint_client.send_messages(
ApplicationId=project_id,
MessageRequest={
"Addresses": {destination_number: {"ChannelType": "SMS"}},
"MessageConfiguration": {
"SMSMessage": {
"MessageType": message_type,
"OriginationNumber": origination_number,
}
},
"TemplateConfiguration": {
"SMSTemplate": {"Name": template_name, "Version": template_version}
},
},
)
except ClientError:
logger.exception("Couldn't send message.")
raise
else:
return response["MessageResponse"]["Result"][destination_number]["MessageId"]
def main():
region = "us-east-1"
origination_number = "+18555550001"
destination_number = "+14255550142"
project_id = "7353f53e6885409fa32d07cedexample"
message_type = "TRANSACTIONAL"
template_name = "My_SMS_Template"
template_version = "1"
message_id = send_templated_sms_message(
boto3.client("pinpoint", region_name=region),
project_id,
destination_number,
message_type,
origination_number,
template_name,
template_version,
)
print(f"Message sent! Message ID: {message_id}.")
if __name__ == "__main__":
main()
```
+ API の詳細については、**「AWS SDK for Python (Boto3) API リファレンス」の「[SendMessage](https://docs.aws.amazon.com/goto/boto3/pinpoint-2016-12-01/SendMessages)」を参照してください。
# SDK for Python (Boto3) を使用する Amazon Pinpoint および音声 API の例
次のコード例は、Amazon Pinpoint SMS および音声 API AWS SDK for Python (Boto3) で を使用してアクションを実行し、一般的なシナリオを実装する方法を示しています。
*アクション*はより大きなプログラムからのコードの抜粋であり、コンテキスト内で実行する必要があります。アクションは個々のサービス機能を呼び出す方法を示していますが、コンテキスト内のアクションは、関連するシナリオで確認できます。
各例には完全なソースコードへのリンクが含まれており、コードの設定方法と実行方法に関する手順を確認できます。
**Topics**
+ [アクション](#actions)
## アクション
### `SendVoiceMessage`
次のコード例は、`SendVoiceMessage` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/pinpoint-sms-voice#code-examples)での設定と実行の方法を確認してください。
```
import logging
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
def send_voice_message(
sms_voice_client,
origination_number,
caller_id,
destination_number,
language_code,
voice_id,
ssml_message,
):
"""
Sends a voice message using speech synthesis provided by Amazon Polly.
:param sms_voice_client: A Boto3 PinpointSMSVoice client.
:param origination_number: The phone number that the message is sent from.
The phone number must be associated with your Amazon
Pinpoint account and be in E.164 format.
:param caller_id: The phone number that you want to appear on the recipient's
device. The phone number must be associated with your Amazon
Pinpoint account and be in E.164 format.
:param destination_number: The recipient's phone number. Specify the phone
number in E.164 format.
:param language_code: The language to use when sending the message.
:param voice_id: The Amazon Polly voice that you want to use to send the message.
:param ssml_message: The content of the message. This example uses SSML to control
certain aspects of the message, such as the volume and the
speech rate. The message must not contain line breaks.
:return: The ID of the message.
"""
try:
response = sms_voice_client.send_voice_message(
DestinationPhoneNumber=destination_number,
OriginationPhoneNumber=origination_number,
CallerId=caller_id,
Content={
"SSMLMessage": {
"LanguageCode": language_code,
"VoiceId": voice_id,
"Text": ssml_message,
}
},
)
except ClientError:
logger.exception(
"Couldn't send message from %s to %s.",
origination_number,
destination_number,
)
raise
else:
return response["MessageId"]
def main():
origination_number = "+12065550110"
caller_id = "+12065550199"
destination_number = "+12065550142"
language_code = "en-US"
voice_id = "Matthew"
ssml_message = (
""
"This is a test message sent from Amazon Pinpoint "
"using the AWS SDK for Python (Boto3). "
"Thank you for listening."
""
""
)
print(f"Sending voice message from {origination_number} to {destination_number}.")
message_id = send_voice_message(
boto3.client("pinpoint-sms-voice"),
origination_number,
caller_id,
destination_number,
language_code,
voice_id,
ssml_message,
)
print(f"Message sent!\nMessage ID: {message_id}")
if __name__ == "__main__":
main()
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[SendVoiceMessage](https://docs.aws.amazon.com/goto/boto3/pinpoint-sms-voice-2018-09-05/SendVoiceMessage)」を参照してください。
# SDK for Python (Boto3) を使用する Amazon Polly の例
次のコード例は、Amazon Polly AWS SDK for Python (Boto3) で を使用してアクションを実行し、一般的なシナリオを実装する方法を示しています。
*アクション*はより大きなプログラムからのコードの抜粋であり、コンテキスト内で実行する必要があります。アクションは個々のサービス機能を呼び出す方法を示していますが、コンテキスト内のアクションは、関連するシナリオで確認できます。
*シナリオ*は、1 つのサービス内から、または他の AWS のサービスと組み合わせて複数の関数を呼び出し、特定のタスクを実行する方法を示すコード例です。
各例には完全なソースコードへのリンクが含まれており、コードの設定方法と実行方法に関する手順を確認できます。
**Topics**
+ [アクション](#actions)
+ [シナリオ](#scenarios)
## アクション
### `DescribeVoices`
次のコード例は、`DescribeVoices` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/polly#code-examples)での設定と実行の方法を確認してください。
```
class PollyWrapper:
"""Encapsulates Amazon Polly functions."""
def __init__(self, polly_client, s3_resource):
"""
:param polly_client: A Boto3 Amazon Polly client.
:param s3_resource: A Boto3 Amazon Simple Storage Service (Amazon S3) resource.
"""
self.polly_client = polly_client
self.s3_resource = s3_resource
self.voice_metadata = None
def describe_voices(self):
"""
Gets metadata about available voices.
:return: The list of voice metadata.
"""
try:
response = self.polly_client.describe_voices()
self.voice_metadata = response["Voices"]
logger.info("Got metadata about %s voices.", len(self.voice_metadata))
except ClientError:
logger.exception("Couldn't get voice metadata.")
raise
else:
return self.voice_metadata
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[DescribeVoices](https://docs.aws.amazon.com/goto/boto3/polly-2016-06-10/DescribeVoices)」を参照してください。
### `GetLexicon`
次のコード例は、`GetLexicon` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/polly#code-examples)での設定と実行の方法を確認してください。
```
class PollyWrapper:
"""Encapsulates Amazon Polly functions."""
def __init__(self, polly_client, s3_resource):
"""
:param polly_client: A Boto3 Amazon Polly client.
:param s3_resource: A Boto3 Amazon Simple Storage Service (Amazon S3) resource.
"""
self.polly_client = polly_client
self.s3_resource = s3_resource
self.voice_metadata = None
def get_lexicon(self, name):
"""
Gets metadata and contents of an existing lexicon.
:param name: The name of the lexicon to retrieve.
:return: The retrieved lexicon.
"""
try:
response = self.polly_client.get_lexicon(Name=name)
logger.info("Got lexicon %s.", name)
except ClientError:
logger.exception("Couldn't get lexicon %s.", name)
raise
else:
return response
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[GetLexicon](https://docs.aws.amazon.com/goto/boto3/polly-2016-06-10/GetLexicon)」を参照してください。
### `GetSpeechSynthesisTask`
次のコード例は、`GetSpeechSynthesisTask` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/polly#code-examples)での設定と実行の方法を確認してください。
```
class PollyWrapper:
"""Encapsulates Amazon Polly functions."""
def __init__(self, polly_client, s3_resource):
"""
:param polly_client: A Boto3 Amazon Polly client.
:param s3_resource: A Boto3 Amazon Simple Storage Service (Amazon S3) resource.
"""
self.polly_client = polly_client
self.s3_resource = s3_resource
self.voice_metadata = None
def get_speech_synthesis_task(self, task_id):
"""
Gets metadata about an asynchronous speech synthesis task, such as its status.
:param task_id: The ID of the task to retrieve.
:return: Metadata about the task.
"""
try:
response = self.polly_client.get_speech_synthesis_task(TaskId=task_id)
task = response["SynthesisTask"]
logger.info("Got synthesis task. Status is %s.", task["TaskStatus"])
except ClientError:
logger.exception("Couldn't get synthesis task %s.", task_id)
raise
else:
return task
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[GetSpeechSynthesisTask](https://docs.aws.amazon.com/goto/boto3/polly-2016-06-10/GetSpeechSynthesisTask)」を参照してください。
### `ListLexicons`
次のコード例は、`ListLexicons` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/polly#code-examples)での設定と実行の方法を確認してください。
```
class PollyWrapper:
"""Encapsulates Amazon Polly functions."""
def __init__(self, polly_client, s3_resource):
"""
:param polly_client: A Boto3 Amazon Polly client.
:param s3_resource: A Boto3 Amazon Simple Storage Service (Amazon S3) resource.
"""
self.polly_client = polly_client
self.s3_resource = s3_resource
self.voice_metadata = None
def list_lexicons(self):
"""
Lists lexicons in the current account.
:return: The list of lexicons.
"""
try:
response = self.polly_client.list_lexicons()
lexicons = response["Lexicons"]
logger.info("Got %s lexicons.", len(lexicons))
except ClientError:
logger.exception(
"Couldn't get %s.",
)
raise
else:
return lexicons
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[ListLexicons](https://docs.aws.amazon.com/goto/boto3/polly-2016-06-10/ListLexicons)」を参照してください。
### `PutLexicon`
次のコード例は、`PutLexicon` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/polly#code-examples)での設定と実行の方法を確認してください。
```
class PollyWrapper:
"""Encapsulates Amazon Polly functions."""
def __init__(self, polly_client, s3_resource):
"""
:param polly_client: A Boto3 Amazon Polly client.
:param s3_resource: A Boto3 Amazon Simple Storage Service (Amazon S3) resource.
"""
self.polly_client = polly_client
self.s3_resource = s3_resource
self.voice_metadata = None
def create_lexicon(self, name, content):
"""
Creates a lexicon with the specified content. A lexicon contains custom
pronunciations.
:param name: The name of the lexicon.
:param content: The content of the lexicon.
"""
try:
self.polly_client.put_lexicon(Name=name, Content=content)
logger.info("Created lexicon %s.", name)
except ClientError:
logger.exception("Couldn't create lexicon %s.")
raise
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[PutLexicon](https://docs.aws.amazon.com/goto/boto3/polly-2016-06-10/PutLexicon)」を参照してください。
### `StartSpeechSynthesisTask`
次のコード例は、`StartSpeechSynthesisTask` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/polly#code-examples)での設定と実行の方法を確認してください。
```
class PollyWrapper:
"""Encapsulates Amazon Polly functions."""
def __init__(self, polly_client, s3_resource):
"""
:param polly_client: A Boto3 Amazon Polly client.
:param s3_resource: A Boto3 Amazon Simple Storage Service (Amazon S3) resource.
"""
self.polly_client = polly_client
self.s3_resource = s3_resource
self.voice_metadata = None
def do_synthesis_task(
self,
text,
engine,
voice,
audio_format,
s3_bucket,
lang_code=None,
include_visemes=False,
wait_callback=None,
):
"""
Start an asynchronous task to synthesize speech or speech marks, wait for
the task to complete, retrieve the output from Amazon S3, and return the
data.
An asynchronous task is required when the text is too long for near-real time
synthesis.
:param text: The text to synthesize.
:param engine: The kind of engine used. Can be standard or neural.
:param voice: The ID of the voice to use.
:param audio_format: The audio format to return for synthesized speech. When
speech marks are synthesized, the output format is JSON.
:param s3_bucket: The name of an existing Amazon S3 bucket that you have
write access to. Synthesis output is written to this bucket.
:param lang_code: The language code of the voice to use. This has an effect
only when a bilingual voice is selected.
:param include_visemes: When True, a second request is made to Amazon Polly
to synthesize a list of visemes, using the specified
text and voice. A viseme represents the visual position
of the face and mouth when saying part of a word.
:param wait_callback: A callback function that is called periodically during
task processing, to give the caller an opportunity to
take action, such as to display status.
:return: The audio stream that contains the synthesized speech and a list
of visemes that are associated with the speech audio.
"""
try:
kwargs = {
"Engine": engine,
"OutputFormat": audio_format,
"OutputS3BucketName": s3_bucket,
"Text": text,
"VoiceId": voice,
}
if lang_code is not None:
kwargs["LanguageCode"] = lang_code
response = self.polly_client.start_speech_synthesis_task(**kwargs)
speech_task = response["SynthesisTask"]
logger.info("Started speech synthesis task %s.", speech_task["TaskId"])
viseme_task = None
if include_visemes:
kwargs["OutputFormat"] = "json"
kwargs["SpeechMarkTypes"] = ["viseme"]
response = self.polly_client.start_speech_synthesis_task(**kwargs)
viseme_task = response["SynthesisTask"]
logger.info("Started viseme synthesis task %s.", viseme_task["TaskId"])
except ClientError:
logger.exception("Couldn't start synthesis task.")
raise
else:
bucket = self.s3_resource.Bucket(s3_bucket)
audio_stream = self._wait_for_task(
10, speech_task["TaskId"], "speech", wait_callback, bucket
)
visemes = None
if include_visemes:
viseme_data = self._wait_for_task(
10, viseme_task["TaskId"], "viseme", wait_callback, bucket
)
visemes = [
json.loads(v) for v in viseme_data.read().decode().split() if v
]
return audio_stream, visemes
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[StartSpeechSynthesisTask](https://docs.aws.amazon.com/goto/boto3/polly-2016-06-10/StartSpeechSynthesisTask)」を参照してください。
### `SynthesizeSpeech`
次のコード例は、`SynthesizeSpeech` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/polly#code-examples)での設定と実行の方法を確認してください。
```
class PollyWrapper:
"""Encapsulates Amazon Polly functions."""
def __init__(self, polly_client, s3_resource):
"""
:param polly_client: A Boto3 Amazon Polly client.
:param s3_resource: A Boto3 Amazon Simple Storage Service (Amazon S3) resource.
"""
self.polly_client = polly_client
self.s3_resource = s3_resource
self.voice_metadata = None
def synthesize(
self, text, engine, voice, audio_format, lang_code=None, include_visemes=False
):
"""
Synthesizes speech or speech marks from text, using the specified voice.
:param text: The text to synthesize.
:param engine: The kind of engine used. Can be standard or neural.
:param voice: The ID of the voice to use.
:param audio_format: The audio format to return for synthesized speech. When
speech marks are synthesized, the output format is JSON.
:param lang_code: The language code of the voice to use. This has an effect
only when a bilingual voice is selected.
:param include_visemes: When True, a second request is made to Amazon Polly
to synthesize a list of visemes, using the specified
text and voice. A viseme represents the visual position
of the face and mouth when saying part of a word.
:return: The audio stream that contains the synthesized speech and a list
of visemes that are associated with the speech audio.
"""
try:
kwargs = {
"Engine": engine,
"OutputFormat": audio_format,
"Text": text,
"VoiceId": voice,
}
if lang_code is not None:
kwargs["LanguageCode"] = lang_code
response = self.polly_client.synthesize_speech(**kwargs)
audio_stream = response["AudioStream"]
logger.info("Got audio stream spoken by %s.", voice)
visemes = None
if include_visemes:
kwargs["OutputFormat"] = "json"
kwargs["SpeechMarkTypes"] = ["viseme"]
response = self.polly_client.synthesize_speech(**kwargs)
visemes = [
json.loads(v)
for v in response["AudioStream"].read().decode().split()
if v
]
logger.info("Got %s visemes.", len(visemes))
except ClientError:
logger.exception("Couldn't get audio stream.")
raise
else:
return audio_stream, visemes
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[SynthesizeSpeech](https://docs.aws.amazon.com/goto/boto3/polly-2016-06-10/SynthesizeSpeech)」を参照してください。
## シナリオ
### リップシンクアプリケーションを作成する
次のコード例は、Amazon Polly でリップシンクアプリケーションを作成する方法を示しています。
**SDK for Python (Boto3)**
Amazon Polly と Tkinter を使用して、Amazon Polly で合成された音声とともに音声をアニメーション表示するリップシンクアプリケーションを作成する方法を説明します。リップシンクは、合成された音声と一致する口形素のリストを Amazon Polly にリクエストすることで実現されます。
+ Amazon Polly から音声メタデータを取得し、Tkinter アプリケーションに表示します。
+ Amazon Polly から合成音声とそれに対応する口形素の音声記号を取得できます。
+ 口の動きが同期した音声を、アニメーション化された顔で再生します。
+ 長いテキストに対する非同期合成タスクを送信し、Amazon Simple Storage Service (Amazon S3) バケットから出力を取得します。
完全なソースコードとセットアップおよび実行の手順については、[GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/polly#code-examples) で完全な例を参照してください。
**この例で使用されているサービス**
+ Amazon Polly
# SDK for Python (Boto3) を使用する Amazon RDS の例
次のコード例は、Amazon RDS AWS SDK for Python (Boto3) で を使用してアクションを実行し、一般的なシナリオを実装する方法を示しています。
*基本* は、重要なオペレーションをサービス内で実行する方法を示すコード例です。
*アクション*はより大きなプログラムからのコードの抜粋であり、コンテキスト内で実行する必要があります。アクションは個々のサービス機能を呼び出す方法を示していますが、コンテキスト内のアクションは、関連するシナリオで確認できます。
*シナリオ*は、1 つのサービス内から、または他の AWS のサービスと組み合わせて複数の関数を呼び出し、特定のタスクを実行する方法を示すコード例です。
各例には完全なソースコードへのリンクが含まれており、コンテキスト内でコードを設定および実行する方法の手順を確認できます。
**Topics**
+ [はじめに](#get_started)
+ [基本](#basics)
+ [アクション](#actions)
+ [シナリオ](#scenarios)
+ [サーバーレスサンプル](#serverless_examples)
## はじめに
### Hello Amazon RDS
次のコード例は、Amazon RDS の使用を開始する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rds#code-examples)での設定と実行の方法を確認してください。
```
"""
Purpose
Shows how to use the AWS SDK for Python (Boto3) with the Amazon Relational Database Service
(Amazon RDS) to list the databases in your account.
"""
import boto3
from botocore.exceptions import ClientError
# Create an RDS client
rds_client = boto3.client("rds")
# Create a paginator for the describe_db_instances operation
paginator = rds_client.get_paginator("describe_db_instances")
try:
# Use the paginator to get a list of DB instances
response_iterator = paginator.paginate(
PaginationConfig={
"MaxItems": 123,
"PageSize": 50, # Adjust PageSize as needed
"StartingToken": None,
}
)
# Iterate through the pages of the response
instances_found = False
for page in response_iterator:
if "DBInstances" in page and page["DBInstances"]:
instances_found = True
print("Your RDS instances are:")
for db in page["DBInstances"]:
print(db["DBInstanceIdentifier"])
if not instances_found:
print("No RDS instances found!")
except ClientError as e:
print(f"Couldn't list RDS instances. Here's why: {e.response['Error']['Message']}")
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[DescribeDBInstances](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/DescribeDBInstances)」を参照してください。
## 基本
### 基本を学ぶ
次のコード例は、以下の操作方法を示しています。
+ カスタム DB パラメータグループを作成し、パラメータ値を設定します。
+ パラメータグループを使用するように設定した DB インスタンスを作成します。DB インスタンスにはデータベースも含まれています。
+ インスタンスのスナップショットを取得します。
+ インスタンスとパラメータグループを削除します。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rds#code-examples)での設定と実行の方法を確認してください。
コマンドプロンプトからインタラクティブなシナリオを実行します。
```
class RdsInstanceScenario:
"""Runs a scenario that shows how to get started using Amazon RDS DB instances."""
def __init__(self, instance_wrapper):
"""
:param instance_wrapper: An object that wraps Amazon RDS DB instance actions.
"""
self.instance_wrapper = instance_wrapper
def create_parameter_group(self, parameter_group_name, db_engine):
"""
Shows how to get available engine versions for a specified database engine and
create a DB parameter group that is compatible with a selected engine family.
:param parameter_group_name: The name given to the newly created parameter group.
:param db_engine: The database engine to use as a basis.
:return: The newly created parameter group.
"""
print(
f"Checking for an existing DB instance parameter group named {parameter_group_name}."
)
parameter_group = self.instance_wrapper.get_parameter_group(
parameter_group_name
)
if parameter_group is None:
print(f"Getting available database engine versions for {db_engine}.")
engine_versions = self.instance_wrapper.get_engine_versions(db_engine)
families = list({ver["DBParameterGroupFamily"] for ver in engine_versions})
family_index = q.choose("Which family do you want to use? ", families)
print(f"Creating a parameter group.")
self.instance_wrapper.create_parameter_group(
parameter_group_name, families[family_index], "Example parameter group."
)
parameter_group = self.instance_wrapper.get_parameter_group(
parameter_group_name
)
print(f"Parameter group {parameter_group['DBParameterGroupName']}:")
pp(parameter_group)
print("-" * 88)
return parameter_group
def update_parameters(self, parameter_group_name):
"""
Shows how to get the parameters contained in a custom parameter group and
update some of the parameter values in the group.
:param parameter_group_name: The name of the parameter group to query and modify.
"""
print("Let's set some parameter values in your parameter group.")
auto_inc_parameters = self.instance_wrapper.get_parameters(
parameter_group_name, name_prefix="auto_increment"
)
update_params = []
for auto_inc in auto_inc_parameters:
if auto_inc["IsModifiable"] and auto_inc["DataType"] == "integer":
print(f"The {auto_inc['ParameterName']} parameter is described as:")
print(f"\t{auto_inc['Description']}")
param_range = auto_inc["AllowedValues"].split("-")
auto_inc["ParameterValue"] = str(
q.ask(
f"Enter a value between {param_range[0]} and {param_range[1]}: ",
q.is_int,
q.in_range(int(param_range[0]), int(param_range[1])),
)
)
update_params.append(auto_inc)
self.instance_wrapper.update_parameters(parameter_group_name, update_params)
print(
"You can get a list of parameters you've set by specifying a source of 'user'."
)
user_parameters = self.instance_wrapper.get_parameters(
parameter_group_name, source="user"
)
pp(user_parameters)
print("-" * 88)
def create_instance(self, instance_name, db_name, db_engine, parameter_group):
"""
Shows how to create a DB instance that contains a database of a specified
type and is configured to use a custom DB parameter group.
:param instance_name: The name given to the newly created DB instance.
:param db_name: The name given to the created database.
:param db_engine: The engine of the created database.
:param parameter_group: The parameter group that is associated with the DB instance.
:return: The newly created DB instance.
"""
print("Checking for an existing DB instance.")
db_inst = self.instance_wrapper.get_db_instance(instance_name)
if db_inst is None:
print("Let's create a DB instance.")
admin_username = q.ask(
"Enter an administrator user name for the database: ", q.non_empty
)
admin_password = q.ask(
"Enter a password for the administrator (at least 8 characters): ",
q.non_empty,
)
engine_versions = self.instance_wrapper.get_engine_versions(
db_engine, parameter_group["DBParameterGroupFamily"]
)
engine_choices = [ver["EngineVersion"] for ver in engine_versions]
print("The available engines for your parameter group are:")
engine_index = q.choose("Which engine do you want to use? ", engine_choices)
engine_selection = engine_versions[engine_index]
print(
"The available micro DB instance classes for your database engine are:"
)
inst_opts = self.instance_wrapper.get_orderable_instances(
engine_selection["Engine"], engine_selection["EngineVersion"]
)
inst_choices = list(
{
opt["DBInstanceClass"]
for opt in inst_opts
if "micro" in opt["DBInstanceClass"]
}
)
inst_index = q.choose(
"Which micro DB instance class do you want to use? ", inst_choices
)
group_name = parameter_group["DBParameterGroupName"]
storage_type = "standard"
allocated_storage = 5
print(
f"Creating a DB instance named {instance_name} and database {db_name}.\n"
f"The DB instance is configured to use your custom parameter group {group_name},\n"
f"selected engine {engine_selection['EngineVersion']},\n"
f"selected DB instance class {inst_choices[inst_index]},"
f"and {allocated_storage} GiB of {storage_type} storage.\n"
f"This typically takes several minutes."
)
db_inst = self.instance_wrapper.create_db_instance(
db_name,
instance_name,
group_name,
engine_selection["Engine"],
engine_selection["EngineVersion"],
inst_choices[inst_index],
storage_type,
allocated_storage,
admin_username,
admin_password,
)
while db_inst.get("DBInstanceStatus") != "available":
wait(10)
db_inst = self.instance_wrapper.get_db_instance(instance_name)
print("Instance data:")
pp(db_inst)
print("-" * 88)
return db_inst
@staticmethod
def display_connection(db_inst):
"""
Displays connection information about a DB instance and tips on how to
connect to it.
:param db_inst: The DB instance to display.
"""
print(
"You can now connect to your database using your favorite MySql client.\n"
"One way to connect is by using the 'mysql' shell on an Amazon EC2 instance\n"
"that is running in the same VPC as your DB instance. Pass the endpoint,\n"
"port, and administrator user name to 'mysql' and enter your password\n"
"when prompted:\n"
)
print(
f"\n\tmysql -h {db_inst['Endpoint']['Address']} -P {db_inst['Endpoint']['Port']} "
f"-u {db_inst['MasterUsername']} -p\n"
)
print(
"For more information, see the User Guide for Amazon RDS:\n"
"\thttps://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_GettingStarted.CreatingConnecting.MySQL.html#CHAP_GettingStarted.Connecting.MySQL"
)
print("-" * 88)
def create_snapshot(self, instance_name):
"""
Shows how to create a DB instance snapshot and wait until it's available.
:param instance_name: The name of a DB instance to snapshot.
"""
if q.ask(
"Do you want to create a snapshot of your DB instance (y/n)? ", q.is_yesno
):
snapshot_id = f"{instance_name}-{uuid.uuid4()}"
print(
f"Creating a snapshot named {snapshot_id}. This typically takes a few minutes."
)
snapshot = self.instance_wrapper.create_snapshot(snapshot_id, instance_name)
while snapshot.get("Status") != "available":
wait(10)
snapshot = self.instance_wrapper.get_snapshot(snapshot_id)
pp(snapshot)
print("-" * 88)
def cleanup(self, db_inst, parameter_group_name):
"""
Shows how to clean up a DB instance and parameter group.
Before the parameter group can be deleted, all associated DB instances must first
be deleted.
:param db_inst: The DB instance to delete.
:param parameter_group_name: The DB parameter group to delete.
"""
if q.ask(
"\nDo you want to delete the DB instance and parameter group (y/n)? ",
q.is_yesno,
):
print(f"Deleting DB instance {db_inst['DBInstanceIdentifier']}.")
self.instance_wrapper.delete_db_instance(db_inst["DBInstanceIdentifier"])
print(
"Waiting for the DB instance to delete. This typically takes several minutes."
)
while db_inst is not None:
wait(10)
db_inst = self.instance_wrapper.get_db_instance(
db_inst["DBInstanceIdentifier"]
)
print(f"Deleting parameter group {parameter_group_name}.")
self.instance_wrapper.delete_parameter_group(parameter_group_name)
def run_scenario(self, db_engine, parameter_group_name, instance_name, db_name):
logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
print("-" * 88)
print(
"Welcome to the Amazon Relational Database Service (Amazon RDS)\n"
"get started with DB instances demo."
)
print("-" * 88)
parameter_group = self.create_parameter_group(parameter_group_name, db_engine)
self.update_parameters(parameter_group_name)
db_inst = self.create_instance(
instance_name, db_name, db_engine, parameter_group
)
self.display_connection(db_inst)
self.create_snapshot(instance_name)
self.cleanup(db_inst, parameter_group_name)
print("\nThanks for watching!")
print("-" * 88)
if __name__ == "__main__":
try:
scenario = RdsInstanceScenario(InstanceWrapper.from_client())
scenario.run_scenario(
"mysql",
"doc-example-parameter-group",
"doc-example-instance",
"docexampledb",
)
except Exception:
logging.exception("Something went wrong with the demo.")
```
Amazon RDS アクションを管理するためにシナリオによって呼び出される関数を定義します。
```
class InstanceWrapper:
"""Encapsulates Amazon RDS DB instance actions."""
def __init__(self, rds_client):
"""
:param rds_client: A Boto3 Amazon RDS client.
"""
self.rds_client = rds_client
@classmethod
def from_client(cls):
"""
Instantiates this class from a Boto3 client.
"""
rds_client = boto3.client("rds")
return cls(rds_client)
def get_parameter_group(self, parameter_group_name):
"""
Gets a DB parameter group.
:param parameter_group_name: The name of the parameter group to retrieve.
:return: The parameter group.
"""
try:
response = self.rds_client.describe_db_parameter_groups(
DBParameterGroupName=parameter_group_name
)
parameter_group = response["DBParameterGroups"][0]
except ClientError as err:
if err.response["Error"]["Code"] == "DBParameterGroupNotFound":
logger.info("Parameter group %s does not exist.", parameter_group_name)
else:
logger.error(
"Couldn't get parameter group %s. Here's why: %s: %s",
parameter_group_name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return parameter_group
def create_parameter_group(
self, parameter_group_name, parameter_group_family, description
):
"""
Creates a DB parameter group that is based on the specified parameter group
family.
:param parameter_group_name: The name of the newly created parameter group.
:param parameter_group_family: The family that is used as the basis of the new
parameter group.
:param description: A description given to the parameter group.
:return: Data about the newly created parameter group.
"""
try:
response = self.rds_client.create_db_parameter_group(
DBParameterGroupName=parameter_group_name,
DBParameterGroupFamily=parameter_group_family,
Description=description,
)
except ClientError as err:
logger.error(
"Couldn't create parameter group %s. Here's why: %s: %s",
parameter_group_name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return response
def delete_parameter_group(self, parameter_group_name):
"""
Deletes a DB parameter group.
:param parameter_group_name: The name of the parameter group to delete.
:return: Data about the parameter group.
"""
try:
self.rds_client.delete_db_parameter_group(
DBParameterGroupName=parameter_group_name
)
except ClientError as err:
logger.error(
"Couldn't delete parameter group %s. Here's why: %s: %s",
parameter_group_name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
def get_parameters(self, parameter_group_name, name_prefix="", source=None):
"""
Gets the parameters that are contained in a DB parameter group.
:param parameter_group_name: The name of the parameter group to query.
:param name_prefix: When specified, the retrieved list of parameters is filtered
to contain only parameters that start with this prefix.
:param source: When specified, only parameters from this source are retrieved.
For example, a source of 'user' retrieves only parameters that
were set by a user.
:return: The list of requested parameters.
"""
try:
kwargs = {"DBParameterGroupName": parameter_group_name}
if source is not None:
kwargs["Source"] = source
parameters = []
paginator = self.rds_client.get_paginator("describe_db_parameters")
for page in paginator.paginate(**kwargs):
parameters += [
p
for p in page["Parameters"]
if p["ParameterName"].startswith(name_prefix)
]
except ClientError as err:
logger.error(
"Couldn't get parameters for %s. Here's why: %s: %s",
parameter_group_name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return parameters
def update_parameters(self, parameter_group_name, update_parameters):
"""
Updates parameters in a custom DB parameter group.
:param parameter_group_name: The name of the parameter group to update.
:param update_parameters: The parameters to update in the group.
:return: Data about the modified parameter group.
"""
try:
response = self.rds_client.modify_db_parameter_group(
DBParameterGroupName=parameter_group_name, Parameters=update_parameters
)
except ClientError as err:
logger.error(
"Couldn't update parameters in %s. Here's why: %s: %s",
parameter_group_name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return response
def create_snapshot(self, snapshot_id, instance_id):
"""
Creates a snapshot of a DB instance.
:param snapshot_id: The ID to give the created snapshot.
:param instance_id: The ID of the DB instance to snapshot.
:return: Data about the newly created snapshot.
"""
try:
response = self.rds_client.create_db_snapshot(
DBSnapshotIdentifier=snapshot_id, DBInstanceIdentifier=instance_id
)
snapshot = response["DBSnapshot"]
except ClientError as err:
logger.error(
"Couldn't create snapshot of %s. Here's why: %s: %s",
instance_id,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return snapshot
def get_snapshot(self, snapshot_id):
"""
Gets a DB instance snapshot.
:param snapshot_id: The ID of the snapshot to retrieve.
:return: The retrieved snapshot.
"""
try:
response = self.rds_client.describe_db_snapshots(
DBSnapshotIdentifier=snapshot_id
)
snapshot = response["DBSnapshots"][0]
except ClientError as err:
logger.error(
"Couldn't get snapshot %s. Here's why: %s: %s",
snapshot_id,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return snapshot
def get_engine_versions(self, engine, parameter_group_family=None):
"""
Gets database engine versions that are available for the specified engine
and parameter group family.
:param engine: The database engine to look up.
:param parameter_group_family: When specified, restricts the returned list of
engine versions to those that are compatible with
this parameter group family.
:return: The list of database engine versions.
"""
try:
kwargs = {"Engine": engine}
if parameter_group_family is not None:
kwargs["DBParameterGroupFamily"] = parameter_group_family
response = self.rds_client.describe_db_engine_versions(**kwargs)
versions = response["DBEngineVersions"]
except ClientError as err:
logger.error(
"Couldn't get engine versions for %s. Here's why: %s: %s",
engine,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return versions
def get_orderable_instances(self, db_engine, db_engine_version):
"""
Gets DB instance options that can be used to create DB instances that are
compatible with a set of specifications.
:param db_engine: The database engine that must be supported by the DB instance.
:param db_engine_version: The engine version that must be supported by the DB instance.
:return: The list of DB instance options that can be used to create a compatible DB instance.
"""
try:
inst_opts = []
paginator = self.rds_client.get_paginator(
"describe_orderable_db_instance_options"
)
for page in paginator.paginate(
Engine=db_engine, EngineVersion=db_engine_version
):
inst_opts += page["OrderableDBInstanceOptions"]
except ClientError as err:
logger.error(
"Couldn't get orderable DB instances. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return inst_opts
def get_db_instance(self, instance_id):
"""
Gets data about a DB instance.
:param instance_id: The ID of the DB instance to retrieve.
:return: The retrieved DB instance.
"""
try:
response = self.rds_client.describe_db_instances(
DBInstanceIdentifier=instance_id
)
db_inst = response["DBInstances"][0]
except ClientError as err:
if err.response["Error"]["Code"] == "DBInstanceNotFound":
logger.info("Instance %s does not exist.", instance_id)
else:
logger.error(
"Couldn't get DB instance %s. Here's why: %s: %s",
instance_id,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return db_inst
def create_db_instance(
self,
db_name,
instance_id,
parameter_group_name,
db_engine,
db_engine_version,
instance_class,
storage_type,
allocated_storage,
admin_name,
admin_password,
):
"""
Creates a DB instance.
:param db_name: The name of the database that is created in the DB instance.
:param instance_id: The ID to give the newly created DB instance.
:param parameter_group_name: A parameter group to associate with the DB instance.
:param db_engine: The database engine of a database to create in the DB instance.
:param db_engine_version: The engine version for the created database.
:param instance_class: The DB instance class for the newly created DB instance.
:param storage_type: The storage type of the DB instance.
:param allocated_storage: The amount of storage allocated on the DB instance, in GiBs.
:param admin_name: The name of the admin user for the created database.
:param admin_password: The admin password for the created database.
:return: Data about the newly created DB instance.
"""
try:
response = self.rds_client.create_db_instance(
DBName=db_name,
DBInstanceIdentifier=instance_id,
DBParameterGroupName=parameter_group_name,
Engine=db_engine,
EngineVersion=db_engine_version,
DBInstanceClass=instance_class,
StorageType=storage_type,
AllocatedStorage=allocated_storage,
MasterUsername=admin_name,
MasterUserPassword=admin_password,
)
db_inst = response["DBInstance"]
except ClientError as err:
logger.error(
"Couldn't create DB instance %s. Here's why: %s: %s",
instance_id,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return db_inst
def delete_db_instance(self, instance_id):
"""
Deletes a DB instance.
:param instance_id: The ID of the DB instance to delete.
:return: Data about the deleted DB instance.
"""
try:
response = self.rds_client.delete_db_instance(
DBInstanceIdentifier=instance_id,
SkipFinalSnapshot=True,
DeleteAutomatedBackups=True,
)
db_inst = response["DBInstance"]
except ClientError as err:
logger.error(
"Couldn't delete DB instance %s. Here's why: %s: %s",
instance_id,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return db_inst
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の以下のトピックを参照してください。
+ [CreateDBInstance](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/CreateDBInstance)
+ [CreateDBParameterGroup](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/CreateDBParameterGroup)
+ [CreateDBSnapshot](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/CreateDBSnapshot)
+ [DeleteDBInstance](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/DeleteDBInstance)
+ [DeleteDBParameterGroup](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/DeleteDBParameterGroup)
+ [DescribeDBEngineVersions](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/DescribeDBEngineVersions)
+ [DescribeDBInstances](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/DescribeDBInstances)
+ [DescribeDBParameterGroups](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/DescribeDBParameterGroups)
+ [DescribeDBParameters](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/DescribeDBParameters)
+ [DescribeDBSnapshots](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/DescribeDBSnapshots)
+ [DescribeOrderableDBInstanceOptions](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/DescribeOrderableDBInstanceOptions)
+ [ModifyDBParameterGroup](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/ModifyDBParameterGroup)
## アクション
### `CreateDBInstance`
次のコード例は、`CreateDBInstance` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rds#code-examples)での設定と実行の方法を確認してください。
```
class InstanceWrapper:
"""Encapsulates Amazon RDS DB instance actions."""
def __init__(self, rds_client):
"""
:param rds_client: A Boto3 Amazon RDS client.
"""
self.rds_client = rds_client
@classmethod
def from_client(cls):
"""
Instantiates this class from a Boto3 client.
"""
rds_client = boto3.client("rds")
return cls(rds_client)
def create_db_instance(
self,
db_name,
instance_id,
parameter_group_name,
db_engine,
db_engine_version,
instance_class,
storage_type,
allocated_storage,
admin_name,
admin_password,
):
"""
Creates a DB instance.
:param db_name: The name of the database that is created in the DB instance.
:param instance_id: The ID to give the newly created DB instance.
:param parameter_group_name: A parameter group to associate with the DB instance.
:param db_engine: The database engine of a database to create in the DB instance.
:param db_engine_version: The engine version for the created database.
:param instance_class: The DB instance class for the newly created DB instance.
:param storage_type: The storage type of the DB instance.
:param allocated_storage: The amount of storage allocated on the DB instance, in GiBs.
:param admin_name: The name of the admin user for the created database.
:param admin_password: The admin password for the created database.
:return: Data about the newly created DB instance.
"""
try:
response = self.rds_client.create_db_instance(
DBName=db_name,
DBInstanceIdentifier=instance_id,
DBParameterGroupName=parameter_group_name,
Engine=db_engine,
EngineVersion=db_engine_version,
DBInstanceClass=instance_class,
StorageType=storage_type,
AllocatedStorage=allocated_storage,
MasterUsername=admin_name,
MasterUserPassword=admin_password,
)
db_inst = response["DBInstance"]
except ClientError as err:
logger.error(
"Couldn't create DB instance %s. Here's why: %s: %s",
instance_id,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return db_inst
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[CreateDBInstance](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/CreateDBInstance)」を参照してください。
### `CreateDBParameterGroup`
次のコード例は、`CreateDBParameterGroup` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rds#code-examples)での設定と実行の方法を確認してください。
```
class InstanceWrapper:
"""Encapsulates Amazon RDS DB instance actions."""
def __init__(self, rds_client):
"""
:param rds_client: A Boto3 Amazon RDS client.
"""
self.rds_client = rds_client
@classmethod
def from_client(cls):
"""
Instantiates this class from a Boto3 client.
"""
rds_client = boto3.client("rds")
return cls(rds_client)
def create_parameter_group(
self, parameter_group_name, parameter_group_family, description
):
"""
Creates a DB parameter group that is based on the specified parameter group
family.
:param parameter_group_name: The name of the newly created parameter group.
:param parameter_group_family: The family that is used as the basis of the new
parameter group.
:param description: A description given to the parameter group.
:return: Data about the newly created parameter group.
"""
try:
response = self.rds_client.create_db_parameter_group(
DBParameterGroupName=parameter_group_name,
DBParameterGroupFamily=parameter_group_family,
Description=description,
)
except ClientError as err:
logger.error(
"Couldn't create parameter group %s. Here's why: %s: %s",
parameter_group_name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return response
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[CreateDBParameterGroup](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/CreateDBParameterGroup)」を参照してください。
### `CreateDBSnapshot`
次のコード例は、`CreateDBSnapshot` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rds#code-examples)での設定と実行の方法を確認してください。
```
class InstanceWrapper:
"""Encapsulates Amazon RDS DB instance actions."""
def __init__(self, rds_client):
"""
:param rds_client: A Boto3 Amazon RDS client.
"""
self.rds_client = rds_client
@classmethod
def from_client(cls):
"""
Instantiates this class from a Boto3 client.
"""
rds_client = boto3.client("rds")
return cls(rds_client)
def create_snapshot(self, snapshot_id, instance_id):
"""
Creates a snapshot of a DB instance.
:param snapshot_id: The ID to give the created snapshot.
:param instance_id: The ID of the DB instance to snapshot.
:return: Data about the newly created snapshot.
"""
try:
response = self.rds_client.create_db_snapshot(
DBSnapshotIdentifier=snapshot_id, DBInstanceIdentifier=instance_id
)
snapshot = response["DBSnapshot"]
except ClientError as err:
logger.error(
"Couldn't create snapshot of %s. Here's why: %s: %s",
instance_id,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return snapshot
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[CreateDBSnapshot](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/CreateDBSnapshot)」を参照してください。
### `DeleteDBInstance`
次のコード例は、`DeleteDBInstance` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rds#code-examples)での設定と実行の方法を確認してください。
```
class InstanceWrapper:
"""Encapsulates Amazon RDS DB instance actions."""
def __init__(self, rds_client):
"""
:param rds_client: A Boto3 Amazon RDS client.
"""
self.rds_client = rds_client
@classmethod
def from_client(cls):
"""
Instantiates this class from a Boto3 client.
"""
rds_client = boto3.client("rds")
return cls(rds_client)
def delete_db_instance(self, instance_id):
"""
Deletes a DB instance.
:param instance_id: The ID of the DB instance to delete.
:return: Data about the deleted DB instance.
"""
try:
response = self.rds_client.delete_db_instance(
DBInstanceIdentifier=instance_id,
SkipFinalSnapshot=True,
DeleteAutomatedBackups=True,
)
db_inst = response["DBInstance"]
except ClientError as err:
logger.error(
"Couldn't delete DB instance %s. Here's why: %s: %s",
instance_id,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return db_inst
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[DeleteDBInstance](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/DeleteDBInstance)」を参照してください。
### `DeleteDBParameterGroup`
次のコード例は、`DeleteDBParameterGroup` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rds#code-examples)での設定と実行の方法を確認してください。
```
class InstanceWrapper:
"""Encapsulates Amazon RDS DB instance actions."""
def __init__(self, rds_client):
"""
:param rds_client: A Boto3 Amazon RDS client.
"""
self.rds_client = rds_client
@classmethod
def from_client(cls):
"""
Instantiates this class from a Boto3 client.
"""
rds_client = boto3.client("rds")
return cls(rds_client)
def delete_parameter_group(self, parameter_group_name):
"""
Deletes a DB parameter group.
:param parameter_group_name: The name of the parameter group to delete.
:return: Data about the parameter group.
"""
try:
self.rds_client.delete_db_parameter_group(
DBParameterGroupName=parameter_group_name
)
except ClientError as err:
logger.error(
"Couldn't delete parameter group %s. Here's why: %s: %s",
parameter_group_name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[DeleteDBParameterGroup](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/DeleteDBParameterGroup)」を参照してください。
### `DescribeDBEngineVersions`
次のコード例は、`DescribeDBEngineVersions` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rds#code-examples)での設定と実行の方法を確認してください。
```
class InstanceWrapper:
"""Encapsulates Amazon RDS DB instance actions."""
def __init__(self, rds_client):
"""
:param rds_client: A Boto3 Amazon RDS client.
"""
self.rds_client = rds_client
@classmethod
def from_client(cls):
"""
Instantiates this class from a Boto3 client.
"""
rds_client = boto3.client("rds")
return cls(rds_client)
def get_engine_versions(self, engine, parameter_group_family=None):
"""
Gets database engine versions that are available for the specified engine
and parameter group family.
:param engine: The database engine to look up.
:param parameter_group_family: When specified, restricts the returned list of
engine versions to those that are compatible with
this parameter group family.
:return: The list of database engine versions.
"""
try:
kwargs = {"Engine": engine}
if parameter_group_family is not None:
kwargs["DBParameterGroupFamily"] = parameter_group_family
response = self.rds_client.describe_db_engine_versions(**kwargs)
versions = response["DBEngineVersions"]
except ClientError as err:
logger.error(
"Couldn't get engine versions for %s. Here's why: %s: %s",
engine,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return versions
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[DescribeDBEngineVersions](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/DescribeDBEngineVersions)」を参照してください。
### `DescribeDBInstances`
次のコード例は、`DescribeDBInstances` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rds#code-examples)での設定と実行の方法を確認してください。
```
class InstanceWrapper:
"""Encapsulates Amazon RDS DB instance actions."""
def __init__(self, rds_client):
"""
:param rds_client: A Boto3 Amazon RDS client.
"""
self.rds_client = rds_client
@classmethod
def from_client(cls):
"""
Instantiates this class from a Boto3 client.
"""
rds_client = boto3.client("rds")
return cls(rds_client)
def get_db_instance(self, instance_id):
"""
Gets data about a DB instance.
:param instance_id: The ID of the DB instance to retrieve.
:return: The retrieved DB instance.
"""
try:
response = self.rds_client.describe_db_instances(
DBInstanceIdentifier=instance_id
)
db_inst = response["DBInstances"][0]
except ClientError as err:
if err.response["Error"]["Code"] == "DBInstanceNotFound":
logger.info("Instance %s does not exist.", instance_id)
else:
logger.error(
"Couldn't get DB instance %s. Here's why: %s: %s",
instance_id,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return db_inst
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[DescribeDBInstances](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/DescribeDBInstances)」を参照してください。
### `DescribeDBParameterGroups`
次のコード例は、`DescribeDBParameterGroups` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rds#code-examples)での設定と実行の方法を確認してください。
```
class InstanceWrapper:
"""Encapsulates Amazon RDS DB instance actions."""
def __init__(self, rds_client):
"""
:param rds_client: A Boto3 Amazon RDS client.
"""
self.rds_client = rds_client
@classmethod
def from_client(cls):
"""
Instantiates this class from a Boto3 client.
"""
rds_client = boto3.client("rds")
return cls(rds_client)
def get_parameter_group(self, parameter_group_name):
"""
Gets a DB parameter group.
:param parameter_group_name: The name of the parameter group to retrieve.
:return: The parameter group.
"""
try:
response = self.rds_client.describe_db_parameter_groups(
DBParameterGroupName=parameter_group_name
)
parameter_group = response["DBParameterGroups"][0]
except ClientError as err:
if err.response["Error"]["Code"] == "DBParameterGroupNotFound":
logger.info("Parameter group %s does not exist.", parameter_group_name)
else:
logger.error(
"Couldn't get parameter group %s. Here's why: %s: %s",
parameter_group_name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return parameter_group
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[DescribeDBParameterGroups](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/DescribeDBParameterGroups)」を参照してください。
### `DescribeDBParameters`
次のコード例は、`DescribeDBParameters` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rds#code-examples)での設定と実行の方法を確認してください。
```
class InstanceWrapper:
"""Encapsulates Amazon RDS DB instance actions."""
def __init__(self, rds_client):
"""
:param rds_client: A Boto3 Amazon RDS client.
"""
self.rds_client = rds_client
@classmethod
def from_client(cls):
"""
Instantiates this class from a Boto3 client.
"""
rds_client = boto3.client("rds")
return cls(rds_client)
def get_parameters(self, parameter_group_name, name_prefix="", source=None):
"""
Gets the parameters that are contained in a DB parameter group.
:param parameter_group_name: The name of the parameter group to query.
:param name_prefix: When specified, the retrieved list of parameters is filtered
to contain only parameters that start with this prefix.
:param source: When specified, only parameters from this source are retrieved.
For example, a source of 'user' retrieves only parameters that
were set by a user.
:return: The list of requested parameters.
"""
try:
kwargs = {"DBParameterGroupName": parameter_group_name}
if source is not None:
kwargs["Source"] = source
parameters = []
paginator = self.rds_client.get_paginator("describe_db_parameters")
for page in paginator.paginate(**kwargs):
parameters += [
p
for p in page["Parameters"]
if p["ParameterName"].startswith(name_prefix)
]
except ClientError as err:
logger.error(
"Couldn't get parameters for %s. Here's why: %s: %s",
parameter_group_name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return parameters
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[DescribeDBParameters](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/DescribeDBParameters)」を参照してください。
### `DescribeDBSnapshots`
次のコード例は、`DescribeDBSnapshots` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rds#code-examples)での設定と実行の方法を確認してください。
```
class InstanceWrapper:
"""Encapsulates Amazon RDS DB instance actions."""
def __init__(self, rds_client):
"""
:param rds_client: A Boto3 Amazon RDS client.
"""
self.rds_client = rds_client
@classmethod
def from_client(cls):
"""
Instantiates this class from a Boto3 client.
"""
rds_client = boto3.client("rds")
return cls(rds_client)
def get_snapshot(self, snapshot_id):
"""
Gets a DB instance snapshot.
:param snapshot_id: The ID of the snapshot to retrieve.
:return: The retrieved snapshot.
"""
try:
response = self.rds_client.describe_db_snapshots(
DBSnapshotIdentifier=snapshot_id
)
snapshot = response["DBSnapshots"][0]
except ClientError as err:
logger.error(
"Couldn't get snapshot %s. Here's why: %s: %s",
snapshot_id,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return snapshot
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[DescribeDBSnapshots](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/DescribeDBSnapshots)」を参照してください。
### `DescribeOrderableDBInstanceOptions`
次のコード例は、`DescribeOrderableDBInstanceOptions` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rds#code-examples)での設定と実行の方法を確認してください。
```
class InstanceWrapper:
"""Encapsulates Amazon RDS DB instance actions."""
def __init__(self, rds_client):
"""
:param rds_client: A Boto3 Amazon RDS client.
"""
self.rds_client = rds_client
@classmethod
def from_client(cls):
"""
Instantiates this class from a Boto3 client.
"""
rds_client = boto3.client("rds")
return cls(rds_client)
def get_orderable_instances(self, db_engine, db_engine_version):
"""
Gets DB instance options that can be used to create DB instances that are
compatible with a set of specifications.
:param db_engine: The database engine that must be supported by the DB instance.
:param db_engine_version: The engine version that must be supported by the DB instance.
:return: The list of DB instance options that can be used to create a compatible DB instance.
"""
try:
inst_opts = []
paginator = self.rds_client.get_paginator(
"describe_orderable_db_instance_options"
)
for page in paginator.paginate(
Engine=db_engine, EngineVersion=db_engine_version
):
inst_opts += page["OrderableDBInstanceOptions"]
except ClientError as err:
logger.error(
"Couldn't get orderable DB instances. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return inst_opts
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[DescribeOrderableDBInstanceOptions](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/DescribeOrderableDBInstanceOptions)」を参照してください。
### `ModifyDBParameterGroup`
次のコード例は、`ModifyDBParameterGroup` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rds#code-examples)での設定と実行の方法を確認してください。
```
class InstanceWrapper:
"""Encapsulates Amazon RDS DB instance actions."""
def __init__(self, rds_client):
"""
:param rds_client: A Boto3 Amazon RDS client.
"""
self.rds_client = rds_client
@classmethod
def from_client(cls):
"""
Instantiates this class from a Boto3 client.
"""
rds_client = boto3.client("rds")
return cls(rds_client)
def update_parameters(self, parameter_group_name, update_parameters):
"""
Updates parameters in a custom DB parameter group.
:param parameter_group_name: The name of the parameter group to update.
:param update_parameters: The parameters to update in the group.
:return: Data about the modified parameter group.
"""
try:
response = self.rds_client.modify_db_parameter_group(
DBParameterGroupName=parameter_group_name, Parameters=update_parameters
)
except ClientError as err:
logger.error(
"Couldn't update parameters in %s. Here's why: %s: %s",
parameter_group_name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return response
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[ModifyDBParameterGroup](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/ModifyDBParameterGroup)」を参照してください。
## シナリオ
### Aurora Serverless 作業項目トラッカーの作成
次のコード例は、Amazon Aurora Serverless データベースの作業項目を追跡し、Amazon Simple Email Service (Amazon SES) を使用してレポートを送信するウェブアプリケーションを作成する方法を示しています。
**SDK for Python (Boto3)**
を使用して Amazon Aurora Serverless データベース内の作業項目を追跡し、Amazon Simple Email Service (Amazon SES) を使用してレポートを E メールで送信する REST サービス AWS SDK for Python (Boto3) を作成する方法を示します。この例では、Flask ウェブフレームワークを使用して HTTP ルーティングを処理し、React ウェブページと統合して完全に機能するウェブアプリケーションを提供しています。
+ と統合する Flask REST サービスを構築します AWS のサービス。
+ Aurora Serverless データベースに保存されている作業項目の読み取り、書き込み、更新を行います。
+ データベース認証情報を含む AWS Secrets Manager シークレットを作成し、それを使用してデータベースへの呼び出しを認証します。
+ Amazon SES を使用して作業項目のレポートを E メールで送信します。
完全なソースコードとセットアップおよび実行の手順については、[GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/aurora_item_tracker) で完全な例を参照してください。
**この例で使用されているサービス**
+ Aurora
+ Amazon RDS
+ Amazon RDS データサービス
+ Amazon SES
## サーバーレスサンプル
### Lambda 関数での Amazon RDS データベースへの接続
次のコード例は、RDS データベースに接続する Lambda 関数を実装する方法を示しています。この関数は、シンプルなデータベースリクエストを実行し、結果を返します。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。[サーバーレスサンプル](https://github.com/aws-samples/serverless-snippets/tree/main/lambda-function-connect-rds-iam)リポジトリで完全な例を見つけて、設定と実行の方法を確認してください。
Python を使用した Lambda 関数での Amazon RDS データベースへの接続
```
import json
import os
import boto3
import pymysql
# RDS settings
proxy_host_name = os.environ['PROXY_HOST_NAME']
port = int(os.environ['PORT'])
db_name = os.environ['DB_NAME']
db_user_name = os.environ['DB_USER_NAME']
aws_region = os.environ['AWS_REGION']
# Fetch RDS Auth Token
def get_auth_token():
client = boto3.client('rds')
token = client.generate_db_auth_token(
DBHostname=proxy_host_name,
Port=port
DBUsername=db_user_name
Region=aws_region
)
return token
def lambda_handler(event, context):
token = get_auth_token()
try:
connection = pymysql.connect(
host=proxy_host_name,
user=db_user_name,
password=token,
db=db_name,
port=port,
ssl={'ca': 'Amazon RDS'} # Ensure you have the CA bundle for SSL connection
)
with connection.cursor() as cursor:
cursor.execute('SELECT %s + %s AS sum', (3, 2))
result = cursor.fetchone()
return result
except Exception as e:
return (f"Error: {str(e)}") # Return an error message if an exception occurs
```
# SDK for Python (Boto3) を使用する Amazon RDS データサービスの例
次のコード例は、Amazon RDS Data Service AWS SDK for Python (Boto3) で を使用してアクションを実行し、一般的なシナリオを実装する方法を示しています。
*シナリオ*は、1 つのサービス内から、または他の AWS のサービスと組み合わせて複数の関数を呼び出し、特定のタスクを実行する方法を示すコード例です。
各例には完全なソースコードへのリンクが含まれており、コンテキスト内でコードを設定および実行する方法の手順を確認できます。
**Topics**
+ [シナリオ](#scenarios)
## シナリオ
### Aurora Serverless 作業項目トラッカーの作成
次のコード例は、Amazon Aurora Serverless データベースの作業項目を追跡し、Amazon Simple Email Service (Amazon SES) を使用してレポートを送信するウェブアプリケーションを作成する方法を示しています。
**SDK for Python (Boto3)**
を使用して Amazon Aurora Serverless データベース内の作業項目を追跡し、Amazon Simple Email Service (Amazon SES) を使用してレポートを E メールで送信する REST サービス AWS SDK for Python (Boto3) を作成する方法を示します。この例では、Flask ウェブフレームワークを使用して HTTP ルーティングを処理し、React ウェブページと統合して完全に機能するウェブアプリケーションを提供しています。
+ と統合する Flask REST サービスを構築します AWS のサービス。
+ Aurora Serverless データベースに保存されている作業項目の読み取り、書き込み、更新を行います。
+ データベース認証情報を含む AWS Secrets Manager シークレットを作成し、それを使用してデータベースへの呼び出しを認証します。
+ Amazon SES を使用して作業項目のレポートを E メールで送信します。
完全なソースコードとセットアップおよび実行の手順については、[GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/aurora_item_tracker) で完全な例を参照してください。
**この例で使用されているサービス**
+ Aurora
+ Amazon RDS
+ Amazon RDS データサービス
+ Amazon SES
# SDK for Python (Boto3) を使用する Amazon Redshift の例
次のコード例は、Amazon Redshift AWS SDK for Python (Boto3) で を使用してアクションを実行し、一般的なシナリオを実装する方法を示しています。
*基本* は、重要なオペレーションをサービス内で実行する方法を示すコード例です。
*アクション*はより大きなプログラムからのコードの抜粋であり、コンテキスト内で実行する必要があります。アクションは個々のサービス機能を呼び出す方法を示していますが、コンテキスト内のアクションは、関連するシナリオで確認できます。
各例には完全なソースコードへのリンクが含まれており、コンテキスト内でコードを設定および実行する方法の手順を確認できます。
**Topics**
+ [はじめに](#get_started)
+ [基本](#basics)
+ [アクション](#actions)
## はじめに
### Hello Amazon Redshift
次のコード例は、Amazon Redshift の使用を開始する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/redshift#code-examples)での設定と実行の方法を確認してください。
```
import boto3
def hello_redshift(redshift_client):
"""
Use the AWS SDK for Python (Boto3) to create an Amazon Redshift client and list
the clusters in your account. This list might be empty if you haven't created
any clusters.
This example uses the default settings specified in your shared credentials
and config files.
:param redshift_client: A Boto3 Redshift Client object.
"""
print("Hello, Redshift! Let's list your clusters:")
paginator = redshift_client.get_paginator("describe_clusters")
clusters = []
for page in paginator.paginate():
clusters.extend(page["Clusters"])
print(f"{len(clusters)} cluster(s) were found.")
for cluster in clusters:
print(f" {cluster['ClusterIdentifier']}")
if __name__ == "__main__":
hello_redshift(boto3.client("redshift"))
```
+ API の詳細については、「AWS SDK for Python (Boto3) API リファレンス」の「[DescribeClusters](https://docs.aws.amazon.com/goto/boto3/redshift-2012-12-01/DescribeClusters)」を参照してください。**
## 基本
### 基本を学ぶ
次のコード例は、以下の操作方法を示しています。
+ Redshift クラスターを作成します。
+ クラスター内のデータベースを一覧表示します。
+ Movies という名前のテーブルを作成します。
+ Movies テーブルにデータを入力します。
+ Movies テーブルに対して年に基づくクエリを実行します。
+ Redshift クラスターを変更します。
+ Amazon Redshift クラスターを削除します。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/redshift#code-examples)での設定と実行の方法を確認してください。
```
class RedshiftScenario:
"""Runs an interactive scenario that shows how to get started with Redshift."""
def __init__(self, redshift_wrapper, redshift_data_wrapper):
self.redshift_wrapper = redshift_wrapper
self.redshift_data_wrapper = redshift_data_wrapper
def redhift_scenario(self, json_file_path):
database_name = "dev"
print(DASHES)
print("Welcome to the Amazon Redshift SDK Getting Started example.")
print(
"""
This Python program demonstrates how to interact with Amazon Redshift
using the AWS SDK for Python (Boto3).
Amazon Redshift is a fully managed, petabyte-scale data warehouse
service hosted in the cloud.
The program's primary functionalities include cluster creation,
verification of cluster readiness, listing databases, table creation,
populating data within the table, and executing SQL statements.
It also demonstrates querying data from the Movies table.
Upon completion, all AWS resources are cleaned up.
"""
)
if not os.path.isfile(json_file_path):
logging.error(f"The file {json_file_path} does not exist.")
return
print("Let's get started...")
user_name = q.ask("Please enter your user name (default is awsuser):")
user_name = user_name if user_name else "awsuser"
print(DASHES)
user_password = q.ask(
"Please enter your user password (default is AwsUser1000):"
)
user_password = user_password if user_password else "AwsUser1000"
print(DASHES)
print(
"""A Redshift cluster refers to the collection of computing resources and storage that work
together to process and analyze large volumes of data."""
)
cluster_id = q.ask(
"Enter a cluster identifier value (default is redshift-cluster-movies): "
)
cluster_id = cluster_id if cluster_id else "redshift-cluster-movies"
self.redshift_wrapper.create_cluster(
cluster_id, "ra3.4xlarge", user_name, user_password, True, 2
)
print(DASHES)
print(f"Wait until {cluster_id} is available. This may take a few minutes...")
q.ask("Press Enter to continue...")
self.wait_cluster_available(cluster_id)
print(DASHES)
print(
f"""
When you created {cluster_id}, the dev database is created by default and used in this scenario.
To create a custom database, you need to have a CREATEDB privilege.
For more information, see the documentation here:
https://docs.aws.amazon.com/redshift/latest/dg/r_CREATE_DATABASE.html.
"""
)
q.ask("Press Enter to continue...")
print(DASHES)
print(DASHES)
print(f"List databases in {cluster_id}")
q.ask("Press Enter to continue...")
databases = self.redshift_data_wrapper.list_databases(
cluster_id, database_name, user_name
)
print(f"The cluster contains {len(databases)} database(s).")
for database in databases:
print(f" Database: {database}")
print(DASHES)
print(DASHES)
print("Now you will create a table named Movies.")
q.ask("Press Enter to continue...")
self.create_table(cluster_id, database_name, user_name)
print(DASHES)
print("Populate the Movies table using the Movies.json file.")
print(
"Specify the number of records you would like to add to the Movies Table."
)
print("Please enter a value between 50 and 200.")
while True:
try:
num_records = int(q.ask("Enter a value: ", q.is_int))
if 50 <= num_records <= 200:
break
else:
print("Invalid input. Please enter a value between 50 and 200.")
except ValueError:
print("Invalid input. Please enter a value between 50 and 200.")
self.populate_table(
cluster_id, database_name, user_name, json_file_path, num_records
)
print(DASHES)
print("Query the Movies table by year. Enter a value between 2012-2014.")
while True:
movie_year = int(q.ask("Enter a year: ", q.is_int))
if 2012 <= movie_year <= 2014:
break
else:
print("Invalid input. Please enter a valid year between 2012 and 2014.")
# Function to query database
sql_id = self.query_movies_by_year(
database_name, user_name, movie_year, cluster_id
)
print(f"The identifier of the statement is {sql_id}")
print("Checking statement status...")
self.wait_statement_finished(sql_id)
result = self.redshift_data_wrapper.get_statement_result(sql_id)
self.display_movies(result)
print(DASHES)
print(DASHES)
print("Now you will modify the Redshift cluster.")
q.ask("Press Enter to continue...")
preferred_maintenance_window = "wed:07:30-wed:08:00"
self.redshift_wrapper.modify_cluster(cluster_id, preferred_maintenance_window)
print(DASHES)
print(DASHES)
delete = q.ask("Do you want to delete the cluster? (y/n) ", q.is_yesno)
if delete:
print(f"You selected to delete {cluster_id}")
q.ask("Press Enter to continue...")
self.redshift_wrapper.delete_cluster(cluster_id)
else:
print(f"Cluster {cluster_id}cluster_id was not deleted")
print(DASHES)
print("This concludes the Amazon Redshift SDK Getting Started scenario.")
print(DASHES)
def create_table(self, cluster_id, database, username):
self.redshift_data_wrapper.execute_statement(
cluster_identifier=cluster_id,
database_name=database,
user_name=username,
sql="CREATE TABLE Movies (statement_id INT PRIMARY KEY, title VARCHAR(100), year INT)",
)
print("Table created: Movies")
def populate_table(self, cluster_id, database, username, file_name, number):
with open(file_name) as f:
data = json.load(f)
i = 0
for record in data:
if i == number:
break
statement_id = i
title = record["title"]
year = record["year"]
i = i + 1
parameters = [
{"name": "statement_id", "value": str(statement_id)},
{"name": "title", "value": title},
{"name": "year", "value": str(year)},
]
self.redshift_data_wrapper.execute_statement(
cluster_identifier=cluster_id,
database_name=database,
user_name=username,
sql="INSERT INTO Movies VALUES(:statement_id, :title, :year)",
parameter_list=parameters,
)
print(f"{i} records inserted into Movies table")
def wait_cluster_available(self, cluster_id):
"""
Waits for a cluster to be available.
:param cluster_id: The cluster identifier.
Note: The cluster_available waiter can also be used.
It is not used in this case to allow an elapsed time message.
"""
cluster_ready = False
start_time = time.time()
while not cluster_ready:
time.sleep(30)
cluster = self.redshift_wrapper.describe_clusters(cluster_id)
status = cluster[0]["ClusterStatus"]
if status == "available":
cluster_ready = True
elif status != "creating":
raise Exception(
f"Cluster {cluster_id} creation failed with status {status}."
)
elapsed_seconds = int(round(time.time() - start_time))
minutes = int(elapsed_seconds // 60)
seconds = int(elapsed_seconds % 60)
print(f"Elapsed Time: {minutes}:{seconds:02d} - status {status}...")
if minutes > 30:
raise Exception(
f"Cluster {cluster_id} is not available after 30 minutes."
)
def query_movies_by_year(self, database, username, year, cluster_id):
sql = "SELECT * FROM Movies WHERE year = :year"
params = [{"name": "year", "value": str(year)}]
response = self.redshift_data_wrapper.execute_statement(
cluster_identifier=cluster_id,
database_name=database,
user_name=username,
sql=sql,
parameter_list=params,
)
return response["Id"]
@staticmethod
def display_movies(response):
metadata = response["ColumnMetadata"]
records = response["Records"]
title_column_index = None
for i in range(len(metadata)):
if metadata[i]["name"] == "title":
title_column_index = i
break
if title_column_index is None:
print("No title column found.")
return
print(f"Found {len(records)} movie(s).")
for record in records:
print(f" {record[title_column_index]['stringValue']}")
def wait_statement_finished(self, sql_id):
while True:
time.sleep(1)
response = self.redshift_data_wrapper.describe_statement(sql_id)
status = response["Status"]
print(f"Statement status is {status}.")
if status == "FAILED":
print(f"The query failed because {response['Error']}. Ending program")
raise Exception("The Query Failed. Ending program")
elif status == "FINISHED":
break
```
シナリオの実装を示すメイン関数。
```
def main():
redshift_client = boto3.client("redshift")
redshift_data_client = boto3.client("redshift-data")
redshift_wrapper = RedshiftWrapper(redshift_client)
redshift_data_wrapper = RedshiftDataWrapper(redshift_data_client)
redshift_scenario = RedshiftScenario(redshift_wrapper, redshift_data_wrapper)
redshift_scenario.redhift_scenario(
f"{os.path.dirname(__file__)}/../../../resources/sample_files/movies.json"
)
```
シナリオで使用するラッパー関数。
```
def create_cluster(
self,
cluster_identifier,
node_type,
master_username,
master_user_password,
publicly_accessible,
number_of_nodes,
):
"""
Creates a cluster.
:param cluster_identifier: The name of the cluster.
:param node_type: The type of node in the cluster.
:param master_username: The master username.
:param master_user_password: The master user password.
:param publicly_accessible: Whether the cluster is publicly accessible.
:param number_of_nodes: The number of nodes in the cluster.
:return: The cluster.
"""
try:
cluster = self.client.create_cluster(
ClusterIdentifier=cluster_identifier,
NodeType=node_type,
MasterUsername=master_username,
MasterUserPassword=master_user_password,
PubliclyAccessible=publicly_accessible,
NumberOfNodes=number_of_nodes,
)
return cluster
except ClientError as err:
logging.error(
"Couldn't create a cluster. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
def describe_clusters(self, cluster_identifier):
"""
Describes a cluster.
:param cluster_identifier: The cluster identifier.
:return: A list of clusters.
"""
try:
kwargs = {}
if cluster_identifier:
kwargs["ClusterIdentifier"] = cluster_identifier
paginator = self.client.get_paginator("describe_clusters")
clusters = []
for page in paginator.paginate(**kwargs):
clusters.extend(page["Clusters"])
return clusters
except ClientError as err:
logging.error(
"Couldn't describe a cluster. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
def execute_statement(
self, cluster_identifier, database_name, user_name, sql, parameter_list=None
):
"""
Executes a SQL statement.
:param cluster_identifier: The cluster identifier.
:param database_name: The database name.
:param user_name: The user's name.
:param sql: The SQL statement.
:param parameter_list: The optional SQL statement parameters.
:return: The SQL statement result.
"""
try:
kwargs = {
"ClusterIdentifier": cluster_identifier,
"Database": database_name,
"DbUser": user_name,
"Sql": sql,
}
if parameter_list:
kwargs["Parameters"] = parameter_list
response = self.client.execute_statement(**kwargs)
return response
except ClientError as err:
logging.error(
"Couldn't execute statement. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
def describe_statement(self, statement_id):
"""
Describes a SQL statement.
:param statement_id: The SQL statement identifier.
:return: The SQL statement result.
"""
try:
response = self.client.describe_statement(Id=statement_id)
return response
except ClientError as err:
logging.error(
"Couldn't describe statement. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
def get_statement_result(self, statement_id):
"""
Gets the result of a SQL statement.
:param statement_id: The SQL statement identifier.
:return: The SQL statement result.
"""
try:
result = {
"Records": [],
}
paginator = self.client.get_paginator("get_statement_result")
for page in paginator.paginate(Id=statement_id):
if "ColumnMetadata" not in result:
result["ColumnMetadata"] = page["ColumnMetadata"]
result["Records"].extend(page["Records"])
return result
except ClientError as err:
logging.error(
"Couldn't get statement result. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
def modify_cluster(self, cluster_identifier, preferred_maintenance_window):
"""
Modifies a cluster.
:param cluster_identifier: The cluster identifier.
:param preferred_maintenance_window: The preferred maintenance window.
"""
try:
self.client.modify_cluster(
ClusterIdentifier=cluster_identifier,
PreferredMaintenanceWindow=preferred_maintenance_window,
)
except ClientError as err:
logging.error(
"Couldn't modify a cluster. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
def list_databases(self, cluster_identifier, database_name, database_user):
"""
Lists databases in a cluster.
:param cluster_identifier: The cluster identifier.
:param database_name: The database name.
:param database_user: The database user.
:return: The list of databases.
"""
try:
paginator = self.client.get_paginator("list_databases")
databases = []
for page in paginator.paginate(
ClusterIdentifier=cluster_identifier,
Database=database_name,
DbUser=database_user,
):
databases.extend(page["Databases"])
return databases
except ClientError as err:
logging.error(
"Couldn't list databases. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
def delete_cluster(self, cluster_identifier):
"""
Deletes a cluster.
:param cluster_identifier: The cluster identifier.
"""
try:
self.client.delete_cluster(
ClusterIdentifier=cluster_identifier, SkipFinalClusterSnapshot=True
)
except ClientError as err:
logging.error(
"Couldn't delete a cluster. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ API の詳細については、『*AWS SDK for Python (Boto3) API リファレンス*』の以下のトピックを参照してください。
+ [CreateCluster](https://docs.aws.amazon.com/goto/boto3/redshift-2012-12-01/CreateCluster)
+ [DescribeClusters](https://docs.aws.amazon.com/goto/boto3/redshift-2012-12-01/DescribeClusters)
+ [DescribeStatement](https://docs.aws.amazon.com/goto/boto3/redshift-2012-12-01/DescribeStatement)
+ [ExecuteStatement](https://docs.aws.amazon.com/goto/boto3/redshift-2012-12-01/ExecuteStatement)
+ [GetStatementResult](https://docs.aws.amazon.com/goto/boto3/redshift-2012-12-01/GetStatementResult)
+ [ListDatabasesPaginator](https://docs.aws.amazon.com/goto/boto3/redshift-2012-12-01/ListDatabasesPaginator)
+ [ModifyCluster](https://docs.aws.amazon.com/goto/boto3/redshift-2012-12-01/ModifyCluster)
## アクション
### `CreateCluster`
次のコード例は、`CreateCluster` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/redshift#code-examples)での設定と実行の方法を確認してください。
```
class RedshiftWrapper:
"""
Encapsulates Amazon Redshift cluster operations.
"""
def __init__(self, redshift_client):
"""
:param redshift_client: A Boto3 Redshift client.
"""
self.client = redshift_client
def create_cluster(
self,
cluster_identifier,
node_type,
master_username,
master_user_password,
publicly_accessible,
number_of_nodes,
):
"""
Creates a cluster.
:param cluster_identifier: The name of the cluster.
:param node_type: The type of node in the cluster.
:param master_username: The master username.
:param master_user_password: The master user password.
:param publicly_accessible: Whether the cluster is publicly accessible.
:param number_of_nodes: The number of nodes in the cluster.
:return: The cluster.
"""
try:
cluster = self.client.create_cluster(
ClusterIdentifier=cluster_identifier,
NodeType=node_type,
MasterUsername=master_username,
MasterUserPassword=master_user_password,
PubliclyAccessible=publicly_accessible,
NumberOfNodes=number_of_nodes,
)
return cluster
except ClientError as err:
logging.error(
"Couldn't create a cluster. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
次のコードは RedShiftWrapper オブジェクトをインスタンス化します。
```
client = boto3.client("redshift")
redhift_wrapper = RedshiftWrapper(client)
```
+ API の詳細については、「AWS SDK for Python (Boto3) API リファレンス」の「[CreateCluster](https://docs.aws.amazon.com/goto/boto3/redshift-2012-12-01/CreateCluster)」を参照してください。**
### `DeleteCluster`
次のコード例は、`DeleteCluster` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/redshift#code-examples)での設定と実行の方法を確認してください。
```
class RedshiftWrapper:
"""
Encapsulates Amazon Redshift cluster operations.
"""
def __init__(self, redshift_client):
"""
:param redshift_client: A Boto3 Redshift client.
"""
self.client = redshift_client
def delete_cluster(self, cluster_identifier):
"""
Deletes a cluster.
:param cluster_identifier: The cluster identifier.
"""
try:
self.client.delete_cluster(
ClusterIdentifier=cluster_identifier, SkipFinalClusterSnapshot=True
)
except ClientError as err:
logging.error(
"Couldn't delete a cluster. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
次のコードは RedShiftWrapper オブジェクトをインスタンス化します。
```
client = boto3.client("redshift")
redhift_wrapper = RedshiftWrapper(client)
```
+ API の詳細については、「AWS SDK for Python (Boto3) API リファレンス」の「[DeleteCluster](https://docs.aws.amazon.com/goto/boto3/redshift-2012-12-01/DeleteCluster)」を参照してください。**
### `DescribeClusters`
次のコード例は、`DescribeClusters` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/redshift#code-examples)での設定と実行の方法を確認してください。
```
class RedshiftWrapper:
"""
Encapsulates Amazon Redshift cluster operations.
"""
def __init__(self, redshift_client):
"""
:param redshift_client: A Boto3 Redshift client.
"""
self.client = redshift_client
def describe_clusters(self, cluster_identifier):
"""
Describes a cluster.
:param cluster_identifier: The cluster identifier.
:return: A list of clusters.
"""
try:
kwargs = {}
if cluster_identifier:
kwargs["ClusterIdentifier"] = cluster_identifier
paginator = self.client.get_paginator("describe_clusters")
clusters = []
for page in paginator.paginate(**kwargs):
clusters.extend(page["Clusters"])
return clusters
except ClientError as err:
logging.error(
"Couldn't describe a cluster. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
次のコードは RedShiftWrapper オブジェクトをインスタンス化します。
```
client = boto3.client("redshift")
redhift_wrapper = RedshiftWrapper(client)
```
+ API の詳細については、「AWS SDK for Python (Boto3) API リファレンス」の「[DescribeClusters](https://docs.aws.amazon.com/goto/boto3/redshift-2012-12-01/DescribeClusters)」を参照してください。**
### `DescribeStatement`
次のコード例は、`DescribeStatement` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/redshift#code-examples)での設定と実行の方法を確認してください。
```
class RedshiftDataWrapper:
"""Encapsulates Amazon Redshift data."""
def __init__(self, client):
"""
:param client: A Boto3 RedshiftDataWrapper client.
"""
self.client = client
def describe_statement(self, statement_id):
"""
Describes a SQL statement.
:param statement_id: The SQL statement identifier.
:return: The SQL statement result.
"""
try:
response = self.client.describe_statement(Id=statement_id)
return response
except ClientError as err:
logging.error(
"Couldn't describe statement. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
次のコードは RedShiftDataWrapper オブジェクトをインスタンス化します。
```
client = boto3.client("redshift-data")
redshift_data_wrapper = RedshiftDataWrapper(client)
```
+ API の詳細については、「AWS SDK for Python (Boto3) API リファレンス」の「[DescribeStatement](https://docs.aws.amazon.com/goto/boto3/redshift-2012-12-01/DescribeStatement)」を参照してください。**
### `GetStatementResult`
次のコード例は、`GetStatementResult` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/redshift#code-examples)での設定と実行の方法を確認してください。
```
class RedshiftDataWrapper:
"""Encapsulates Amazon Redshift data."""
def __init__(self, client):
"""
:param client: A Boto3 RedshiftDataWrapper client.
"""
self.client = client
def get_statement_result(self, statement_id):
"""
Gets the result of a SQL statement.
:param statement_id: The SQL statement identifier.
:return: The SQL statement result.
"""
try:
result = {
"Records": [],
}
paginator = self.client.get_paginator("get_statement_result")
for page in paginator.paginate(Id=statement_id):
if "ColumnMetadata" not in result:
result["ColumnMetadata"] = page["ColumnMetadata"]
result["Records"].extend(page["Records"])
return result
except ClientError as err:
logging.error(
"Couldn't get statement result. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
次のコードは RedShiftDataWrapper オブジェクトをインスタンス化します。
```
client = boto3.client("redshift-data")
redshift_data_wrapper = RedshiftDataWrapper(client)
```
+ API の詳細については、「AWS SDK for Python (Boto3) API リファレンス」の「[GetStatementResult](https://docs.aws.amazon.com/goto/boto3/redshift-2012-12-01/GetStatementResult)」を参照してください。**
### `ModifyCluster`
次のコード例は、`ModifyCluster` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/redshift#code-examples)での設定と実行の方法を確認してください。
```
class RedshiftWrapper:
"""
Encapsulates Amazon Redshift cluster operations.
"""
def __init__(self, redshift_client):
"""
:param redshift_client: A Boto3 Redshift client.
"""
self.client = redshift_client
def modify_cluster(self, cluster_identifier, preferred_maintenance_window):
"""
Modifies a cluster.
:param cluster_identifier: The cluster identifier.
:param preferred_maintenance_window: The preferred maintenance window.
"""
try:
self.client.modify_cluster(
ClusterIdentifier=cluster_identifier,
PreferredMaintenanceWindow=preferred_maintenance_window,
)
except ClientError as err:
logging.error(
"Couldn't modify a cluster. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
次のコードは RedShiftWrapper オブジェクトをインスタンス化します。
```
client = boto3.client("redshift")
redhift_wrapper = RedshiftWrapper(client)
```
+ API の詳細については、「AWS SDK for Python (Boto3) API リファレンス」の「[ModifyCluster](https://docs.aws.amazon.com/goto/boto3/redshift-2012-12-01/ModifyCluster)」を参照してください。**
# SDK for Python (Boto3) を使用する Amazon Rekognition の例
次のコード例は、Amazon Rekognition AWS SDK for Python (Boto3) で を使用してアクションを実行し、一般的なシナリオを実装する方法を示しています。
*アクション*はより大きなプログラムからのコードの抜粋であり、コンテキスト内で実行する必要があります。アクションは個々のサービス機能を呼び出す方法を示していますが、コンテキスト内のアクションは、関連するシナリオで確認できます。
*シナリオ*は、1 つのサービス内から、または他の AWS のサービスと組み合わせて複数の関数を呼び出し、特定のタスクを実行する方法を示すコード例です。
各例には完全なソースコードへのリンクが含まれており、コードの設定方法と実行方法に関する手順を確認できます。
**Topics**
+ [アクション](#actions)
+ [シナリオ](#scenarios)
## アクション
### `CompareFaces`
次のコード例は、`CompareFaces` を使用する方法を示しています。
詳細については、「[イメージ内の顔を比較する](https://docs.aws.amazon.com/rekognition/latest/dg/faces-comparefaces.html)」を参照してください。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rekognition#code-examples)での設定と実行の方法を確認してください。
```
class RekognitionImage:
"""
Encapsulates an Amazon Rekognition image. This class is a thin wrapper
around parts of the Boto3 Amazon Rekognition API.
"""
def __init__(self, image, image_name, rekognition_client):
"""
Initializes the image object.
:param image: Data that defines the image, either the image bytes or
an Amazon S3 bucket and object key.
:param image_name: The name of the image.
:param rekognition_client: A Boto3 Rekognition client.
"""
self.image = image
self.image_name = image_name
self.rekognition_client = rekognition_client
def compare_faces(self, target_image, similarity):
"""
Compares faces in the image with the largest face in the target image.
:param target_image: The target image to compare against.
:param similarity: Faces in the image must have a similarity value greater
than this value to be included in the results.
:return: A tuple. The first element is the list of faces that match the
reference image. The second element is the list of faces that have
a similarity value below the specified threshold.
"""
try:
response = self.rekognition_client.compare_faces(
SourceImage=self.image,
TargetImage=target_image.image,
SimilarityThreshold=similarity,
)
matches = [
RekognitionFace(match["Face"]) for match in response["FaceMatches"]
]
unmatches = [RekognitionFace(face) for face in response["UnmatchedFaces"]]
logger.info(
"Found %s matched faces and %s unmatched faces.",
len(matches),
len(unmatches),
)
except ClientError:
logger.exception(
"Couldn't match faces from %s to %s.",
self.image_name,
target_image.image_name,
)
raise
else:
return matches, unmatches
```
+ API の詳細については、[AWS SDK for Python (Boto3) API リファレンス](https://docs.aws.amazon.com/goto/boto3/rekognition-2016-06-27/CompareFaces)の「*CompareFaces*」を参照してください。
### `CreateCollection`
次のコード例は、`CreateCollection` を使用する方法を示しています。
詳細については、「[コレクションを作成する](https://docs.aws.amazon.com/rekognition/latest/dg/create-collection-procedure.html)」を参照してください。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rekognition#code-examples)での設定と実行の方法を確認してください。
```
class RekognitionCollectionManager:
"""
Encapsulates Amazon Rekognition collection management functions.
This class is a thin wrapper around parts of the Boto3 Amazon Rekognition API.
"""
def __init__(self, rekognition_client):
"""
Initializes the collection manager object.
:param rekognition_client: A Boto3 Rekognition client.
"""
self.rekognition_client = rekognition_client
def create_collection(self, collection_id):
"""
Creates an empty collection.
:param collection_id: Text that identifies the collection.
:return: The newly created collection.
"""
try:
response = self.rekognition_client.create_collection(
CollectionId=collection_id
)
response["CollectionId"] = collection_id
collection = RekognitionCollection(response, self.rekognition_client)
logger.info("Created collection %s.", collection_id)
except ClientError:
logger.exception("Couldn't create collection %s.", collection_id)
raise
else:
return collection
```
+ API の詳細については、[AWS SDK for Python (Boto3) API リファレンス](https://docs.aws.amazon.com/goto/boto3/rekognition-2016-06-27/CreateCollection) の「*CreateCollection*」を参照してください。
### `DeleteCollection`
次のコード例は、`DeleteCollection` を使用する方法を示しています。
詳細については、「[コレクションを削除する](https://docs.aws.amazon.com/rekognition/latest/dg/delete-collection-procedure.html)」を参照してください。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rekognition#code-examples)での設定と実行の方法を確認してください。
```
class RekognitionCollection:
"""
Encapsulates an Amazon Rekognition collection. This class is a thin wrapper
around parts of the Boto3 Amazon Rekognition API.
"""
def __init__(self, collection, rekognition_client):
"""
Initializes a collection object.
:param collection: Collection data in the format returned by a call to
create_collection.
:param rekognition_client: A Boto3 Rekognition client.
"""
self.collection_id = collection["CollectionId"]
self.collection_arn, self.face_count, self.created = self._unpack_collection(
collection
)
self.rekognition_client = rekognition_client
@staticmethod
def _unpack_collection(collection):
"""
Unpacks optional parts of a collection that can be returned by
describe_collection.
:param collection: The collection data.
:return: A tuple of the data in the collection.
"""
return (
collection.get("CollectionArn"),
collection.get("FaceCount", 0),
collection.get("CreationTimestamp"),
)
def delete_collection(self):
"""
Deletes the collection.
"""
try:
self.rekognition_client.delete_collection(CollectionId=self.collection_id)
logger.info("Deleted collection %s.", self.collection_id)
self.collection_id = None
except ClientError:
logger.exception("Couldn't delete collection %s.", self.collection_id)
raise
```
+ API の詳細については、 [AWS SDK for Python (Boto3) API リファレンス](https://docs.aws.amazon.com/goto/boto3/rekognition-2016-06-27/DeleteCollection) で「*DeleteCollection*」を参照してください。
### `DeleteFaces`
次のコード例は、`DeleteFaces` を使用する方法を示しています。
詳細については、「[コレクションから顔を削除する](https://docs.aws.amazon.com/rekognition/latest/dg/delete-faces-procedure.html)」を参照してください。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rekognition#code-examples)での設定と実行の方法を確認してください。
```
class RekognitionCollection:
"""
Encapsulates an Amazon Rekognition collection. This class is a thin wrapper
around parts of the Boto3 Amazon Rekognition API.
"""
def __init__(self, collection, rekognition_client):
"""
Initializes a collection object.
:param collection: Collection data in the format returned by a call to
create_collection.
:param rekognition_client: A Boto3 Rekognition client.
"""
self.collection_id = collection["CollectionId"]
self.collection_arn, self.face_count, self.created = self._unpack_collection(
collection
)
self.rekognition_client = rekognition_client
@staticmethod
def _unpack_collection(collection):
"""
Unpacks optional parts of a collection that can be returned by
describe_collection.
:param collection: The collection data.
:return: A tuple of the data in the collection.
"""
return (
collection.get("CollectionArn"),
collection.get("FaceCount", 0),
collection.get("CreationTimestamp"),
)
def delete_faces(self, face_ids):
"""
Deletes faces from the collection.
:param face_ids: The list of IDs of faces to delete.
:return: The list of IDs of faces that were deleted.
"""
try:
response = self.rekognition_client.delete_faces(
CollectionId=self.collection_id, FaceIds=face_ids
)
deleted_ids = response["DeletedFaces"]
logger.info(
"Deleted %s faces from %s.", len(deleted_ids), self.collection_id
)
except ClientError:
logger.exception("Couldn't delete faces from %s.", self.collection_id)
raise
else:
return deleted_ids
```
+ API の詳細については、[AWS SDK for Python (Boto3) API リファレンス](https://docs.aws.amazon.com/goto/boto3/rekognition-2016-06-27/DeleteFaces) で「*DeleteFaces*」を参照してください。
### `DescribeCollection`
次のコード例は、`DescribeCollection` を使用する方法を示しています。
詳細については、「[コレクションを定義する](https://docs.aws.amazon.com/rekognition/latest/dg/describe-collection-procedure.html)」を参照してください。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rekognition#code-examples)での設定と実行の方法を確認してください。
```
class RekognitionCollection:
"""
Encapsulates an Amazon Rekognition collection. This class is a thin wrapper
around parts of the Boto3 Amazon Rekognition API.
"""
def __init__(self, collection, rekognition_client):
"""
Initializes a collection object.
:param collection: Collection data in the format returned by a call to
create_collection.
:param rekognition_client: A Boto3 Rekognition client.
"""
self.collection_id = collection["CollectionId"]
self.collection_arn, self.face_count, self.created = self._unpack_collection(
collection
)
self.rekognition_client = rekognition_client
@staticmethod
def _unpack_collection(collection):
"""
Unpacks optional parts of a collection that can be returned by
describe_collection.
:param collection: The collection data.
:return: A tuple of the data in the collection.
"""
return (
collection.get("CollectionArn"),
collection.get("FaceCount", 0),
collection.get("CreationTimestamp"),
)
def describe_collection(self):
"""
Gets data about the collection from the Amazon Rekognition service.
:return: The collection rendered as a dict.
"""
try:
response = self.rekognition_client.describe_collection(
CollectionId=self.collection_id
)
# Work around capitalization of Arn vs. ARN
response["CollectionArn"] = response.get("CollectionARN")
(
self.collection_arn,
self.face_count,
self.created,
) = self._unpack_collection(response)
logger.info("Got data for collection %s.", self.collection_id)
except ClientError:
logger.exception("Couldn't get data for collection %s.", self.collection_id)
raise
else:
return self.to_dict()
```
+ API の詳細については、[AWS SDK for Python (Boto3) API リファレンス](https://docs.aws.amazon.com/goto/boto3/rekognition-2016-06-27/DescribeCollection)の「*DescribeCollection*」を参照してください。
### `DetectFaces`
次のコード例は、`DetectFaces` を使用する方法を示しています。
詳細については、「[イメージ内の顔を検出する](https://docs.aws.amazon.com/rekognition/latest/dg/faces-detect-images.html)」を参照してください。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rekognition#code-examples)での設定と実行の方法を確認してください。
```
class RekognitionImage:
"""
Encapsulates an Amazon Rekognition image. This class is a thin wrapper
around parts of the Boto3 Amazon Rekognition API.
"""
def __init__(self, image, image_name, rekognition_client):
"""
Initializes the image object.
:param image: Data that defines the image, either the image bytes or
an Amazon S3 bucket and object key.
:param image_name: The name of the image.
:param rekognition_client: A Boto3 Rekognition client.
"""
self.image = image
self.image_name = image_name
self.rekognition_client = rekognition_client
def detect_faces(self):
"""
Detects faces in the image.
:return: The list of faces found in the image.
"""
try:
response = self.rekognition_client.detect_faces(
Image=self.image, Attributes=["ALL"]
)
faces = [RekognitionFace(face) for face in response["FaceDetails"]]
logger.info("Detected %s faces.", len(faces))
except ClientError:
logger.exception("Couldn't detect faces in %s.", self.image_name)
raise
else:
return faces
```
+ API の詳細については、[AWS SDK for Python (Boto3) API リファレンス](https://docs.aws.amazon.com/goto/boto3/rekognition-2016-06-27/DetectFaces) の「*DetectFaces*」を参照してください。
### `DetectLabels`
次のコード例は、`DetectLabels` を使用する方法を示しています。
詳細については、「[イメージ内のラベルを検出する](https://docs.aws.amazon.com/rekognition/latest/dg/labels-detect-labels-image.html)」を参照してください。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rekognition#code-examples)での設定と実行の方法を確認してください。
```
class RekognitionImage:
"""
Encapsulates an Amazon Rekognition image. This class is a thin wrapper
around parts of the Boto3 Amazon Rekognition API.
"""
def __init__(self, image, image_name, rekognition_client):
"""
Initializes the image object.
:param image: Data that defines the image, either the image bytes or
an Amazon S3 bucket and object key.
:param image_name: The name of the image.
:param rekognition_client: A Boto3 Rekognition client.
"""
self.image = image
self.image_name = image_name
self.rekognition_client = rekognition_client
def detect_labels(self, max_labels):
"""
Detects labels in the image. Labels are objects and people.
:param max_labels: The maximum number of labels to return.
:return: The list of labels detected in the image.
"""
try:
response = self.rekognition_client.detect_labels(
Image=self.image, MaxLabels=max_labels
)
labels = [RekognitionLabel(label) for label in response["Labels"]]
logger.info("Found %s labels in %s.", len(labels), self.image_name)
except ClientError:
logger.info("Couldn't detect labels in %s.", self.image_name)
raise
else:
return labels
```
+ API の詳細については、[AWS SDK for Python (Boto3) API リファレンス](https://docs.aws.amazon.com/goto/boto3/rekognition-2016-06-27/DetectLabels) の「*DetectLabels*」を参照してください。
### `DetectModerationLabels`
次のコード例は、`DetectModerationLabels` を使用する方法を示しています。
詳細については、「[不適切なイメージを検出する](https://docs.aws.amazon.com/rekognition/latest/dg/procedure-moderate-images.html)」を参照してください。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rekognition#code-examples)での設定と実行の方法を確認してください。
```
class RekognitionImage:
"""
Encapsulates an Amazon Rekognition image. This class is a thin wrapper
around parts of the Boto3 Amazon Rekognition API.
"""
def __init__(self, image, image_name, rekognition_client):
"""
Initializes the image object.
:param image: Data that defines the image, either the image bytes or
an Amazon S3 bucket and object key.
:param image_name: The name of the image.
:param rekognition_client: A Boto3 Rekognition client.
"""
self.image = image
self.image_name = image_name
self.rekognition_client = rekognition_client
def detect_moderation_labels(self):
"""
Detects moderation labels in the image. Moderation labels identify content
that may be inappropriate for some audiences.
:return: The list of moderation labels found in the image.
"""
try:
response = self.rekognition_client.detect_moderation_labels(
Image=self.image
)
labels = [
RekognitionModerationLabel(label)
for label in response["ModerationLabels"]
]
logger.info(
"Found %s moderation labels in %s.", len(labels), self.image_name
)
except ClientError:
logger.exception(
"Couldn't detect moderation labels in %s.", self.image_name
)
raise
else:
return labels
```
+ API の詳細については、「**AWS SDK for Python (Boto3) API リファレンス」の「[DetectModerationLabels](https://docs.aws.amazon.com/goto/boto3/rekognition-2016-06-27/DetectModerationLabels)」を参照してください。
### `DetectText`
次のコード例は、`DetectText` を使用する方法を示しています。
詳細については、「[イメージ内のテキストを検出する](https://docs.aws.amazon.com/rekognition/latest/dg/text-detecting-text-procedure.html)」を参照してください。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rekognition#code-examples)での設定と実行の方法を確認してください。
```
class RekognitionImage:
"""
Encapsulates an Amazon Rekognition image. This class is a thin wrapper
around parts of the Boto3 Amazon Rekognition API.
"""
def __init__(self, image, image_name, rekognition_client):
"""
Initializes the image object.
:param image: Data that defines the image, either the image bytes or
an Amazon S3 bucket and object key.
:param image_name: The name of the image.
:param rekognition_client: A Boto3 Rekognition client.
"""
self.image = image
self.image_name = image_name
self.rekognition_client = rekognition_client
def detect_text(self):
"""
Detects text in the image.
:return The list of text elements found in the image.
"""
try:
response = self.rekognition_client.detect_text(Image=self.image)
texts = [RekognitionText(text) for text in response["TextDetections"]]
logger.info("Found %s texts in %s.", len(texts), self.image_name)
except ClientError:
logger.exception("Couldn't detect text in %s.", self.image_name)
raise
else:
return texts
```
+ API の詳細については、[https://docs.aws.amazon.com/goto/boto3/rekognition-2016-06-27/DetectText](https://docs.aws.amazon.com/goto/boto3/rekognition-2016-06-27/DetectText) SDK for Python (Boto3) API リファレンス* の「AWS DetectText*」を参照してください。
### `IndexFaces`
次の例は、`IndexFaces` を使用する方法を説明しています。
詳細については、「[コレクションに顔を追加する](https://docs.aws.amazon.com/rekognition/latest/dg/add-faces-to-collection-procedure.html)」を参照してください。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rekognition#code-examples)での設定と実行の方法を確認してください。
```
class RekognitionCollection:
"""
Encapsulates an Amazon Rekognition collection. This class is a thin wrapper
around parts of the Boto3 Amazon Rekognition API.
"""
def __init__(self, collection, rekognition_client):
"""
Initializes a collection object.
:param collection: Collection data in the format returned by a call to
create_collection.
:param rekognition_client: A Boto3 Rekognition client.
"""
self.collection_id = collection["CollectionId"]
self.collection_arn, self.face_count, self.created = self._unpack_collection(
collection
)
self.rekognition_client = rekognition_client
@staticmethod
def _unpack_collection(collection):
"""
Unpacks optional parts of a collection that can be returned by
describe_collection.
:param collection: The collection data.
:return: A tuple of the data in the collection.
"""
return (
collection.get("CollectionArn"),
collection.get("FaceCount", 0),
collection.get("CreationTimestamp"),
)
def index_faces(self, image, max_faces):
"""
Finds faces in the specified image, indexes them, and stores them in the
collection.
:param image: The image to index.
:param max_faces: The maximum number of faces to index.
:return: A tuple. The first element is a list of indexed faces.
The second element is a list of faces that couldn't be indexed.
"""
try:
response = self.rekognition_client.index_faces(
CollectionId=self.collection_id,
Image=image.image,
ExternalImageId=image.image_name,
MaxFaces=max_faces,
DetectionAttributes=["ALL"],
)
indexed_faces = [
RekognitionFace({**face["Face"], **face["FaceDetail"]})
for face in response["FaceRecords"]
]
unindexed_faces = [
RekognitionFace(face["FaceDetail"])
for face in response["UnindexedFaces"]
]
logger.info(
"Indexed %s faces in %s. Could not index %s faces.",
len(indexed_faces),
image.image_name,
len(unindexed_faces),
)
except ClientError:
logger.exception("Couldn't index faces in image %s.", image.image_name)
raise
else:
return indexed_faces, unindexed_faces
```
+ API の詳細については、[AWS SDK for Python (Boto3) API リファレンス](https://docs.aws.amazon.com/goto/boto3/rekognition-2016-06-27/IndexFaces)の「*IndexFaces*」を参照してください。
### `ListCollections`
次のコード例は、`ListCollections` を使用する方法を示しています。
コレクションの詳細については、「[コレクションを一覧表示する](https://docs.aws.amazon.com/rekognition/latest/dg/list-collection-procedure.html)」を参照してください。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rekognition#code-examples)での設定と実行の方法を確認してください。
```
class RekognitionCollectionManager:
"""
Encapsulates Amazon Rekognition collection management functions.
This class is a thin wrapper around parts of the Boto3 Amazon Rekognition API.
"""
def __init__(self, rekognition_client):
"""
Initializes the collection manager object.
:param rekognition_client: A Boto3 Rekognition client.
"""
self.rekognition_client = rekognition_client
def list_collections(self, max_results):
"""
Lists collections for the current account.
:param max_results: The maximum number of collections to return.
:return: The list of collections for the current account.
"""
try:
response = self.rekognition_client.list_collections(MaxResults=max_results)
collections = [
RekognitionCollection({"CollectionId": col_id}, self.rekognition_client)
for col_id in response["CollectionIds"]
]
except ClientError:
logger.exception("Couldn't list collections.")
raise
else:
return collections
```
+ API の詳細については、[AWS SDK for Python (Boto3) API リファレンス](https://docs.aws.amazon.com/goto/boto3/rekognition-2016-06-27/ListCollections)の「*ListCollections*」を参照してください。
### `ListFaces`
次のコード例は、`ListFaces` を使用する方法を示しています。
詳細については、「[コレクションに顔を保存する](https://docs.aws.amazon.com/rekognition/latest/dg/list-faces-in-collection-procedure.html)」を参照してください。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rekognition#code-examples)での設定と実行の方法を確認してください。
```
class RekognitionCollection:
"""
Encapsulates an Amazon Rekognition collection. This class is a thin wrapper
around parts of the Boto3 Amazon Rekognition API.
"""
def __init__(self, collection, rekognition_client):
"""
Initializes a collection object.
:param collection: Collection data in the format returned by a call to
create_collection.
:param rekognition_client: A Boto3 Rekognition client.
"""
self.collection_id = collection["CollectionId"]
self.collection_arn, self.face_count, self.created = self._unpack_collection(
collection
)
self.rekognition_client = rekognition_client
@staticmethod
def _unpack_collection(collection):
"""
Unpacks optional parts of a collection that can be returned by
describe_collection.
:param collection: The collection data.
:return: A tuple of the data in the collection.
"""
return (
collection.get("CollectionArn"),
collection.get("FaceCount", 0),
collection.get("CreationTimestamp"),
)
def list_faces(self, max_results):
"""
Lists the faces currently indexed in the collection.
:param max_results: The maximum number of faces to return.
:return: The list of faces in the collection.
"""
try:
response = self.rekognition_client.list_faces(
CollectionId=self.collection_id, MaxResults=max_results
)
faces = [RekognitionFace(face) for face in response["Faces"]]
logger.info(
"Found %s faces in collection %s.", len(faces), self.collection_id
)
except ClientError:
logger.exception(
"Couldn't list faces in collection %s.", self.collection_id
)
raise
else:
return faces
```
+ API の詳細については、[https://docs.aws.amazon.com/goto/boto3/rekognition-2016-06-27/ListFaces](https://docs.aws.amazon.com/goto/boto3/rekognition-2016-06-27/ListFaces) SDK for Python (Boto3) API リファレンス* で「AWS ListFaces*」を参照してください。
### `RecognizeCelebrities`
次のコード例は、`RecognizeCelebrities` を使用する方法を示しています。
詳細については、「[イメージ内で有名人を認識する](https://docs.aws.amazon.com/rekognition/latest/dg/celebrities-procedure-image.html)」を参照してください。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rekognition#code-examples)での設定と実行の方法を確認してください。
```
class RekognitionImage:
"""
Encapsulates an Amazon Rekognition image. This class is a thin wrapper
around parts of the Boto3 Amazon Rekognition API.
"""
def __init__(self, image, image_name, rekognition_client):
"""
Initializes the image object.
:param image: Data that defines the image, either the image bytes or
an Amazon S3 bucket and object key.
:param image_name: The name of the image.
:param rekognition_client: A Boto3 Rekognition client.
"""
self.image = image
self.image_name = image_name
self.rekognition_client = rekognition_client
def recognize_celebrities(self):
"""
Detects celebrities in the image.
:return: A tuple. The first element is the list of celebrities found in
the image. The second element is the list of faces that were
detected but did not match any known celebrities.
"""
try:
response = self.rekognition_client.recognize_celebrities(Image=self.image)
celebrities = [
RekognitionCelebrity(celeb) for celeb in response["CelebrityFaces"]
]
other_faces = [
RekognitionFace(face) for face in response["UnrecognizedFaces"]
]
logger.info(
"Found %s celebrities and %s other faces in %s.",
len(celebrities),
len(other_faces),
self.image_name,
)
except ClientError:
logger.exception("Couldn't detect celebrities in %s.", self.image_name)
raise
else:
return celebrities, other_faces
```
+ API の詳細については、「[AWS SDK for Python (Boto3) API リファレンス](https://docs.aws.amazon.com/goto/boto3/rekognition-2016-06-27/RecognizeCelebrities)の *RecognizeCelebrities*」を参照してください。
### `SearchFaces`
次のコード例は、`SearchFaces` を使用する方法を示しています。
詳細については、[顔 (フェイス ID) を検索する](https://docs.aws.amazon.com/rekognition/latest/dg/search-face-with-id-procedure.html) を参照してください。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rekognition#code-examples)での設定と実行の方法を確認してください。
```
class RekognitionCollection:
"""
Encapsulates an Amazon Rekognition collection. This class is a thin wrapper
around parts of the Boto3 Amazon Rekognition API.
"""
def __init__(self, collection, rekognition_client):
"""
Initializes a collection object.
:param collection: Collection data in the format returned by a call to
create_collection.
:param rekognition_client: A Boto3 Rekognition client.
"""
self.collection_id = collection["CollectionId"]
self.collection_arn, self.face_count, self.created = self._unpack_collection(
collection
)
self.rekognition_client = rekognition_client
@staticmethod
def _unpack_collection(collection):
"""
Unpacks optional parts of a collection that can be returned by
describe_collection.
:param collection: The collection data.
:return: A tuple of the data in the collection.
"""
return (
collection.get("CollectionArn"),
collection.get("FaceCount", 0),
collection.get("CreationTimestamp"),
)
def search_faces(self, face_id, threshold, max_faces):
"""
Searches for faces in the collection that match another face from the
collection.
:param face_id: The ID of the face in the collection to search for.
:param threshold: The match confidence must be greater than this value
for a face to be included in the results.
:param max_faces: The maximum number of faces to return.
:return: The list of matching faces found in the collection. This list does
not contain the face specified by `face_id`.
"""
try:
response = self.rekognition_client.search_faces(
CollectionId=self.collection_id,
FaceId=face_id,
FaceMatchThreshold=threshold,
MaxFaces=max_faces,
)
faces = [RekognitionFace(face["Face"]) for face in response["FaceMatches"]]
logger.info(
"Found %s faces in %s that match %s.",
len(faces),
self.collection_id,
face_id,
)
except ClientError:
logger.exception(
"Couldn't search for faces in %s that match %s.",
self.collection_id,
face_id,
)
raise
else:
return faces
```
+ API の詳細については、[AWS SDK for Python (Boto3) API リファレンス](https://docs.aws.amazon.com/goto/boto3/rekognition-2016-06-27/SearchFaces) の「*SearchFaces*」を参照してください。
### `SearchFacesByImage`
次のコード例は、`SearchFacesByImage` を使用する方法を示しています。
詳細については、「[顔を検索する (イメージ)](https://docs.aws.amazon.com/rekognition/latest/dg/search-face-with-image-procedure.html)」を参照してください。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rekognition#code-examples)での設定と実行の方法を確認してください。
```
class RekognitionCollection:
"""
Encapsulates an Amazon Rekognition collection. This class is a thin wrapper
around parts of the Boto3 Amazon Rekognition API.
"""
def __init__(self, collection, rekognition_client):
"""
Initializes a collection object.
:param collection: Collection data in the format returned by a call to
create_collection.
:param rekognition_client: A Boto3 Rekognition client.
"""
self.collection_id = collection["CollectionId"]
self.collection_arn, self.face_count, self.created = self._unpack_collection(
collection
)
self.rekognition_client = rekognition_client
@staticmethod
def _unpack_collection(collection):
"""
Unpacks optional parts of a collection that can be returned by
describe_collection.
:param collection: The collection data.
:return: A tuple of the data in the collection.
"""
return (
collection.get("CollectionArn"),
collection.get("FaceCount", 0),
collection.get("CreationTimestamp"),
)
def search_faces_by_image(self, image, threshold, max_faces):
"""
Searches for faces in the collection that match the largest face in the
reference image.
:param image: The image that contains the reference face to search for.
:param threshold: The match confidence must be greater than this value
for a face to be included in the results.
:param max_faces: The maximum number of faces to return.
:return: A tuple. The first element is the face found in the reference image.
The second element is the list of matching faces found in the
collection.
"""
try:
response = self.rekognition_client.search_faces_by_image(
CollectionId=self.collection_id,
Image=image.image,
FaceMatchThreshold=threshold,
MaxFaces=max_faces,
)
image_face = RekognitionFace(
{
"BoundingBox": response["SearchedFaceBoundingBox"],
"Confidence": response["SearchedFaceConfidence"],
}
)
collection_faces = [
RekognitionFace(face["Face"]) for face in response["FaceMatches"]
]
logger.info(
"Found %s faces in the collection that match the largest "
"face in %s.",
len(collection_faces),
image.image_name,
)
except ClientError:
logger.exception(
"Couldn't search for faces in %s that match %s.",
self.collection_id,
image.image_name,
)
raise
else:
return image_face, collection_faces
```
+ API の詳細については、[AWS SDK for Python (Boto3) API リファレンス](https://docs.aws.amazon.com/goto/boto3/rekognition-2016-06-27/SearchFacesByImage) の「*SearchFacesByImage*」を参照してください。
## シナリオ
### コレクションを構築し、その中に顔を検索します。
次のコード例は、以下の操作方法を示しています。
+ Amazon Rekognition コレクションを作成します。
+ このコレクションにイメージを追加し、その中から顔を検出します。
+ 参照イメージに一致する顔をコレクション内で検索します。
+ コレクションを削除します。
詳細については、[コレクション内の顔を検索するには](https://docs.aws.amazon.com/rekognition/latest/dg/collections.html) を参照してください。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rekognition#code-examples)での設定と実行の方法を確認してください。
Amazon Rekognition 関数をラップするクラスを作成します。
```
import logging
from pprint import pprint
import boto3
from botocore.exceptions import ClientError
from rekognition_objects import RekognitionFace
from rekognition_image_detection import RekognitionImage
logger = logging.getLogger(__name__)
class RekognitionImage:
"""
Encapsulates an Amazon Rekognition image. This class is a thin wrapper
around parts of the Boto3 Amazon Rekognition API.
"""
def __init__(self, image, image_name, rekognition_client):
"""
Initializes the image object.
:param image: Data that defines the image, either the image bytes or
an Amazon S3 bucket and object key.
:param image_name: The name of the image.
:param rekognition_client: A Boto3 Rekognition client.
"""
self.image = image
self.image_name = image_name
self.rekognition_client = rekognition_client
@classmethod
def from_file(cls, image_file_name, rekognition_client, image_name=None):
"""
Creates a RekognitionImage object from a local file.
:param image_file_name: The file name of the image. The file is opened and its
bytes are read.
:param rekognition_client: A Boto3 Rekognition client.
:param image_name: The name of the image. If this is not specified, the
file name is used as the image name.
:return: The RekognitionImage object, initialized with image bytes from the
file.
"""
with open(image_file_name, "rb") as img_file:
image = {"Bytes": img_file.read()}
name = image_file_name if image_name is None else image_name
return cls(image, name, rekognition_client)
class RekognitionCollectionManager:
"""
Encapsulates Amazon Rekognition collection management functions.
This class is a thin wrapper around parts of the Boto3 Amazon Rekognition API.
"""
def __init__(self, rekognition_client):
"""
Initializes the collection manager object.
:param rekognition_client: A Boto3 Rekognition client.
"""
self.rekognition_client = rekognition_client
def create_collection(self, collection_id):
"""
Creates an empty collection.
:param collection_id: Text that identifies the collection.
:return: The newly created collection.
"""
try:
response = self.rekognition_client.create_collection(
CollectionId=collection_id
)
response["CollectionId"] = collection_id
collection = RekognitionCollection(response, self.rekognition_client)
logger.info("Created collection %s.", collection_id)
except ClientError:
logger.exception("Couldn't create collection %s.", collection_id)
raise
else:
return collection
def list_collections(self, max_results):
"""
Lists collections for the current account.
:param max_results: The maximum number of collections to return.
:return: The list of collections for the current account.
"""
try:
response = self.rekognition_client.list_collections(MaxResults=max_results)
collections = [
RekognitionCollection({"CollectionId": col_id}, self.rekognition_client)
for col_id in response["CollectionIds"]
]
except ClientError:
logger.exception("Couldn't list collections.")
raise
else:
return collections
class RekognitionCollection:
"""
Encapsulates an Amazon Rekognition collection. This class is a thin wrapper
around parts of the Boto3 Amazon Rekognition API.
"""
def __init__(self, collection, rekognition_client):
"""
Initializes a collection object.
:param collection: Collection data in the format returned by a call to
create_collection.
:param rekognition_client: A Boto3 Rekognition client.
"""
self.collection_id = collection["CollectionId"]
self.collection_arn, self.face_count, self.created = self._unpack_collection(
collection
)
self.rekognition_client = rekognition_client
@staticmethod
def _unpack_collection(collection):
"""
Unpacks optional parts of a collection that can be returned by
describe_collection.
:param collection: The collection data.
:return: A tuple of the data in the collection.
"""
return (
collection.get("CollectionArn"),
collection.get("FaceCount", 0),
collection.get("CreationTimestamp"),
)
def to_dict(self):
"""
Renders parts of the collection data to a dict.
:return: The collection data as a dict.
"""
rendering = {
"collection_id": self.collection_id,
"collection_arn": self.collection_arn,
"face_count": self.face_count,
"created": self.created,
}
return rendering
def describe_collection(self):
"""
Gets data about the collection from the Amazon Rekognition service.
:return: The collection rendered as a dict.
"""
try:
response = self.rekognition_client.describe_collection(
CollectionId=self.collection_id
)
# Work around capitalization of Arn vs. ARN
response["CollectionArn"] = response.get("CollectionARN")
(
self.collection_arn,
self.face_count,
self.created,
) = self._unpack_collection(response)
logger.info("Got data for collection %s.", self.collection_id)
except ClientError:
logger.exception("Couldn't get data for collection %s.", self.collection_id)
raise
else:
return self.to_dict()
def delete_collection(self):
"""
Deletes the collection.
"""
try:
self.rekognition_client.delete_collection(CollectionId=self.collection_id)
logger.info("Deleted collection %s.", self.collection_id)
self.collection_id = None
except ClientError:
logger.exception("Couldn't delete collection %s.", self.collection_id)
raise
def index_faces(self, image, max_faces):
"""
Finds faces in the specified image, indexes them, and stores them in the
collection.
:param image: The image to index.
:param max_faces: The maximum number of faces to index.
:return: A tuple. The first element is a list of indexed faces.
The second element is a list of faces that couldn't be indexed.
"""
try:
response = self.rekognition_client.index_faces(
CollectionId=self.collection_id,
Image=image.image,
ExternalImageId=image.image_name,
MaxFaces=max_faces,
DetectionAttributes=["ALL"],
)
indexed_faces = [
RekognitionFace({**face["Face"], **face["FaceDetail"]})
for face in response["FaceRecords"]
]
unindexed_faces = [
RekognitionFace(face["FaceDetail"])
for face in response["UnindexedFaces"]
]
logger.info(
"Indexed %s faces in %s. Could not index %s faces.",
len(indexed_faces),
image.image_name,
len(unindexed_faces),
)
except ClientError:
logger.exception("Couldn't index faces in image %s.", image.image_name)
raise
else:
return indexed_faces, unindexed_faces
def list_faces(self, max_results):
"""
Lists the faces currently indexed in the collection.
:param max_results: The maximum number of faces to return.
:return: The list of faces in the collection.
"""
try:
response = self.rekognition_client.list_faces(
CollectionId=self.collection_id, MaxResults=max_results
)
faces = [RekognitionFace(face) for face in response["Faces"]]
logger.info(
"Found %s faces in collection %s.", len(faces), self.collection_id
)
except ClientError:
logger.exception(
"Couldn't list faces in collection %s.", self.collection_id
)
raise
else:
return faces
def search_faces(self, face_id, threshold, max_faces):
"""
Searches for faces in the collection that match another face from the
collection.
:param face_id: The ID of the face in the collection to search for.
:param threshold: The match confidence must be greater than this value
for a face to be included in the results.
:param max_faces: The maximum number of faces to return.
:return: The list of matching faces found in the collection. This list does
not contain the face specified by `face_id`.
"""
try:
response = self.rekognition_client.search_faces(
CollectionId=self.collection_id,
FaceId=face_id,
FaceMatchThreshold=threshold,
MaxFaces=max_faces,
)
faces = [RekognitionFace(face["Face"]) for face in response["FaceMatches"]]
logger.info(
"Found %s faces in %s that match %s.",
len(faces),
self.collection_id,
face_id,
)
except ClientError:
logger.exception(
"Couldn't search for faces in %s that match %s.",
self.collection_id,
face_id,
)
raise
else:
return faces
def search_faces_by_image(self, image, threshold, max_faces):
"""
Searches for faces in the collection that match the largest face in the
reference image.
:param image: The image that contains the reference face to search for.
:param threshold: The match confidence must be greater than this value
for a face to be included in the results.
:param max_faces: The maximum number of faces to return.
:return: A tuple. The first element is the face found in the reference image.
The second element is the list of matching faces found in the
collection.
"""
try:
response = self.rekognition_client.search_faces_by_image(
CollectionId=self.collection_id,
Image=image.image,
FaceMatchThreshold=threshold,
MaxFaces=max_faces,
)
image_face = RekognitionFace(
{
"BoundingBox": response["SearchedFaceBoundingBox"],
"Confidence": response["SearchedFaceConfidence"],
}
)
collection_faces = [
RekognitionFace(face["Face"]) for face in response["FaceMatches"]
]
logger.info(
"Found %s faces in the collection that match the largest "
"face in %s.",
len(collection_faces),
image.image_name,
)
except ClientError:
logger.exception(
"Couldn't search for faces in %s that match %s.",
self.collection_id,
image.image_name,
)
raise
else:
return image_face, collection_faces
class RekognitionFace:
"""Encapsulates an Amazon Rekognition face."""
def __init__(self, face, timestamp=None):
"""
Initializes the face object.
:param face: Face data, in the format returned by Amazon Rekognition
functions.
:param timestamp: The time when the face was detected, if the face was
detected in a video.
"""
self.bounding_box = face.get("BoundingBox")
self.confidence = face.get("Confidence")
self.landmarks = face.get("Landmarks")
self.pose = face.get("Pose")
self.quality = face.get("Quality")
age_range = face.get("AgeRange")
if age_range is not None:
self.age_range = (age_range.get("Low"), age_range.get("High"))
else:
self.age_range = None
self.smile = face.get("Smile", {}).get("Value")
self.eyeglasses = face.get("Eyeglasses", {}).get("Value")
self.sunglasses = face.get("Sunglasses", {}).get("Value")
self.gender = face.get("Gender", {}).get("Value", None)
self.beard = face.get("Beard", {}).get("Value")
self.mustache = face.get("Mustache", {}).get("Value")
self.eyes_open = face.get("EyesOpen", {}).get("Value")
self.mouth_open = face.get("MouthOpen", {}).get("Value")
self.emotions = [
emo.get("Type")
for emo in face.get("Emotions", [])
if emo.get("Confidence", 0) > 50
]
self.face_id = face.get("FaceId")
self.image_id = face.get("ImageId")
self.timestamp = timestamp
def to_dict(self):
"""
Renders some of the face data to a dict.
:return: A dict that contains the face data.
"""
rendering = {}
if self.bounding_box is not None:
rendering["bounding_box"] = self.bounding_box
if self.age_range is not None:
rendering["age"] = f"{self.age_range[0]} - {self.age_range[1]}"
if self.gender is not None:
rendering["gender"] = self.gender
if self.emotions:
rendering["emotions"] = self.emotions
if self.face_id is not None:
rendering["face_id"] = self.face_id
if self.image_id is not None:
rendering["image_id"] = self.image_id
if self.timestamp is not None:
rendering["timestamp"] = self.timestamp
has = []
if self.smile:
has.append("smile")
if self.eyeglasses:
has.append("eyeglasses")
if self.sunglasses:
has.append("sunglasses")
if self.beard:
has.append("beard")
if self.mustache:
has.append("mustache")
if self.eyes_open:
has.append("open eyes")
if self.mouth_open:
has.append("open mouth")
if has:
rendering["has"] = has
return rendering
```
ラッパークラスを使用して、一連のイメージから顔のコレクションを作成し、コレクション内の顔を検索します。
```
def usage_demo():
print("-" * 88)
print("Welcome to the Amazon Rekognition face collection demo!")
print("-" * 88)
logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
rekognition_client = boto3.client("rekognition")
images = [
RekognitionImage.from_file(
".media/pexels-agung-pandit-wiguna-1128316.jpg",
rekognition_client,
image_name="sitting",
),
RekognitionImage.from_file(
".media/pexels-agung-pandit-wiguna-1128317.jpg",
rekognition_client,
image_name="hopping",
),
RekognitionImage.from_file(
".media/pexels-agung-pandit-wiguna-1128318.jpg",
rekognition_client,
image_name="biking",
),
]
collection_mgr = RekognitionCollectionManager(rekognition_client)
collection = collection_mgr.create_collection("doc-example-collection-demo")
print(f"Created collection {collection.collection_id}:")
pprint(collection.describe_collection())
print("Indexing faces from three images:")
for image in images:
collection.index_faces(image, 10)
print("Listing faces in collection:")
faces = collection.list_faces(10)
for face in faces:
pprint(face.to_dict())
input("Press Enter to continue.")
print(
f"Searching for faces in the collection that match the first face in the "
f"list (Face ID: {faces[0].face_id}."
)
found_faces = collection.search_faces(faces[0].face_id, 80, 10)
print(f"Found {len(found_faces)} matching faces.")
for face in found_faces:
pprint(face.to_dict())
input("Press Enter to continue.")
print(
f"Searching for faces in the collection that match the largest face in "
f"{images[0].image_name}."
)
image_face, match_faces = collection.search_faces_by_image(images[0], 80, 10)
print(f"The largest face in {images[0].image_name} is:")
pprint(image_face.to_dict())
print(f"Found {len(match_faces)} matching faces.")
for face in match_faces:
pprint(face.to_dict())
input("Press Enter to continue.")
collection.delete_collection()
print("Thanks for watching!")
print("-" * 88)
```
### イメージ内の要素の検出と表示
次のコード例は、以下の操作方法を示しています。
+ Amazon Rekognition を使用してイメージから要素を検出します。
+ イメージを表示し、検出された要素の周囲に境界ボックスを描画します。
詳細については、[境界ボックスの表示](https://docs.aws.amazon.com/rekognition/latest/dg/images-displaying-bounding-boxes.html) を参照してください。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rekognition#code-examples)での設定と実行の方法を確認してください。
Amazon Rekognition 関数をラップするクラスを作成します。
```
import logging
from pprint import pprint
import boto3
from botocore.exceptions import ClientError
import requests
from rekognition_objects import (
RekognitionFace,
RekognitionCelebrity,
RekognitionLabel,
RekognitionModerationLabel,
RekognitionText,
show_bounding_boxes,
show_polygons,
)
logger = logging.getLogger(__name__)
class RekognitionImage:
"""
Encapsulates an Amazon Rekognition image. This class is a thin wrapper
around parts of the Boto3 Amazon Rekognition API.
"""
def __init__(self, image, image_name, rekognition_client):
"""
Initializes the image object.
:param image: Data that defines the image, either the image bytes or
an Amazon S3 bucket and object key.
:param image_name: The name of the image.
:param rekognition_client: A Boto3 Rekognition client.
"""
self.image = image
self.image_name = image_name
self.rekognition_client = rekognition_client
@classmethod
def from_file(cls, image_file_name, rekognition_client, image_name=None):
"""
Creates a RekognitionImage object from a local file.
:param image_file_name: The file name of the image. The file is opened and its
bytes are read.
:param rekognition_client: A Boto3 Rekognition client.
:param image_name: The name of the image. If this is not specified, the
file name is used as the image name.
:return: The RekognitionImage object, initialized with image bytes from the
file.
"""
with open(image_file_name, "rb") as img_file:
image = {"Bytes": img_file.read()}
name = image_file_name if image_name is None else image_name
return cls(image, name, rekognition_client)
@classmethod
def from_bucket(cls, s3_object, rekognition_client):
"""
Creates a RekognitionImage object from an Amazon S3 object.
:param s3_object: An Amazon S3 object that identifies the image. The image
is not retrieved until needed for a later call.
:param rekognition_client: A Boto3 Rekognition client.
:return: The RekognitionImage object, initialized with Amazon S3 object data.
"""
image = {"S3Object": {"Bucket": s3_object.bucket_name, "Name": s3_object.key}}
return cls(image, s3_object.key, rekognition_client)
def detect_faces(self):
"""
Detects faces in the image.
:return: The list of faces found in the image.
"""
try:
response = self.rekognition_client.detect_faces(
Image=self.image, Attributes=["ALL"]
)
faces = [RekognitionFace(face) for face in response["FaceDetails"]]
logger.info("Detected %s faces.", len(faces))
except ClientError:
logger.exception("Couldn't detect faces in %s.", self.image_name)
raise
else:
return faces
def detect_labels(self, max_labels):
"""
Detects labels in the image. Labels are objects and people.
:param max_labels: The maximum number of labels to return.
:return: The list of labels detected in the image.
"""
try:
response = self.rekognition_client.detect_labels(
Image=self.image, MaxLabels=max_labels
)
labels = [RekognitionLabel(label) for label in response["Labels"]]
logger.info("Found %s labels in %s.", len(labels), self.image_name)
except ClientError:
logger.info("Couldn't detect labels in %s.", self.image_name)
raise
else:
return labels
def recognize_celebrities(self):
"""
Detects celebrities in the image.
:return: A tuple. The first element is the list of celebrities found in
the image. The second element is the list of faces that were
detected but did not match any known celebrities.
"""
try:
response = self.rekognition_client.recognize_celebrities(Image=self.image)
celebrities = [
RekognitionCelebrity(celeb) for celeb in response["CelebrityFaces"]
]
other_faces = [
RekognitionFace(face) for face in response["UnrecognizedFaces"]
]
logger.info(
"Found %s celebrities and %s other faces in %s.",
len(celebrities),
len(other_faces),
self.image_name,
)
except ClientError:
logger.exception("Couldn't detect celebrities in %s.", self.image_name)
raise
else:
return celebrities, other_faces
def compare_faces(self, target_image, similarity):
"""
Compares faces in the image with the largest face in the target image.
:param target_image: The target image to compare against.
:param similarity: Faces in the image must have a similarity value greater
than this value to be included in the results.
:return: A tuple. The first element is the list of faces that match the
reference image. The second element is the list of faces that have
a similarity value below the specified threshold.
"""
try:
response = self.rekognition_client.compare_faces(
SourceImage=self.image,
TargetImage=target_image.image,
SimilarityThreshold=similarity,
)
matches = [
RekognitionFace(match["Face"]) for match in response["FaceMatches"]
]
unmatches = [RekognitionFace(face) for face in response["UnmatchedFaces"]]
logger.info(
"Found %s matched faces and %s unmatched faces.",
len(matches),
len(unmatches),
)
except ClientError:
logger.exception(
"Couldn't match faces from %s to %s.",
self.image_name,
target_image.image_name,
)
raise
else:
return matches, unmatches
def detect_moderation_labels(self):
"""
Detects moderation labels in the image. Moderation labels identify content
that may be inappropriate for some audiences.
:return: The list of moderation labels found in the image.
"""
try:
response = self.rekognition_client.detect_moderation_labels(
Image=self.image
)
labels = [
RekognitionModerationLabel(label)
for label in response["ModerationLabels"]
]
logger.info(
"Found %s moderation labels in %s.", len(labels), self.image_name
)
except ClientError:
logger.exception(
"Couldn't detect moderation labels in %s.", self.image_name
)
raise
else:
return labels
def detect_text(self):
"""
Detects text in the image.
:return The list of text elements found in the image.
"""
try:
response = self.rekognition_client.detect_text(Image=self.image)
texts = [RekognitionText(text) for text in response["TextDetections"]]
logger.info("Found %s texts in %s.", len(texts), self.image_name)
except ClientError:
logger.exception("Couldn't detect text in %s.", self.image_name)
raise
else:
return texts
```
境界ボックスとポリゴンを描画するヘルパー関数を作成します。
```
import io
import logging
from PIL import Image, ImageDraw
logger = logging.getLogger(__name__)
def show_bounding_boxes(image_bytes, box_sets, colors):
"""
Draws bounding boxes on an image and shows it with the default image viewer.
:param image_bytes: The image to draw, as bytes.
:param box_sets: A list of lists of bounding boxes to draw on the image.
:param colors: A list of colors to use to draw the bounding boxes.
"""
image = Image.open(io.BytesIO(image_bytes))
draw = ImageDraw.Draw(image)
for boxes, color in zip(box_sets, colors):
for box in boxes:
left = image.width * box["Left"]
top = image.height * box["Top"]
right = (image.width * box["Width"]) + left
bottom = (image.height * box["Height"]) + top
draw.rectangle([left, top, right, bottom], outline=color, width=3)
image.show()
def show_polygons(image_bytes, polygons, color):
"""
Draws polygons on an image and shows it with the default image viewer.
:param image_bytes: The image to draw, as bytes.
:param polygons: The list of polygons to draw on the image.
:param color: The color to use to draw the polygons.
"""
image = Image.open(io.BytesIO(image_bytes))
draw = ImageDraw.Draw(image)
for polygon in polygons:
draw.polygon(
[
(image.width * point["X"], image.height * point["Y"])
for point in polygon
],
outline=color,
)
image.show()
```
Amazon Rekognition から返されたオブジェクトを解析するクラスを作成します。
```
class RekognitionFace:
"""Encapsulates an Amazon Rekognition face."""
def __init__(self, face, timestamp=None):
"""
Initializes the face object.
:param face: Face data, in the format returned by Amazon Rekognition
functions.
:param timestamp: The time when the face was detected, if the face was
detected in a video.
"""
self.bounding_box = face.get("BoundingBox")
self.confidence = face.get("Confidence")
self.landmarks = face.get("Landmarks")
self.pose = face.get("Pose")
self.quality = face.get("Quality")
age_range = face.get("AgeRange")
if age_range is not None:
self.age_range = (age_range.get("Low"), age_range.get("High"))
else:
self.age_range = None
self.smile = face.get("Smile", {}).get("Value")
self.eyeglasses = face.get("Eyeglasses", {}).get("Value")
self.sunglasses = face.get("Sunglasses", {}).get("Value")
self.gender = face.get("Gender", {}).get("Value", None)
self.beard = face.get("Beard", {}).get("Value")
self.mustache = face.get("Mustache", {}).get("Value")
self.eyes_open = face.get("EyesOpen", {}).get("Value")
self.mouth_open = face.get("MouthOpen", {}).get("Value")
self.emotions = [
emo.get("Type")
for emo in face.get("Emotions", [])
if emo.get("Confidence", 0) > 50
]
self.face_id = face.get("FaceId")
self.image_id = face.get("ImageId")
self.timestamp = timestamp
def to_dict(self):
"""
Renders some of the face data to a dict.
:return: A dict that contains the face data.
"""
rendering = {}
if self.bounding_box is not None:
rendering["bounding_box"] = self.bounding_box
if self.age_range is not None:
rendering["age"] = f"{self.age_range[0]} - {self.age_range[1]}"
if self.gender is not None:
rendering["gender"] = self.gender
if self.emotions:
rendering["emotions"] = self.emotions
if self.face_id is not None:
rendering["face_id"] = self.face_id
if self.image_id is not None:
rendering["image_id"] = self.image_id
if self.timestamp is not None:
rendering["timestamp"] = self.timestamp
has = []
if self.smile:
has.append("smile")
if self.eyeglasses:
has.append("eyeglasses")
if self.sunglasses:
has.append("sunglasses")
if self.beard:
has.append("beard")
if self.mustache:
has.append("mustache")
if self.eyes_open:
has.append("open eyes")
if self.mouth_open:
has.append("open mouth")
if has:
rendering["has"] = has
return rendering
class RekognitionCelebrity:
"""Encapsulates an Amazon Rekognition celebrity."""
def __init__(self, celebrity, timestamp=None):
"""
Initializes the celebrity object.
:param celebrity: Celebrity data, in the format returned by Amazon Rekognition
functions.
:param timestamp: The time when the celebrity was detected, if the celebrity
was detected in a video.
"""
self.info_urls = celebrity.get("Urls")
self.name = celebrity.get("Name")
self.id = celebrity.get("Id")
self.face = RekognitionFace(celebrity.get("Face"))
self.confidence = celebrity.get("MatchConfidence")
self.bounding_box = celebrity.get("BoundingBox")
self.timestamp = timestamp
def to_dict(self):
"""
Renders some of the celebrity data to a dict.
:return: A dict that contains the celebrity data.
"""
rendering = self.face.to_dict()
if self.name is not None:
rendering["name"] = self.name
if self.info_urls:
rendering["info URLs"] = self.info_urls
if self.timestamp is not None:
rendering["timestamp"] = self.timestamp
return rendering
class RekognitionPerson:
"""Encapsulates an Amazon Rekognition person."""
def __init__(self, person, timestamp=None):
"""
Initializes the person object.
:param person: Person data, in the format returned by Amazon Rekognition
functions.
:param timestamp: The time when the person was detected, if the person
was detected in a video.
"""
self.index = person.get("Index")
self.bounding_box = person.get("BoundingBox")
face = person.get("Face")
self.face = RekognitionFace(face) if face is not None else None
self.timestamp = timestamp
def to_dict(self):
"""
Renders some of the person data to a dict.
:return: A dict that contains the person data.
"""
rendering = self.face.to_dict() if self.face is not None else {}
if self.index is not None:
rendering["index"] = self.index
if self.bounding_box is not None:
rendering["bounding_box"] = self.bounding_box
if self.timestamp is not None:
rendering["timestamp"] = self.timestamp
return rendering
class RekognitionLabel:
"""Encapsulates an Amazon Rekognition label."""
def __init__(self, label, timestamp=None):
"""
Initializes the label object.
:param label: Label data, in the format returned by Amazon Rekognition
functions.
:param timestamp: The time when the label was detected, if the label
was detected in a video.
"""
self.name = label.get("Name")
self.confidence = label.get("Confidence")
self.instances = label.get("Instances")
self.parents = label.get("Parents")
self.timestamp = timestamp
def to_dict(self):
"""
Renders some of the label data to a dict.
:return: A dict that contains the label data.
"""
rendering = {}
if self.name is not None:
rendering["name"] = self.name
if self.timestamp is not None:
rendering["timestamp"] = self.timestamp
return rendering
class RekognitionModerationLabel:
"""Encapsulates an Amazon Rekognition moderation label."""
def __init__(self, label, timestamp=None):
"""
Initializes the moderation label object.
:param label: Label data, in the format returned by Amazon Rekognition
functions.
:param timestamp: The time when the moderation label was detected, if the
label was detected in a video.
"""
self.name = label.get("Name")
self.confidence = label.get("Confidence")
self.parent_name = label.get("ParentName")
self.timestamp = timestamp
def to_dict(self):
"""
Renders some of the moderation label data to a dict.
:return: A dict that contains the moderation label data.
"""
rendering = {}
if self.name is not None:
rendering["name"] = self.name
if self.parent_name is not None:
rendering["parent_name"] = self.parent_name
if self.timestamp is not None:
rendering["timestamp"] = self.timestamp
return rendering
class RekognitionText:
"""Encapsulates an Amazon Rekognition text element."""
def __init__(self, text_data):
"""
Initializes the text object.
:param text_data: Text data, in the format returned by Amazon Rekognition
functions.
"""
self.text = text_data.get("DetectedText")
self.kind = text_data.get("Type")
self.id = text_data.get("Id")
self.parent_id = text_data.get("ParentId")
self.confidence = text_data.get("Confidence")
self.geometry = text_data.get("Geometry")
def to_dict(self):
"""
Renders some of the text data to a dict.
:return: A dict that contains the text data.
"""
rendering = {}
if self.text is not None:
rendering["text"] = self.text
if self.kind is not None:
rendering["kind"] = self.kind
if self.geometry is not None:
rendering["polygon"] = self.geometry.get("Polygon")
return rendering
```
ラッパークラスを使用して、イメージ内の要素を検出し、その境界ボックスを表示します。この例で使用されているイメージは GitHub で、指示やコードとともに確認できます。
```
def usage_demo():
print("-" * 88)
print("Welcome to the Amazon Rekognition image detection demo!")
print("-" * 88)
logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
rekognition_client = boto3.client("rekognition")
street_scene_file_name = ".media/pexels-kaique-rocha-109919.jpg"
celebrity_file_name = ".media/pexels-pixabay-53370.jpg"
one_girl_url = "https://dhei5unw3vrsx.cloudfront.net/images/source3_resized.jpg"
three_girls_url = "https://dhei5unw3vrsx.cloudfront.net/images/target3_resized.jpg"
swimwear_object = boto3.resource("s3").Object(
"console-sample-images-pdx", "yoga_swimwear.jpg"
)
book_file_name = ".media/pexels-christina-morillo-1181671.jpg"
street_scene_image = RekognitionImage.from_file(
street_scene_file_name, rekognition_client
)
print(f"Detecting faces in {street_scene_image.image_name}...")
faces = street_scene_image.detect_faces()
print(f"Found {len(faces)} faces, here are the first three.")
for face in faces[:3]:
pprint(face.to_dict())
show_bounding_boxes(
street_scene_image.image["Bytes"],
[[face.bounding_box for face in faces]],
["aqua"],
)
input("Press Enter to continue.")
print(f"Detecting labels in {street_scene_image.image_name}...")
labels = street_scene_image.detect_labels(100)
print(f"Found {len(labels)} labels.")
for label in labels:
pprint(label.to_dict())
names = []
box_sets = []
colors = ["aqua", "red", "white", "blue", "yellow", "green"]
for label in labels:
if label.instances:
names.append(label.name)
box_sets.append([inst["BoundingBox"] for inst in label.instances])
print(f"Showing bounding boxes for {names} in {colors[:len(names)]}.")
show_bounding_boxes(
street_scene_image.image["Bytes"], box_sets, colors[: len(names)]
)
input("Press Enter to continue.")
celebrity_image = RekognitionImage.from_file(
celebrity_file_name, rekognition_client
)
print(f"Detecting celebrities in {celebrity_image.image_name}...")
celebs, others = celebrity_image.recognize_celebrities()
print(f"Found {len(celebs)} celebrities.")
for celeb in celebs:
pprint(celeb.to_dict())
show_bounding_boxes(
celebrity_image.image["Bytes"],
[[celeb.face.bounding_box for celeb in celebs]],
["aqua"],
)
input("Press Enter to continue.")
girl_image_response = requests.get(one_girl_url)
girl_image = RekognitionImage(
{"Bytes": girl_image_response.content}, "one-girl", rekognition_client
)
group_image_response = requests.get(three_girls_url)
group_image = RekognitionImage(
{"Bytes": group_image_response.content}, "three-girls", rekognition_client
)
print("Comparing reference face to group of faces...")
matches, unmatches = girl_image.compare_faces(group_image, 80)
print(f"Found {len(matches)} face matching the reference face.")
show_bounding_boxes(
group_image.image["Bytes"],
[[match.bounding_box for match in matches]],
["aqua"],
)
input("Press Enter to continue.")
swimwear_image = RekognitionImage.from_bucket(swimwear_object, rekognition_client)
print(f"Detecting suggestive content in {swimwear_object.key}...")
labels = swimwear_image.detect_moderation_labels()
print(f"Found {len(labels)} moderation labels.")
for label in labels:
pprint(label.to_dict())
input("Press Enter to continue.")
book_image = RekognitionImage.from_file(book_file_name, rekognition_client)
print(f"Detecting text in {book_image.image_name}...")
texts = book_image.detect_text()
print(f"Found {len(texts)} text instances. Here are the first seven:")
for text in texts[:7]:
pprint(text.to_dict())
show_polygons(
book_image.image["Bytes"], [text.geometry["Polygon"] for text in texts], "aqua"
)
print("Thanks for watching!")
print("-" * 88)
```
### 画像内のオブジェクトを検出する
次のコード例は、Amazon Rekognition を使用して画像内でカテゴリ別にオブジェクトを検出するアプリケーションを構築する方法を示しています。
**SDK for Python (Boto3)**
を使用して AWS SDK for Python (Boto3) 、以下を可能にするウェブアプリケーションを作成する方法を示します。
+ Amazon Simple Storage Service (Amazon S3) バケットに、写真をアップロードします。
+ Amazon Rekognition を使用して、写真を分析およびラベル付けします。
+ Amazon Simple Email Service (Amazon SES) を使用して、イメージ分析の E メールレポートを送信します。
この例には、React で構築された JavaScript で記述されたウェブページと、Flask-RESTful で構築された Python で記述された REST サービスの 2 つの主要なコンポーネントが含まれています。
React ウェブページを使用すると、次のことができます。
+ S3 バケットに保存されているイメージのリストを表示します。
+ イメージを S3 バケットにアップロードします。
+ イメージ内で検出された項目を識別するイメージとラベルを表示します。
+ S3 バケット内のすべてのイメージのレポートを取得し、レポートの E メールを送信します。
ウェブページが REST サービスを呼び出します。サービスはリクエストを AWS に送信して、以下のアクションを実行します。
+ S3 バケット内のイメージのリストを取得し、フィルタリングします。
+ Amazon S3 バケットに写真をアップロードします。
+ Amazon Rekognition を使用して個々の写真を分析し、写真で検出された項目を識別するラベルのリストを取得します。
+ S3 バケット内のすべての写真を分析し、Amazon SES を使用してレポートを E メールで送信します。
完全なソースコードとセットアップおよび実行の手順については、[GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/photo_analyzer) で完全な例を参照してください。
**この例で使用されているサービス**
+ Amazon Rekognition
+ Amazon S3
+ Amazon SES
### 動画内の人物や物体を検出する
次のコード例は、Amazon Rekognition で動画内の人やオブジェクトを検出する方法を示します。
**SDK for Python (Boto3)**
Amazon Rekognition を使用して、非同期検出ジョブを開始して、動画内の顔、オブジェクト、人を検出します。この例では、ジョブが完了し、Amazon Simple Queue Service (Amazon SQS) キューをトピックにサブスクライブしたときに、Amazon Simple Notification Service (Amazon SNS) トピックに通知するように Amazon Rekognition を設定します。キューがジョブに関するメッセージを受信すると、ジョブが取得され、結果が出力されます。
この例は GitHub で最もよく見られます。完全なソースコードとセットアップおよび実行の手順については、[GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rekognition) で完全な例を参照してください。
**この例で使用されているサービス**
+ Amazon Rekognition
+ Amazon S3
+ Amazon SES
+ Amazon SNS
+ Amazon SQS
# SDK for Python (Boto3) を使用する Amazon S3 の例
次のコード例は、Amazon S3 AWS SDK for Python (Boto3) で を使用してアクションを実行し、一般的なシナリオを実装する方法を示しています。
*基本* は、重要なオペレーションをサービス内で実行する方法を示すコード例です。
*アクション*はより大きなプログラムからのコードの抜粋であり、コンテキスト内で実行する必要があります。アクションは個々のサービス機能を呼び出す方法を示していますが、コンテキスト内のアクションは、関連するシナリオで確認できます。
*シナリオ*は、1 つのサービス内から、または他の AWS のサービスと組み合わせて複数の関数を呼び出し、特定のタスクを実行する方法を示すコード例です。
各例には完全なソースコードへのリンクが含まれており、コンテキスト内でコードを設定および実行する方法の手順を確認できます。
**Topics**
+ [開始方法](#get_started)
+ [基本](#basics)
+ [アクション](#actions)
+ [シナリオ](#scenarios)
+ [サーバーレスサンプル](#serverless_examples)
## はじめに
### Hello Amazon S3
次のコード例は、Amazon S3 の使用を開始する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3#code-examples)での設定と実行の方法を確認してください。
```
import boto3
def hello_s3():
"""
Use the AWS SDK for Python (Boto3) to create an Amazon Simple Storage Service
(Amazon S3) client and list the buckets in your account.
This example uses the default settings specified in your shared credentials
and config files.
"""
# Create an S3 client.
s3_client = boto3.client("s3")
print("Hello, Amazon S3! Let's list your buckets:")
# Create a paginator for the list_buckets operation.
paginator = s3_client.get_paginator("list_buckets")
# Use the paginator to get a list of all buckets.
response_iterator = paginator.paginate(
PaginationConfig={
"PageSize": 50, # Adjust PageSize as needed.
"StartingToken": None,
}
)
# Iterate through the pages of the response.
buckets_found = False
for page in response_iterator:
if "Buckets" in page and page["Buckets"]:
buckets_found = True
for bucket in page["Buckets"]:
print(f"\t{bucket['Name']}")
if not buckets_found:
print("No buckets found!")
if __name__ == "__main__":
hello_s3()
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[ListBuckets](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/ListBuckets)」を参照してください。
## 基本
### 基本を学ぶ
次のコード例は、以下の操作方法を示しています。
+ バケットを作成し、そこにファイルをアップロードします。
+ バケットからオブジェクトをダウンロードします。
+ バケット内のサブフォルダにオブジェクトをコピーします。
+ バケット内のオブジェクトを一覧表示します。
+ バケットオブジェクトとバケットを削除します。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/s3_basics#code-examples)での設定と実行の方法を確認してください。
```
import io
import os
import uuid
import boto3
from boto3.s3.transfer import S3UploadFailedError
from botocore.exceptions import ClientError
def do_scenario(s3_resource):
print("-" * 88)
print("Welcome to the Amazon S3 getting started demo!")
print("-" * 88)
bucket_name = f"amzn-s3-demo-bucket-{uuid.uuid4()}"
bucket = s3_resource.Bucket(bucket_name)
try:
bucket.create(
CreateBucketConfiguration={
"LocationConstraint": s3_resource.meta.client.meta.region_name
}
)
print(f"Created demo bucket named {bucket.name}.")
except ClientError as err:
print(f"Tried and failed to create demo bucket {bucket_name}.")
print(f"\t{err.response['Error']['Code']}:{err.response['Error']['Message']}")
print(f"\nCan't continue the demo without a bucket!")
return
file_name = None
while file_name is None:
file_name = input("\nEnter a file you want to upload to your bucket: ")
if not os.path.exists(file_name):
print(f"Couldn't find file {file_name}. Are you sure it exists?")
file_name = None
obj = bucket.Object(os.path.basename(file_name))
try:
obj.upload_file(file_name)
print(
f"Uploaded file {file_name} into bucket {bucket.name} with key {obj.key}."
)
except S3UploadFailedError as err:
print(f"Couldn't upload file {file_name} to {bucket.name}.")
print(f"\t{err}")
answer = input(f"\nDo you want to download {obj.key} into memory (y/n)? ")
if answer.lower() == "y":
data = io.BytesIO()
try:
obj.download_fileobj(data)
data.seek(0)
print(f"Got your object. Here are the first 20 bytes:\n")
print(f"\t{data.read(20)}")
except ClientError as err:
print(f"Couldn't download {obj.key}.")
print(
f"\t{err.response['Error']['Code']}:{err.response['Error']['Message']}"
)
answer = input(
f"\nDo you want to copy {obj.key} to a subfolder in your bucket (y/n)? "
)
if answer.lower() == "y":
dest_obj = bucket.Object(f"demo-folder/{obj.key}")
try:
dest_obj.copy({"Bucket": bucket.name, "Key": obj.key})
print(f"Copied {obj.key} to {dest_obj.key}.")
except ClientError as err:
print(f"Couldn't copy {obj.key} to {dest_obj.key}.")
print(
f"\t{err.response['Error']['Code']}:{err.response['Error']['Message']}"
)
print("\nYour bucket contains the following objects:")
try:
for o in bucket.objects.all():
print(f"\t{o.key}")
except ClientError as err:
print(f"Couldn't list the objects in bucket {bucket.name}.")
print(f"\t{err.response['Error']['Code']}:{err.response['Error']['Message']}")
answer = input(
"\nDo you want to delete all of the objects as well as the bucket (y/n)? "
)
if answer.lower() == "y":
try:
bucket.objects.delete()
bucket.delete()
print(f"Emptied and deleted bucket {bucket.name}.\n")
except ClientError as err:
print(f"Couldn't empty and delete bucket {bucket.name}.")
print(
f"\t{err.response['Error']['Code']}:{err.response['Error']['Message']}"
)
print("Thanks for watching!")
print("-" * 88)
if __name__ == "__main__":
do_scenario(boto3.resource("s3"))
```
+ API の詳細については、「**AWS SDK for Python (Boto3) API リファレンス」の以下のトピックを参照してください。
+ [CopyObject](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/CopyObject)
+ [CreateBucket](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/CreateBucket)
+ [DeleteBucket](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/DeleteBucket)
+ [DeleteObjects](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/DeleteObjects)
+ [GetObject](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/GetObject)
+ [ListObjectsV2](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/ListObjectsV2)
+ [PutObject](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/PutObject)
## アクション
### `CopyObject`
次のコード例は、`CopyObject` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/s3_basics#code-examples)での設定と実行の方法を確認してください。
```
class ObjectWrapper:
"""Encapsulates S3 object actions."""
def __init__(self, s3_object):
"""
:param s3_object: A Boto3 Object resource. This is a high-level resource in Boto3
that wraps object actions in a class-like structure.
"""
self.object = s3_object
self.key = self.object.key
def copy(self, dest_object):
"""
Copies the object to another bucket.
:param dest_object: The destination object initialized with a bucket and key.
This is a Boto3 Object resource.
"""
try:
dest_object.copy_from(
CopySource={"Bucket": self.object.bucket_name, "Key": self.object.key}
)
dest_object.wait_until_exists()
logger.info(
"Copied object from %s:%s to %s:%s.",
self.object.bucket_name,
self.object.key,
dest_object.bucket_name,
dest_object.key,
)
except ClientError:
logger.exception(
"Couldn't copy object from %s/%s to %s/%s.",
self.object.bucket_name,
self.object.key,
dest_object.bucket_name,
dest_object.key,
)
raise
```
条件付きリクエストを使用してオブジェクトをコピーします。
```
class S3ConditionalRequests:
"""Encapsulates S3 conditional request operations."""
def __init__(self, s3_client):
self.s3 = s3_client
@classmethod
def from_client(cls):
"""
Instantiates this class from a Boto3 client.
"""
s3_client = boto3.client("s3")
return cls(s3_client)
def copy_object_conditional(
self,
source_key: str,
dest_key: str,
source_bucket: str,
dest_bucket: str,
condition_type: str,
condition_value: str,
):
"""
Copies an object from one Amazon S3 bucket to another with a conditional request.
:param source_key: The key of the source object to copy.
:param dest_key: The key of the destination object.
:param source_bucket: The source bucket of the object.
:param dest_bucket: The destination bucket of the object.
:param condition_type: The type of condition to apply, e.g.
'CopySourceIfMatch', 'CopySourceIfNoneMatch', 'CopySourceIfModifiedSince', 'CopySourceIfUnmodifiedSince'.
:param condition_value: The value to use for the condition.
"""
try:
self.s3.copy_object(
Bucket=dest_bucket,
Key=dest_key,
CopySource={"Bucket": source_bucket, "Key": source_key},
**{condition_type: condition_value},
)
print(
f"\tConditional copy successful for key {dest_key} in bucket {dest_bucket}."
)
except ClientError as e:
error_code = e.response["Error"]["Code"]
if error_code == "PreconditionFailed":
print("\tConditional copy failed: Precondition failed")
elif error_code == "304": # Not modified error code.
print("\tConditional copy failed: Object not modified")
else:
logger.error(f"Unexpected error: {error_code}")
raise
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[CopyObject](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/CopyObject)」を参照してください。
### `CreateBucket`
次のコード例は、`CreateBucket` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/s3_basics#code-examples)での設定と実行の方法を確認してください。
デフォルトの設定でバケットを作成します。
```
class BucketWrapper:
"""Encapsulates S3 bucket actions."""
def __init__(self, bucket):
"""
:param bucket: A Boto3 Bucket resource. This is a high-level resource in Boto3
that wraps bucket actions in a class-like structure.
"""
self.bucket = bucket
self.name = bucket.name
def create(self, region_override=None):
"""
Create an Amazon S3 bucket in the default Region for the account or in the
specified Region.
:param region_override: The Region in which to create the bucket. If this is
not specified, the Region configured in your shared
credentials is used.
"""
if region_override is not None:
region = region_override
else:
region = self.bucket.meta.client.meta.region_name
try:
self.bucket.create(CreateBucketConfiguration={"LocationConstraint": region})
self.bucket.wait_until_exists()
logger.info("Created bucket '%s' in region=%s", self.bucket.name, region)
except ClientError as error:
logger.exception(
"Couldn't create bucket named '%s' in region=%s.",
self.bucket.name,
region,
)
raise error
```
ライフサイクル設定を使用してバージョン対応バケットを作成します。
```
def create_versioned_bucket(bucket_name, prefix):
"""
Creates an Amazon S3 bucket, enables it for versioning, and configures a lifecycle
that expires noncurrent object versions after 7 days.
Adding a lifecycle configuration to a versioned bucket is a best practice.
It helps prevent objects in the bucket from accumulating a large number of
noncurrent versions, which can slow down request performance.
Usage is shown in the usage_demo_single_object function at the end of this module.
:param bucket_name: The name of the bucket to create.
:param prefix: Identifies which objects are automatically expired under the
configured lifecycle rules.
:return: The newly created bucket.
"""
try:
bucket = s3.create_bucket(
Bucket=bucket_name,
CreateBucketConfiguration={
"LocationConstraint": s3.meta.client.meta.region_name
},
)
logger.info("Created bucket %s.", bucket.name)
except ClientError as error:
if error.response["Error"]["Code"] == "BucketAlreadyOwnedByYou":
logger.warning("Bucket %s already exists! Using it.", bucket_name)
bucket = s3.Bucket(bucket_name)
else:
logger.exception("Couldn't create bucket %s.", bucket_name)
raise
try:
bucket.Versioning().enable()
logger.info("Enabled versioning on bucket %s.", bucket.name)
except ClientError:
logger.exception("Couldn't enable versioning on bucket %s.", bucket.name)
raise
try:
expiration = 7
bucket.LifecycleConfiguration().put(
LifecycleConfiguration={
"Rules": [
{
"Status": "Enabled",
"Prefix": prefix,
"NoncurrentVersionExpiration": {"NoncurrentDays": expiration},
}
]
}
)
logger.info(
"Configured lifecycle to expire noncurrent versions after %s days "
"on bucket %s.",
expiration,
bucket.name,
)
except ClientError as error:
logger.warning(
"Couldn't configure lifecycle on bucket %s because %s. "
"Continuing anyway.",
bucket.name,
error,
)
return bucket
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[CreateBucket](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/CreateBucket)」を参照してください。
### `DeleteBucket`
次のコード例は、`DeleteBucket` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/s3_basics#code-examples)での設定と実行の方法を確認してください。
```
class BucketWrapper:
"""Encapsulates S3 bucket actions."""
def __init__(self, bucket):
"""
:param bucket: A Boto3 Bucket resource. This is a high-level resource in Boto3
that wraps bucket actions in a class-like structure.
"""
self.bucket = bucket
self.name = bucket.name
def delete(self):
"""
Delete the bucket. The bucket must be empty or an error is raised.
"""
try:
self.bucket.delete()
self.bucket.wait_until_not_exists()
logger.info("Bucket %s successfully deleted.", self.bucket.name)
except ClientError:
logger.exception("Couldn't delete bucket %s.", self.bucket.name)
raise
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[DeleteBucket](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/DeleteBucket)」を参照してください。
### `DeleteBucketCors`
次のコード例は、`DeleteBucketCors` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/s3_basics#code-examples)での設定と実行の方法を確認してください。
```
class BucketWrapper:
"""Encapsulates S3 bucket actions."""
def __init__(self, bucket):
"""
:param bucket: A Boto3 Bucket resource. This is a high-level resource in Boto3
that wraps bucket actions in a class-like structure.
"""
self.bucket = bucket
self.name = bucket.name
def delete_cors(self):
"""
Delete the CORS rules from the bucket.
:param bucket_name: The name of the bucket to update.
"""
try:
self.bucket.Cors().delete()
logger.info("Deleted CORS from bucket '%s'.", self.bucket.name)
except ClientError:
logger.exception("Couldn't delete CORS from bucket '%s'.", self.bucket.name)
raise
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[DeleteBucketCors](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/DeleteBucketCors)」を参照してください。
### `DeleteBucketLifecycle`
次のコード例は、`DeleteBucketLifecycle` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/s3_basics#code-examples)での設定と実行の方法を確認してください。
```
class BucketWrapper:
"""Encapsulates S3 bucket actions."""
def __init__(self, bucket):
"""
:param bucket: A Boto3 Bucket resource. This is a high-level resource in Boto3
that wraps bucket actions in a class-like structure.
"""
self.bucket = bucket
self.name = bucket.name
def delete_lifecycle_configuration(self):
"""
Remove the lifecycle configuration from the specified bucket.
"""
try:
self.bucket.LifecycleConfiguration().delete()
logger.info(
"Deleted lifecycle configuration for bucket '%s'.", self.bucket.name
)
except ClientError:
logger.exception(
"Couldn't delete lifecycle configuration for bucket '%s'.",
self.bucket.name,
)
raise
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[DeleteBucketLifecycle](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/DeleteBucketLifecycle)」を参照してください。
### `DeleteBucketPolicy`
次のコード例は、`DeleteBucketPolicy` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/s3_basics#code-examples)での設定と実行の方法を確認してください。
```
class BucketWrapper:
"""Encapsulates S3 bucket actions."""
def __init__(self, bucket):
"""
:param bucket: A Boto3 Bucket resource. This is a high-level resource in Boto3
that wraps bucket actions in a class-like structure.
"""
self.bucket = bucket
self.name = bucket.name
def delete_policy(self):
"""
Delete the security policy from the bucket.
"""
try:
self.bucket.Policy().delete()
logger.info("Deleted policy for bucket '%s'.", self.bucket.name)
except ClientError:
logger.exception(
"Couldn't delete policy for bucket '%s'.", self.bucket.name
)
raise
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[DeleteBucketPolicy](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/DeleteBucketPolicy)」を参照してください。
### `DeleteObject`
次のコード例は、`DeleteObject` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/s3_basics#code-examples)での設定と実行の方法を確認してください。
オブジェクトを削除します。
```
class ObjectWrapper:
"""Encapsulates S3 object actions."""
def __init__(self, s3_object):
"""
:param s3_object: A Boto3 Object resource. This is a high-level resource in Boto3
that wraps object actions in a class-like structure.
"""
self.object = s3_object
self.key = self.object.key
def delete(self):
"""
Deletes the object.
"""
try:
self.object.delete()
self.object.wait_until_not_exists()
logger.info(
"Deleted object '%s' from bucket '%s'.",
self.object.key,
self.object.bucket_name,
)
except ClientError:
logger.exception(
"Couldn't delete object '%s' from bucket '%s'.",
self.object.key,
self.object.bucket_name,
)
raise
```
オブジェクトの新しいバージョンを削除して、オブジェクトを以前のバージョンにロールバックします。
```
def rollback_object(bucket, object_key, version_id):
"""
Rolls back an object to an earlier version by deleting all versions that
occurred after the specified rollback version.
Usage is shown in the usage_demo_single_object function at the end of this module.
:param bucket: The bucket that holds the object to roll back.
:param object_key: The object to roll back.
:param version_id: The version ID to roll back to.
"""
# Versions must be sorted by last_modified date because delete markers are
# at the end of the list even when they are interspersed in time.
versions = sorted(
bucket.object_versions.filter(Prefix=object_key),
key=attrgetter("last_modified"),
reverse=True,
)
logger.debug(
"Got versions:\n%s",
"\n".join(
[
f"\t{version.version_id}, last modified {version.last_modified}"
for version in versions
]
),
)
if version_id in [ver.version_id for ver in versions]:
print(f"Rolling back to version {version_id}")
for version in versions:
if version.version_id != version_id:
version.delete()
print(f"Deleted version {version.version_id}")
else:
break
print(f"Active version is now {bucket.Object(object_key).version_id}")
else:
raise KeyError(
f"{version_id} was not found in the list of versions for " f"{object_key}."
)
```
オブジェクトのアクティブな削除マーカーを削除して、削除されたオブジェクトを復活させます。
```
def revive_object(bucket, object_key):
"""
Revives a versioned object that was deleted by removing the object's active
delete marker.
A versioned object presents as deleted when its latest version is a delete marker.
By removing the delete marker, we make the previous version the latest version
and the object then presents as *not* deleted.
Usage is shown in the usage_demo_single_object function at the end of this module.
:param bucket: The bucket that contains the object.
:param object_key: The object to revive.
"""
# Get the latest version for the object.
response = s3.meta.client.list_object_versions(
Bucket=bucket.name, Prefix=object_key, MaxKeys=1
)
if "DeleteMarkers" in response:
latest_version = response["DeleteMarkers"][0]
if latest_version["IsLatest"]:
logger.info(
"Object %s was indeed deleted on %s. Let's revive it.",
object_key,
latest_version["LastModified"],
)
obj = bucket.Object(object_key)
obj.Version(latest_version["VersionId"]).delete()
logger.info(
"Revived %s, active version is now %s with body '%s'",
object_key,
obj.version_id,
obj.get()["Body"].read(),
)
else:
logger.warning(
"Delete marker is not the latest version for %s!", object_key
)
elif "Versions" in response:
logger.warning("Got an active version for %s, nothing to do.", object_key)
else:
logger.error("Couldn't get any version info for %s.", object_key)
```
S3 オブジェクトから削除マーカーを削除する Lambda ハンドラを作成します。このハンドラを使用して、バージョン管理されたバケット内の余分な削除マーカーを効率的にクリーンアップできます。
```
import logging
from urllib import parse
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
logger.setLevel("INFO")
s3 = boto3.client("s3")
def lambda_handler(event, context):
"""
Removes a delete marker from the specified versioned object.
:param event: The S3 batch event that contains the ID of the delete marker
to remove.
:param context: Context about the event.
:return: A result structure that Amazon S3 uses to interpret the result of the
operation. When the result code is TemporaryFailure, S3 retries the
operation.
"""
# Parse job parameters from Amazon S3 batch operations
invocation_id = event["invocationId"]
invocation_schema_version = event["invocationSchemaVersion"]
results = []
result_code = None
result_string = None
task = event["tasks"][0]
task_id = task["taskId"]
try:
obj_key = parse.unquote_plus(task["s3Key"], encoding="utf-8")
obj_version_id = task["s3VersionId"]
bucket_name = task["s3BucketArn"].split(":")[-1]
logger.info(
"Got task: remove delete marker %s from object %s.", obj_version_id, obj_key
)
try:
# If this call does not raise an error, the object version is not a delete
# marker and should not be deleted.
response = s3.head_object(
Bucket=bucket_name, Key=obj_key, VersionId=obj_version_id
)
result_code = "PermanentFailure"
result_string = (
f"Object {obj_key}, ID {obj_version_id} is not " f"a delete marker."
)
logger.debug(response)
logger.warning(result_string)
except ClientError as error:
delete_marker = error.response["ResponseMetadata"]["HTTPHeaders"].get(
"x-amz-delete-marker", "false"
)
if delete_marker == "true":
logger.info(
"Object %s, version %s is a delete marker.", obj_key, obj_version_id
)
try:
s3.delete_object(
Bucket=bucket_name, Key=obj_key, VersionId=obj_version_id
)
result_code = "Succeeded"
result_string = (
f"Successfully removed delete marker "
f"{obj_version_id} from object {obj_key}."
)
logger.info(result_string)
except ClientError as error:
# Mark request timeout as a temporary failure so it will be retried.
if error.response["Error"]["Code"] == "RequestTimeout":
result_code = "TemporaryFailure"
result_string = (
f"Attempt to remove delete marker from "
f"object {obj_key} timed out."
)
logger.info(result_string)
else:
raise
else:
raise ValueError(
f"The x-amz-delete-marker header is either not "
f"present or is not 'true'."
)
except Exception as error:
# Mark all other exceptions as permanent failures.
result_code = "PermanentFailure"
result_string = str(error)
logger.exception(error)
finally:
results.append(
{
"taskId": task_id,
"resultCode": result_code,
"resultString": result_string,
}
)
return {
"invocationSchemaVersion": invocation_schema_version,
"treatMissingKeysAs": "PermanentFailure",
"invocationId": invocation_id,
"results": results,
}
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[DeleteObject](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/DeleteObject)」を参照してください。
### `DeleteObjects`
次のコード例は、`DeleteObjects` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/s3_basics#code-examples)での設定と実行の方法を確認してください。
オブジェクト キーのリストからオブジェクトのセットを削除します。
```
class ObjectWrapper:
"""Encapsulates S3 object actions."""
def __init__(self, s3_object):
"""
:param s3_object: A Boto3 Object resource. This is a high-level resource in Boto3
that wraps object actions in a class-like structure.
"""
self.object = s3_object
self.key = self.object.key
@staticmethod
def delete_objects(bucket, object_keys):
"""
Removes a list of objects from a bucket.
This operation is done as a batch in a single request.
:param bucket: The bucket that contains the objects. This is a Boto3 Bucket
resource.
:param object_keys: The list of keys that identify the objects to remove.
:return: The response that contains data about which objects were deleted
and any that could not be deleted.
"""
try:
response = bucket.delete_objects(
Delete={"Objects": [{"Key": key} for key in object_keys]}
)
if "Deleted" in response:
logger.info(
"Deleted objects '%s' from bucket '%s'.",
[del_obj["Key"] for del_obj in response["Deleted"]],
bucket.name,
)
if "Errors" in response:
logger.warning(
"Could not delete objects '%s' from bucket '%s'.",
[
f"{del_obj['Key']}: {del_obj['Code']}"
for del_obj in response["Errors"]
],
bucket.name,
)
except ClientError:
logger.exception("Couldn't delete any objects from bucket %s.", bucket.name)
raise
else:
return response
```
バケット内のすべてのオブジェクトを削除します。
```
class ObjectWrapper:
"""Encapsulates S3 object actions."""
def __init__(self, s3_object):
"""
:param s3_object: A Boto3 Object resource. This is a high-level resource in Boto3
that wraps object actions in a class-like structure.
"""
self.object = s3_object
self.key = self.object.key
@staticmethod
def empty_bucket(bucket):
"""
Remove all objects from a bucket.
:param bucket: The bucket to empty. This is a Boto3 Bucket resource.
"""
try:
bucket.objects.delete()
logger.info("Emptied bucket '%s'.", bucket.name)
except ClientError:
logger.exception("Couldn't empty bucket '%s'.", bucket.name)
raise
```
すべてのバージョンを削除することによって、バージョン管理されているオブジェクトを完全に削除します。
```
def permanently_delete_object(bucket, object_key):
"""
Permanently deletes a versioned object by deleting all of its versions.
Usage is shown in the usage_demo_single_object function at the end of this module.
:param bucket: The bucket that contains the object.
:param object_key: The object to delete.
"""
try:
bucket.object_versions.filter(Prefix=object_key).delete()
logger.info("Permanently deleted all versions of object %s.", object_key)
except ClientError:
logger.exception("Couldn't delete all versions of %s.", object_key)
raise
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[DeleteObjects](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/DeleteObjects)」を参照してください。
### `GetBucketAcl`
次のコード例は、`GetBucketAcl` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/s3_basics#code-examples)での設定と実行の方法を確認してください。
```
class BucketWrapper:
"""Encapsulates S3 bucket actions."""
def __init__(self, bucket):
"""
:param bucket: A Boto3 Bucket resource. This is a high-level resource in Boto3
that wraps bucket actions in a class-like structure.
"""
self.bucket = bucket
self.name = bucket.name
def get_acl(self):
"""
Get the ACL of the bucket.
:return: The ACL of the bucket.
"""
try:
acl = self.bucket.Acl()
logger.info(
"Got ACL for bucket %s. Owner is %s.", self.bucket.name, acl.owner
)
except ClientError:
logger.exception("Couldn't get ACL for bucket %s.", self.bucket.name)
raise
else:
return acl
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[GetBucketAcl](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/GetBucketAcl)」を参照してください。
### `GetBucketCors`
次のコード例は、`GetBucketCors` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/s3_basics#code-examples)での設定と実行の方法を確認してください。
```
class BucketWrapper:
"""Encapsulates S3 bucket actions."""
def __init__(self, bucket):
"""
:param bucket: A Boto3 Bucket resource. This is a high-level resource in Boto3
that wraps bucket actions in a class-like structure.
"""
self.bucket = bucket
self.name = bucket.name
def get_cors(self):
"""
Get the CORS rules for the bucket.
:return The CORS rules for the specified bucket.
"""
try:
cors = self.bucket.Cors()
logger.info(
"Got CORS rules %s for bucket '%s'.", cors.cors_rules, self.bucket.name
)
except ClientError:
logger.exception(("Couldn't get CORS for bucket %s.", self.bucket.name))
raise
else:
return cors
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[GetBucketCors](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/GetBucketCors)」を参照してください。
### `GetBucketLifecycleConfiguration`
次のコード例は、`GetBucketLifecycleConfiguration` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/s3_basics#code-examples)での設定と実行の方法を確認してください。
```
class BucketWrapper:
"""Encapsulates S3 bucket actions."""
def __init__(self, bucket):
"""
:param bucket: A Boto3 Bucket resource. This is a high-level resource in Boto3
that wraps bucket actions in a class-like structure.
"""
self.bucket = bucket
self.name = bucket.name
def get_lifecycle_configuration(self):
"""
Get the lifecycle configuration of the bucket.
:return: The lifecycle rules of the specified bucket.
"""
try:
config = self.bucket.LifecycleConfiguration()
logger.info(
"Got lifecycle rules %s for bucket '%s'.",
config.rules,
self.bucket.name,
)
except:
logger.exception(
"Couldn't get lifecycle rules for bucket '%s'.", self.bucket.name
)
raise
else:
return config.rules
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[GetBucketLifecycleConfiguration](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/GetBucketLifecycleConfiguration)」を参照してください。
### `GetBucketPolicy`
次のコード例は、`GetBucketPolicy` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/s3_basics#code-examples)での設定と実行の方法を確認してください。
```
class BucketWrapper:
"""Encapsulates S3 bucket actions."""
def __init__(self, bucket):
"""
:param bucket: A Boto3 Bucket resource. This is a high-level resource in Boto3
that wraps bucket actions in a class-like structure.
"""
self.bucket = bucket
self.name = bucket.name
def get_policy(self):
"""
Get the security policy of the bucket.
:return: The security policy of the specified bucket, in JSON format.
"""
try:
policy = self.bucket.Policy()
logger.info(
"Got policy %s for bucket '%s'.", policy.policy, self.bucket.name
)
except ClientError:
logger.exception("Couldn't get policy for bucket '%s'.", self.bucket.name)
raise
else:
return json.loads(policy.policy)
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[GetBucketPolicy](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/GetBucketPolicy)」を参照してください。
### `GetObject`
次のコード例は、`GetObject` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/s3_basics#code-examples)での設定と実行の方法を確認してください。
```
class ObjectWrapper:
"""Encapsulates S3 object actions."""
def __init__(self, s3_object):
"""
:param s3_object: A Boto3 Object resource. This is a high-level resource in Boto3
that wraps object actions in a class-like structure.
"""
self.object = s3_object
self.key = self.object.key
def get(self):
"""
Gets the object.
:return: The object data in bytes.
"""
try:
body = self.object.get()["Body"].read()
logger.info(
"Got object '%s' from bucket '%s'.",
self.object.key,
self.object.bucket_name,
)
except ClientError:
logger.exception(
"Couldn't get object '%s' from bucket '%s'.",
self.object.key,
self.object.bucket_name,
)
raise
else:
return body
```
条件付きリクエストを使用してオブジェクトを取得します。
```
class S3ConditionalRequests:
"""Encapsulates S3 conditional request operations."""
def __init__(self, s3_client):
self.s3 = s3_client
@classmethod
def from_client(cls):
"""
Instantiates this class from a Boto3 client.
"""
s3_client = boto3.client("s3")
return cls(s3_client)
def get_object_conditional(
self,
object_key: str,
source_bucket: str,
condition_type: str,
condition_value: str,
):
"""
Retrieves an object from Amazon S3 with a conditional request.
:param object_key: The key of the object to retrieve.
:param source_bucket: The source bucket of the object.
:param condition_type: The type of condition: 'IfMatch', 'IfNoneMatch', 'IfModifiedSince', 'IfUnmodifiedSince'.
:param condition_value: The value to use for the condition.
"""
try:
response = self.s3.get_object(
Bucket=source_bucket,
Key=object_key,
**{condition_type: condition_value},
)
sample_bytes = response["Body"].read(20)
print(
f"\tConditional read successful. Here are the first 20 bytes of the object:\n"
)
print(f"\t{sample_bytes}")
except ClientError as e:
error_code = e.response["Error"]["Code"]
if error_code == "PreconditionFailed":
print("\tConditional read failed: Precondition failed")
elif error_code == "304": # Not modified error code.
print("\tConditional read failed: Object not modified")
else:
logger.error(f"Unexpected error: {error_code}")
raise
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[GetObject](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/GetObject)」を参照してください。
### `GetObjectAcl`
次のコード例は、`GetObjectAcl` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/s3_basics#code-examples)での設定と実行の方法を確認してください。
```
class ObjectWrapper:
"""Encapsulates S3 object actions."""
def __init__(self, s3_object):
"""
:param s3_object: A Boto3 Object resource. This is a high-level resource in Boto3
that wraps object actions in a class-like structure.
"""
self.object = s3_object
self.key = self.object.key
def get_acl(self):
"""
Gets the ACL of the object.
:return: The ACL of the object.
"""
try:
acl = self.object.Acl()
logger.info(
"Got ACL for object %s owned by %s.",
self.object.key,
acl.owner["DisplayName"],
)
except ClientError:
logger.exception("Couldn't get ACL for object %s.", self.object.key)
raise
else:
return acl
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[GetObjectAcl](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/GetObjectAcl)」を参照してください。
### `GetObjectLegalHold`
次のコード例は、`GetObjectLegalHold` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/scenarios/object-locking#code-examples)での設定と実行の方法を確認してください。
オブジェクトにリーガルホールドを適用します。
```
def get_legal_hold(s3_client, bucket: str, key: str) -> None:
"""
Get the legal hold status of a specific file in a bucket.
Args:
s3_client: Boto3 S3 client.
bucket: The name of the bucket containing the file.
key: The key of the file to get the legal hold status of.
"""
print()
logger.info("Getting legal hold status of file [%s] in bucket [%s]", key, bucket)
try:
response = s3_client.get_object_legal_hold(Bucket=bucket, Key=key)
legal_hold_status = response["LegalHold"]["Status"]
logger.debug(
"Legal hold status of file [%s] in bucket [%s] is [%s]",
key,
bucket,
legal_hold_status,
)
except Exception as e:
logger.error(
"Failed to get legal hold status of file [%s] in bucket [%s]: %s",
key,
bucket,
e,
)
```
+ API の詳細については、「AWS SDK for Python (Boto3) API リファレンス」の「[GetObjectLegalHold](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/GetObjectLegalHold)」を参照してください。**
### `GetObjectLockConfiguration`
次のコード例は、`GetObjectLockConfiguration` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/scenarios/object-locking#code-examples)での設定と実行の方法を確認してください。
オブジェクトロック設定を取得します。
```
def is_object_lock_enabled(s3_client, bucket: str) -> bool:
"""
Check if object lock is enabled for a bucket.
Args:
s3_client: Boto3 S3 client.
bucket: The name of the bucket to check.
Returns:
True if object lock is enabled, False otherwise.
"""
try:
response = s3_client.get_object_lock_configuration(Bucket=bucket)
return (
"ObjectLockConfiguration" in response
and response["ObjectLockConfiguration"]["ObjectLockEnabled"] == "Enabled"
)
except s3_client.exceptions.ClientError as e:
if e.response["Error"]["Code"] == "ObjectLockConfigurationNotFoundError":
return False
else:
raise
```
+ API の詳細については、「AWS SDK for Python (Boto3) API リファレンス」の「[GetObjectLockConfiguration](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/GetObjectLockConfiguration)」を参照してください。**
### `HeadBucket`
次のコード例は、`HeadBucket` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/s3_basics#code-examples)での設定と実行の方法を確認してください。
```
class BucketWrapper:
"""Encapsulates S3 bucket actions."""
def __init__(self, bucket):
"""
:param bucket: A Boto3 Bucket resource. This is a high-level resource in Boto3
that wraps bucket actions in a class-like structure.
"""
self.bucket = bucket
self.name = bucket.name
def exists(self):
"""
Determine whether the bucket exists and you have access to it.
:return: True when the bucket exists; otherwise, False.
"""
try:
self.bucket.meta.client.head_bucket(Bucket=self.bucket.name)
logger.info("Bucket %s exists.", self.bucket.name)
exists = True
except ClientError:
logger.warning(
"Bucket %s doesn't exist or you don't have access to it.",
self.bucket.name,
)
exists = False
return exists
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[HeadBucket](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/HeadBucket)」を参照してください。
### `ListBuckets`
次のコード例は、`ListBuckets` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/s3_basics#code-examples)での設定と実行の方法を確認してください。
```
class BucketWrapper:
"""Encapsulates S3 bucket actions."""
def __init__(self, bucket):
"""
:param bucket: A Boto3 Bucket resource. This is a high-level resource in Boto3
that wraps bucket actions in a class-like structure.
"""
self.bucket = bucket
self.name = bucket.name
@staticmethod
def list(s3_resource):
"""
Get the buckets in all Regions for the current account.
:param s3_resource: A Boto3 S3 resource. This is a high-level resource in Boto3
that contains collections and factory methods to create
other high-level S3 sub-resources.
:return: The list of buckets.
"""
try:
buckets = list(s3_resource.buckets.all())
logger.info("Got buckets: %s.", buckets)
except ClientError:
logger.exception("Couldn't get buckets.")
raise
else:
return buckets
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[ListBuckets](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/ListBuckets)」を参照してください。
### `ListObjectsV2`
次のコード例は、`ListObjectsV2` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/s3_basics#code-examples)での設定と実行の方法を確認してください。
```
class ObjectWrapper:
"""Encapsulates S3 object actions."""
def __init__(self, s3_object):
"""
:param s3_object: A Boto3 Object resource. This is a high-level resource in Boto3
that wraps object actions in a class-like structure.
"""
self.object = s3_object
self.key = self.object.key
@staticmethod
def list(bucket, prefix=None):
"""
Lists the objects in a bucket, optionally filtered by a prefix.
:param bucket: The bucket to query. This is a Boto3 Bucket resource.
:param prefix: When specified, only objects that start with this prefix are listed.
:return: The list of objects.
"""
try:
if not prefix:
objects = list(bucket.objects.all())
else:
objects = list(bucket.objects.filter(Prefix=prefix))
logger.info(
"Got objects %s from bucket '%s'", [o.key for o in objects], bucket.name
)
except ClientError:
logger.exception("Couldn't get objects for bucket '%s'.", bucket.name)
raise
else:
return objects
```
+ API の詳細については、「AWS SDK for Python (Boto3) API リファレンス」の「[ListObjectsV2](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/ListObjectsV2)」を参照してください。**
### `PutBucketAcl`
次のコード例は、`PutBucketAcl` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/s3_basics#code-examples)での設定と実行の方法を確認してください。
```
class BucketWrapper:
"""Encapsulates S3 bucket actions."""
def __init__(self, bucket):
"""
:param bucket: A Boto3 Bucket resource. This is a high-level resource in Boto3
that wraps bucket actions in a class-like structure.
"""
self.bucket = bucket
self.name = bucket.name
def grant_log_delivery_access(self):
"""
Grant the AWS Log Delivery group write access to the bucket so that
Amazon S3 can deliver access logs to the bucket. This is the only recommended
use of an S3 bucket ACL.
"""
try:
acl = self.bucket.Acl()
# Putting an ACL overwrites the existing ACL. If you want to preserve
# existing grants, append new grants to the list of existing grants.
grants = acl.grants if acl.grants else []
grants.append(
{
"Grantee": {
"Type": "Group",
"URI": "http://acs.amazonaws.com/groups/s3/LogDelivery",
},
"Permission": "WRITE",
}
)
acl.put(AccessControlPolicy={"Grants": grants, "Owner": acl.owner})
logger.info("Granted log delivery access to bucket '%s'", self.bucket.name)
except ClientError:
logger.exception("Couldn't add ACL to bucket '%s'.", self.bucket.name)
raise
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[PutBucketAcl](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/PutBucketAcl)」を参照してください。
### `PutBucketCors`
次のコード例は、`PutBucketCors` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/s3_basics#code-examples)での設定と実行の方法を確認してください。
```
class BucketWrapper:
"""Encapsulates S3 bucket actions."""
def __init__(self, bucket):
"""
:param bucket: A Boto3 Bucket resource. This is a high-level resource in Boto3
that wraps bucket actions in a class-like structure.
"""
self.bucket = bucket
self.name = bucket.name
def put_cors(self, cors_rules):
"""
Apply CORS rules to the bucket. CORS rules specify the HTTP actions that are
allowed from other domains.
:param cors_rules: The CORS rules to apply.
"""
try:
self.bucket.Cors().put(CORSConfiguration={"CORSRules": cors_rules})
logger.info(
"Put CORS rules %s for bucket '%s'.", cors_rules, self.bucket.name
)
except ClientError:
logger.exception("Couldn't put CORS rules for bucket %s.", self.bucket.name)
raise
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[PutBucketCors](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/PutBucketCors)」を参照してください。
### `PutBucketLifecycleConfiguration`
次のコード例は、`PutBucketLifecycleConfiguration` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/s3_basics#code-examples)での設定と実行の方法を確認してください。
```
class BucketWrapper:
"""Encapsulates S3 bucket actions."""
def __init__(self, bucket):
"""
:param bucket: A Boto3 Bucket resource. This is a high-level resource in Boto3
that wraps bucket actions in a class-like structure.
"""
self.bucket = bucket
self.name = bucket.name
def put_lifecycle_configuration(self, lifecycle_rules):
"""
Apply a lifecycle configuration to the bucket. The lifecycle configuration can
be used to archive or delete the objects in the bucket according to specified
parameters, such as a number of days.
:param lifecycle_rules: The lifecycle rules to apply.
"""
try:
self.bucket.LifecycleConfiguration().put(
LifecycleConfiguration={"Rules": lifecycle_rules}
)
logger.info(
"Put lifecycle rules %s for bucket '%s'.",
lifecycle_rules,
self.bucket.name,
)
except ClientError:
logger.exception(
"Couldn't put lifecycle rules for bucket '%s'.", self.bucket.name
)
raise
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[PutBucketLifecycleConfiguration](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/PutBucketLifecycleConfiguration)」を参照してください。
### `PutBucketPolicy`
次のコード例は、`PutBucketPolicy` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/s3_basics#code-examples)での設定と実行の方法を確認してください。
```
class BucketWrapper:
"""Encapsulates S3 bucket actions."""
def __init__(self, bucket):
"""
:param bucket: A Boto3 Bucket resource. This is a high-level resource in Boto3
that wraps bucket actions in a class-like structure.
"""
self.bucket = bucket
self.name = bucket.name
def put_policy(self, policy):
"""
Apply a security policy to the bucket. Policies control users' ability
to perform specific actions, such as listing the objects in the bucket.
:param policy: The policy to apply to the bucket.
"""
try:
self.bucket.Policy().put(Policy=json.dumps(policy))
logger.info("Put policy %s for bucket '%s'.", policy, self.bucket.name)
except ClientError:
logger.exception("Couldn't apply policy to bucket '%s'.", self.bucket.name)
raise
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[PutBucketPolicy](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/PutBucketPolicy)」を参照してください。
### `PutObject`
次のコード例は、`PutObject` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/s3_basics#code-examples)での設定と実行の方法を確認してください。
```
class ObjectWrapper:
"""Encapsulates S3 object actions."""
def __init__(self, s3_object):
"""
:param s3_object: A Boto3 Object resource. This is a high-level resource in Boto3
that wraps object actions in a class-like structure.
"""
self.object = s3_object
self.key = self.object.key
def put(self, data):
"""
Upload data to the object.
:param data: The data to upload. This can either be bytes or a string. When this
argument is a string, it is interpreted as a file name, which is
opened in read bytes mode.
"""
put_data = data
if isinstance(data, str):
try:
put_data = open(data, "rb")
except IOError:
logger.exception("Expected file name or binary data, got '%s'.", data)
raise
try:
self.object.put(Body=put_data)
self.object.wait_until_exists()
logger.info(
"Put object '%s' to bucket '%s'.",
self.object.key,
self.object.bucket_name,
)
except ClientError:
logger.exception(
"Couldn't put object '%s' to bucket '%s'.",
self.object.key,
self.object.bucket_name,
)
raise
finally:
if getattr(put_data, "close", None):
put_data.close()
```
条件付きリクエストを使用してオブジェクトをアップロードします。
```
class S3ConditionalRequests:
"""Encapsulates S3 conditional request operations."""
def __init__(self, s3_client):
self.s3 = s3_client
@classmethod
def from_client(cls):
"""
Instantiates this class from a Boto3 client.
"""
s3_client = boto3.client("s3")
return cls(s3_client)
def put_object_conditional(self, object_key: str, source_bucket: str, data: bytes):
"""
Uploads an object to Amazon S3 with a conditional request. Prevents overwrite
using an IfNoneMatch condition for the object key.
:param object_key: The key of the object to upload.
:param source_bucket: The source bucket of the object.
:param data: The data to upload.
"""
try:
self.s3.put_object(
Bucket=source_bucket, Key=object_key, Body=data, IfNoneMatch="*"
)
print(
f"\tConditional write successful for key {object_key} in bucket {source_bucket}."
)
except ClientError as e:
error_code = e.response["Error"]["Code"]
if error_code == "PreconditionFailed":
print("\tConditional write failed: Precondition failed")
else:
logger.error(f"Unexpected error: {error_code}")
raise
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[PutObject](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/PutObject)」を参照してください。
### `PutObjectAcl`
次のコード例は、`PutObjectAcl` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/s3_basics#code-examples)での設定と実行の方法を確認してください。
```
class ObjectWrapper:
"""Encapsulates S3 object actions."""
def __init__(self, s3_object):
"""
:param s3_object: A Boto3 Object resource. This is a high-level resource in Boto3
that wraps object actions in a class-like structure.
"""
self.object = s3_object
self.key = self.object.key
def put_acl(self, email):
"""
Applies an ACL to the object that grants read access to an AWS user identified
by email address.
:param email: The email address of the user to grant access.
"""
try:
acl = self.object.Acl()
# Putting an ACL overwrites the existing ACL, so append new grants
# if you want to preserve existing grants.
grants = acl.grants if acl.grants else []
grants.append(
{
"Grantee": {"Type": "AmazonCustomerByEmail", "EmailAddress": email},
"Permission": "READ",
}
)
acl.put(AccessControlPolicy={"Grants": grants, "Owner": acl.owner})
logger.info("Granted read access to %s.", email)
except ClientError:
logger.exception("Couldn't add ACL to object '%s'.", self.object.key)
raise
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[PutObjectAcl](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/PutObjectAcl)」を参照してください。
### `PutObjectLegalHold`
次のコード例は、`PutObjectLegalHold` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/scenarios/object-locking#code-examples)での設定と実行の方法を確認してください。
オブジェクトにリーガルホールドを適用します。
```
def set_legal_hold(s3_client, bucket: str, key: str) -> None:
"""
Set a legal hold on a specific file in a bucket.
Args:
s3_client: Boto3 S3 client.
bucket: The name of the bucket containing the file.
key: The key of the file to set the legal hold on.
"""
print()
logger.info("Setting legal hold on file [%s] in bucket [%s]", key, bucket)
try:
before_status = "OFF"
after_status = "ON"
s3_client.put_object_legal_hold(
Bucket=bucket, Key=key, LegalHold={"Status": after_status}
)
logger.debug(
"Legal hold set successfully on file [%s] in bucket [%s]", key, bucket
)
_print_legal_hold_update(bucket, key, before_status, after_status)
except Exception as e:
logger.error(
"Failed to set legal hold on file [%s] in bucket [%s]: %s", key, bucket, e
)
```
+ API の詳細については、「AWS SDK for Python (Boto3) API リファレンス」の「[PutObjectLegalHold](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/PutObjectLegalHold)」を参照してください。**
### `PutObjectLockConfiguration`
次のコード例は、`PutObjectLockConfiguration` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/scenarios/object-locking#code-examples)での設定と実行の方法を確認してください。
オブジェクトロック設定を適用します。
```
s3_client.put_object_lock_configuration(
Bucket=bucket,
ObjectLockConfiguration={"ObjectLockEnabled": "Disabled", "Rule": {}},
)
```
+ API の詳細については、「AWS SDK for Python (Boto3) API リファレンス」の「[PutObjectLockConfiguration](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/PutObjectLockConfiguration)」を参照してください。**
### `PutObjectRetention`
次のコード例は、`PutObjectRetention` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/scenarios/object-locking#code-examples)での設定と実行の方法を確認してください。
オブジェクト保持を適用します。
```
s3_client.put_object_retention(
Bucket=bucket,
Key=key,
VersionId=version_id,
Retention={"Mode": "GOVERNANCE", "RetainUntilDate": far_future_date},
BypassGovernanceRetention=True,
)
```
+ API の詳細については、「AWS SDK for Python (Boto3) API リファレンス」の「[PutObjectRetention](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/PutObjectRetention)」を参照してください。**
## シナリオ
### 署名付き URL を作成する
次のコード例は、Amazon S3 の署名付き URL を作成し、オブジェクトをアップロードする方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/s3_basics#code-examples)での設定と実行の方法を確認してください。
S3 アクションを期間限定で実行できる署名付き URL を生成します。Requests パッケージを使用して、URL でリクエストを行います。
```
import argparse
import logging
import boto3
from botocore.exceptions import ClientError
import requests
logger = logging.getLogger(__name__)
def generate_presigned_url(s3_client, client_method, method_parameters, expires_in):
"""
Generate a presigned Amazon S3 URL that can be used to perform an action.
:param s3_client: A Boto3 Amazon S3 client.
:param client_method: The name of the client method that the URL performs.
:param method_parameters: The parameters of the specified client method.
:param expires_in: The number of seconds the presigned URL is valid for.
:return: The presigned URL.
"""
try:
url = s3_client.generate_presigned_url(
ClientMethod=client_method, Params=method_parameters, ExpiresIn=expires_in
)
logger.info("Got presigned URL: %s", url)
except ClientError:
logger.exception(
"Couldn't get a presigned URL for client method '%s'.", client_method
)
raise
return url
def usage_demo():
logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
print("-" * 88)
print("Welcome to the Amazon S3 presigned URL demo.")
print("-" * 88)
parser = argparse.ArgumentParser()
parser.add_argument("bucket", help="The name of the bucket.")
parser.add_argument(
"key",
help="For a GET operation, the key of the object in Amazon S3. For a "
"PUT operation, the name of a file to upload.",
)
parser.add_argument("action", choices=("get", "put"), help="The action to perform.")
args = parser.parse_args()
s3_client = boto3.client("s3")
client_action = "get_object" if args.action == "get" else "put_object"
url = generate_presigned_url(
s3_client, client_action, {"Bucket": args.bucket, "Key": args.key}, 1000
)
print("Using the Requests package to send a request to the URL.")
response = None
if args.action == "get":
response = requests.get(url)
if response.status_code == 200:
with open(args.key.split("/")[-1], 'wb') as object_file:
object_file.write(response.content)
elif args.action == "put":
print("Putting data to the URL.")
try:
with open(args.key, "rb") as object_file:
object_text = object_file.read()
response = requests.put(url, data=object_text)
except FileNotFoundError:
print(
f"Couldn't find {args.key}. For a PUT operation, the key must be the "
f"name of a file that exists on your computer."
)
if response is not None:
print(f"Status: {response.status_code}\nReason: {response.reason}")
print("-" * 88)
if __name__ == "__main__":
usage_demo()
```
署名付き POST リクエストを生成して、ファイルをアップロードします。
```
class BucketWrapper:
"""Encapsulates S3 bucket actions."""
def __init__(self, bucket):
"""
:param bucket: A Boto3 Bucket resource. This is a high-level resource in Boto3
that wraps bucket actions in a class-like structure.
"""
self.bucket = bucket
self.name = bucket.name
def generate_presigned_post(self, object_key, expires_in):
"""
Generate a presigned Amazon S3 POST request to upload a file.
A presigned POST can be used for a limited time to let someone without an AWS
account upload a file to a bucket.
:param object_key: The object key to identify the uploaded object.
:param expires_in: The number of seconds the presigned POST is valid.
:return: A dictionary that contains the URL and form fields that contain
required access data.
"""
try:
response = self.bucket.meta.client.generate_presigned_post(
Bucket=self.bucket.name, Key=object_key, ExpiresIn=expires_in
)
logger.info("Got presigned POST URL: %s", response["url"])
except ClientError:
logger.exception(
"Couldn't get a presigned POST URL for bucket '%s' and object '%s'",
self.bucket.name,
object_key,
)
raise
return response
```
### Amazon Textract エクスプローラーアプリケーションを作成する
次のコード例は、インタラクティブアプリケーションで Amazon Textract の出力を調べる方法を示しています。
**SDK for Python (Boto3)**
Amazon Textract AWS SDK for Python (Boto3) で を使用して、ドキュメントイメージ内のテキスト、フォーム、テーブル要素を検出する方法を示します。入力イメージと Amazon Textract 出力は、検出された要素を探索できる Tkinter アプリケーションに表示されます。
+ Amazon Textract にドキュメントイメージを送信し、検出された要素の出力を調べます。
+ Amazon Textract に直接イメージを送信するか、Amazon Simple Storage Service (Amazon S3) バケットを通じてイメージを送信します。
+ 非同期 API を使用して、ジョブの完了時に Amazon Simple Notification Service (Amazon SNS) トピックに通知を発行するジョブを開始します。
+ Amazon Simple Queue Service (Amazon SQS) キューにジョブ完了メッセージについてポーリングし、結果を表示します。
完全なソースコードとセットアップおよび実行の手順については、[GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/textract_explorer) で完全な例を参照してください。
**この例で使用されているサービス**
+ Amazon Cognito ID
+ Amazon S3
+ Amazon SNS
+ Amazon SQS
+ Amazon Textract
### 画像から抽出されたテキスト内のエンティティを検出する
次のコード例は、Amazon Comprehend を使用して、Amazon S3 に格納されている画像から Amazon Textract によって抽出されたテキスト内のエンティティを検出する方法を示しています。
**SDK for Python (Boto3)**
Jupyter ノートブック AWS SDK for Python (Boto3) で を使用して、イメージから抽出されたテキスト内のエンティティを検出する方法を示します。この例では、Amazon Textract を使用して Amazon Simple Storage Service (Amazon S3) に保存されている画像からテキストを抽出し、Amazon Comprehend を使用して、抽出されたテキスト内のエンティティを検出します。
この例は Jupyter Notebook であり、ノートブックをホストできる環境で実行する必要があります。Amazon SageMaker AI を使用してサンプルを実行する方法については、「[TextractAndComprehendNotebook.ipynb](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/textract_comprehend_notebook/TextractAndComprehendNotebook.ipynb)」の手順を参照してください。
完全なソースコードとセットアップおよび実行の手順については、[GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/textract_comprehend_notebook#readme) で完全な例を参照してください。
**この例で使用されているサービス**
+ Amazon Comprehend
+ Amazon S3
+ Amazon Textract
### 画像内のオブジェクトを検出する
次のコード例は、Amazon Rekognition を使用して画像内でカテゴリ別にオブジェクトを検出するアプリケーションを構築する方法を示しています。
**SDK for Python (Boto3)**
を使用して AWS SDK for Python (Boto3) 、以下を可能にするウェブアプリケーションを作成する方法を示します。
+ Amazon Simple Storage Service (Amazon S3) バケットに、写真をアップロードします。
+ Amazon Rekognition を使用して、写真を分析およびラベル付けします。
+ Amazon Simple Email Service (Amazon SES) を使用して、イメージ分析の E メールレポートを送信します。
この例には、React で構築された JavaScript で記述されたウェブページと、Flask-RESTful で構築された Python で記述された REST サービスの 2 つの主要なコンポーネントが含まれています。
React ウェブページを使用すると、次のことができます。
+ S3 バケットに保存されているイメージのリストを表示します。
+ イメージを S3 バケットにアップロードします。
+ イメージ内で検出された項目を識別するイメージとラベルを表示します。
+ S3 バケット内のすべてのイメージのレポートを取得し、レポートの E メールを送信します。
ウェブページが REST サービスを呼び出します。サービスはリクエストを AWS に送信して、以下のアクションを実行します。
+ S3 バケット内のイメージのリストを取得し、フィルタリングします。
+ Amazon S3 バケットに写真をアップロードします。
+ Amazon Rekognition を使用して個々の写真を分析し、写真で検出された項目を識別するラベルのリストを取得します。
+ S3 バケット内のすべての写真を分析し、Amazon SES を使用してレポートを E メールで送信します。
完全なソースコードとセットアップおよび実行の手順については、[GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/photo_analyzer) で完全な例を参照してください。
**この例で使用されているサービス**
+ Amazon Rekognition
+ Amazon S3
+ Amazon SES
### 動画内の人物や物体を検出する
次のコード例は、Amazon Rekognition で動画内の人やオブジェクトを検出する方法を示します。
**SDK for Python (Boto3)**
Amazon Rekognition を使用して、非同期検出ジョブを開始して、動画内の顔、オブジェクト、人を検出します。この例では、ジョブが完了し、Amazon Simple Queue Service (Amazon SQS) キューをトピックにサブスクライブしたときに、Amazon Simple Notification Service (Amazon SNS) トピックに通知するように Amazon Rekognition を設定します。キューがジョブに関するメッセージを受信すると、ジョブが取得され、結果が出力されます。
この例は GitHub で最もよく見られます。完全なソースコードとセットアップおよび実行の手順については、[GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rekognition) で完全な例を参照してください。
**この例で使用されているサービス**
+ Amazon Rekognition
+ Amazon S3
+ Amazon SES
+ Amazon SNS
+ Amazon SQS
### 条件付きリクエストの実行
次のコード例は、Amazon S3 リクエストに前提条件を追加する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/scenarios/conditional_requests#code-examples)での設定と実行の方法を確認してください。
Amazon S3 の条件付きリクエストを示すインタラクティブなシナリオを実行します。
```
"""
Purpose
Shows how to use AWS SDK for Python (Boto3) to get started using conditional requests for
Amazon Simple Storage Service (Amazon S3).
"""
import logging
import random
import sys
import datetime
import boto3
from botocore.exceptions import ClientError
from s3_conditional_requests import S3ConditionalRequests
# Add relative path to include demo_tools in this code example without need for setup.
sys.path.append("../../../..")
import demo_tools.question as q # noqa
# Constants
FILE_CONTENT = "This is a test file for S3 conditional requests."
RANDOM_SUFFIX = str(random.randint(100, 999))
logger = logging.getLogger(__name__)
class ConditionalRequestsScenario:
"""Runs a scenario that shows how to use S3 Conditional Requests."""
def __init__(self, conditional_requests, s3_client):
"""
:param conditional_requests: An object that wraps S3 conditional request actions.
:param s3_client: A Boto3 S3 client for setup and cleanup operations.
"""
self.conditional_requests = conditional_requests
self.s3_client = s3_client
def setup_scenario(self, source_bucket: str, dest_bucket: str, object_key: str):
"""
Sets up the scenario by creating a source and destination bucket.
Prompts the user to provide a bucket name prefix.
:param source_bucket: The name of the source bucket.
:param dest_bucket: The name of the destination bucket.
:param object_key: The name of a test file to add to the source bucket.
"""
# Create the buckets.
try:
self.s3_client.create_bucket(Bucket=source_bucket)
self.s3_client.create_bucket(Bucket=dest_bucket)
print(
f"Created source bucket: {source_bucket} and destination bucket: {dest_bucket}"
)
except ClientError as e:
error_code = e.response["Error"]["Code"]
logger.error(f"Error creating buckets: {error_code}")
raise
# Upload test file into the source bucket.
try:
print(f"Uploading file {object_key} to bucket {source_bucket}")
response = self.s3_client.put_object(
Bucket=source_bucket, Key=object_key, Body=FILE_CONTENT
)
object_etag = response["ETag"]
return object_etag
except Exception as e:
logger.error(
f"Failed to upload file {object_key} to bucket {source_bucket}: {e}"
)
def cleanup_scenario(self, source_bucket: str, dest_bucket: str):
"""
Cleans up the scenario by deleting the source and destination buckets.
:param source_bucket: The name of the source bucket.
:param dest_bucket: The name of the destination bucket.
"""
self.cleanup_bucket(source_bucket)
self.cleanup_bucket(dest_bucket)
def cleanup_bucket(self, bucket_name: str):
"""
Cleans up the bucket by deleting all objects and then the bucket itself.
:param bucket_name: The name of the bucket.
"""
try:
# Get list of all objects in the bucket.
list_response = self.s3_client.list_objects_v2(Bucket=bucket_name)
objs = list_response.get("Contents", [])
for obj in objs:
key = obj["Key"]
self.s3_client.delete_object(Bucket=bucket_name, Key=key)
self.s3_client.delete_bucket(Bucket=bucket_name)
print(f"Cleaned up bucket: {bucket_name}.")
except ClientError as e:
error_code = e.response["Error"]["Code"]
if error_code == "NoSuchBucket":
logger.info(f"Bucket {bucket_name} does not exist, skipping cleanup.")
else:
logger.error(f"Error deleting bucket: {error_code}")
raise
def display_buckets(self, source_bucket: str, dest_bucket: str):
"""
Display a list of the objects in the test buckets.
:param source_bucket: The name of the source bucket.
:param dest_bucket: The name of the destination bucket.
"""
self.list_bucket_contents(source_bucket)
self.list_bucket_contents(dest_bucket)
def list_bucket_contents(self, bucket_name):
"""
Display a list of the objects in the bucket.
:param bucket_name: The name of the bucket.
"""
try:
# Get list of all objects in the bucket.
print(f"\t Items in bucket {bucket_name}")
list_response = self.s3_client.list_objects_v2(Bucket=bucket_name)
objs = list_response.get("Contents", [])
if not objs:
print("\t\tNo objects found.")
for obj in objs:
key = obj["Key"]
print(f"\t\t object: {key} ETag {obj['ETag']}")
return objs
except ClientError as e:
error_code = e.response["Error"]["Code"]
if error_code == "NoSuchBucket":
logger.info(f"Bucket {bucket_name} does not exist.")
else:
logger.error(f"Error listing bucket and objects: {error_code}")
raise
def display_menu(
self, source_bucket: str, dest_bucket: str, object_key: str, etag: str
):
"""
Displays the menu of conditional request options for the user.
:param source_bucket: The name of the source bucket.
:param dest_bucket: The name of the destination bucket.
:param object_key: The key of the test object in the source bucket.
:param etag: The etag of the test object in the source bucket.
"""
actions = [
"Print list of bucket items.",
"Perform a conditional read.",
"Perform a conditional copy.",
"Perform a conditional write.",
"Clean up and exit.",
]
conditions = [
"If-Match: using the object's ETag. This condition should succeed.",
"If-None-Match: using the object's ETag. This condition should fail.",
"If-Modified-Since: using yesterday's date. This condition should succeed.",
"If-Unmodified-Since: using yesterday's date. This condition should fail.",
]
condition_types = [
"IfMatch",
"IfNoneMatch",
"IfModifiedSince",
"IfUnmodifiedSince",
]
copy_condition_types = [
"CopySourceIfMatch",
"CopySourceIfNoneMatch",
"CopySourceIfModifiedSince",
"CopySourceIfUnmodifiedSince",
]
yesterday_date = datetime.datetime.utcnow() - datetime.timedelta(days=1)
choice = 0
while choice != 4:
print("-" * 88)
print("Choose an action to explore some example conditional requests.")
choice = q.choose("Which action would you like to take? ", actions)
if choice == 0:
print("Listing the objects and buckets.")
self.display_buckets(source_bucket, dest_bucket)
elif choice == 1:
print("Perform a conditional read.")
condition_type = q.choose("Enter the condition type : ", conditions)
if condition_type == 0 or condition_type == 1:
self.conditional_requests.get_object_conditional(
object_key, source_bucket, condition_types[condition_type], etag
)
elif condition_type == 2 or condition_type == 3:
self.conditional_requests.get_object_conditional(
object_key,
source_bucket,
condition_types[condition_type],
yesterday_date,
)
elif choice == 2:
print("Perform a conditional copy.")
condition_type = q.choose("Enter the condition type : ", conditions)
dest_key = q.ask("Enter an object key: ", q.non_empty)
if condition_type == 0 or condition_type == 1:
self.conditional_requests.copy_object_conditional(
object_key,
dest_key,
source_bucket,
dest_bucket,
copy_condition_types[condition_type],
etag,
)
elif condition_type == 2 or condition_type == 3:
self.conditional_requests.copy_object_conditional(
object_key,
dest_key,
copy_condition_types[condition_type],
yesterday_date,
)
elif choice == 3:
print(
"Perform a conditional write using IfNoneMatch condition on the object key."
)
print("If the key is a duplicate, the write will fail.")
object_key = q.ask("Enter an object key: ", q.non_empty)
self.conditional_requests.put_object_conditional(
object_key, source_bucket, b"Conditional write example data."
)
elif choice == 4:
print("Proceeding to cleanup.")
def run_scenario(self):
"""
Runs the interactive scenario.
"""
print("-" * 88)
print("Welcome to the Amazon S3 conditional requests example.")
print("-" * 88)
print(
f"""\
This example demonstrates the use of conditional requests for S3 operations.
You can use conditional requests to add preconditions to S3 read requests to return or copy
an object based on its Entity tag (ETag), or last modified date.
You can use a conditional write requests to prevent overwrites by ensuring
there is no existing object with the same key.
This example will allow you to perform conditional reads
and writes that will succeed or fail based on your selected options.
Sample buckets and a sample object will be created as part of the example.
"""
)
bucket_prefix = q.ask("Enter a bucket name prefix: ", q.non_empty)
source_bucket_name = f"{bucket_prefix}-source-{RANDOM_SUFFIX}"
dest_bucket_name = f"{bucket_prefix}-dest-{RANDOM_SUFFIX}"
object_key = "test-upload-file.txt"
try:
etag = self.setup_scenario(source_bucket_name, dest_bucket_name, object_key)
self.display_menu(source_bucket_name, dest_bucket_name, object_key, etag)
finally:
self.cleanup_scenario(source_bucket_name, dest_bucket_name)
print("-" * 88)
print("Thanks for watching.")
print("-" * 88)
if __name__ == "__main__":
scenario = ConditionalRequestsScenario(
S3ConditionalRequests.from_client(), boto3.client("s3")
)
scenario.run_scenario()
```
条件付きリクエストオペレーションを定義するラッパークラス。
```
import boto3
import logging
from botocore.exceptions import ClientError
# Configure logging
logger = logging.getLogger(__name__)
class S3ConditionalRequests:
"""Encapsulates S3 conditional request operations."""
def __init__(self, s3_client):
self.s3 = s3_client
@classmethod
def from_client(cls):
"""
Instantiates this class from a Boto3 client.
"""
s3_client = boto3.client("s3")
return cls(s3_client)
def get_object_conditional(
self,
object_key: str,
source_bucket: str,
condition_type: str,
condition_value: str,
):
"""
Retrieves an object from Amazon S3 with a conditional request.
:param object_key: The key of the object to retrieve.
:param source_bucket: The source bucket of the object.
:param condition_type: The type of condition: 'IfMatch', 'IfNoneMatch', 'IfModifiedSince', 'IfUnmodifiedSince'.
:param condition_value: The value to use for the condition.
"""
try:
response = self.s3.get_object(
Bucket=source_bucket,
Key=object_key,
**{condition_type: condition_value},
)
sample_bytes = response["Body"].read(20)
print(
f"\tConditional read successful. Here are the first 20 bytes of the object:\n"
)
print(f"\t{sample_bytes}")
except ClientError as e:
error_code = e.response["Error"]["Code"]
if error_code == "PreconditionFailed":
print("\tConditional read failed: Precondition failed")
elif error_code == "304": # Not modified error code.
print("\tConditional read failed: Object not modified")
else:
logger.error(f"Unexpected error: {error_code}")
raise
def put_object_conditional(self, object_key: str, source_bucket: str, data: bytes):
"""
Uploads an object to Amazon S3 with a conditional request. Prevents overwrite
using an IfNoneMatch condition for the object key.
:param object_key: The key of the object to upload.
:param source_bucket: The source bucket of the object.
:param data: The data to upload.
"""
try:
self.s3.put_object(
Bucket=source_bucket, Key=object_key, Body=data, IfNoneMatch="*"
)
print(
f"\tConditional write successful for key {object_key} in bucket {source_bucket}."
)
except ClientError as e:
error_code = e.response["Error"]["Code"]
if error_code == "PreconditionFailed":
print("\tConditional write failed: Precondition failed")
else:
logger.error(f"Unexpected error: {error_code}")
raise
def copy_object_conditional(
self,
source_key: str,
dest_key: str,
source_bucket: str,
dest_bucket: str,
condition_type: str,
condition_value: str,
):
"""
Copies an object from one Amazon S3 bucket to another with a conditional request.
:param source_key: The key of the source object to copy.
:param dest_key: The key of the destination object.
:param source_bucket: The source bucket of the object.
:param dest_bucket: The destination bucket of the object.
:param condition_type: The type of condition to apply, e.g.
'CopySourceIfMatch', 'CopySourceIfNoneMatch', 'CopySourceIfModifiedSince', 'CopySourceIfUnmodifiedSince'.
:param condition_value: The value to use for the condition.
"""
try:
self.s3.copy_object(
Bucket=dest_bucket,
Key=dest_key,
CopySource={"Bucket": source_bucket, "Key": source_key},
**{condition_type: condition_value},
)
print(
f"\tConditional copy successful for key {dest_key} in bucket {dest_bucket}."
)
except ClientError as e:
error_code = e.response["Error"]["Code"]
if error_code == "PreconditionFailed":
print("\tConditional copy failed: Precondition failed")
elif error_code == "304": # Not modified error code.
print("\tConditional copy failed: Object not modified")
else:
logger.error(f"Unexpected error: {error_code}")
raise
```
+ API の詳細については、「**AWS SDK for Python (Boto3) API リファレンス」の以下のトピックを参照してください。
+ [CopyObject](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/CopyObject)
+ [GetObject](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/GetObject)
+ [PutObject](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/PutObject)
### バージョン管理されているオブジェクトを Lambda 関数でバッチで管理する
次のコード例は、バージョン管理されている S3 オブジェクトを Lambda 関数でバッチで管理する方法を示しています。
**SDK for Python (Boto3)**
AWS Lambda 関数を呼び出して処理を実行するジョブを作成して、Amazon Simple Storage Service (Amazon S3) バージョンのオブジェクトをバッチで操作する方法を示します。この例では、バージョン対応のバケットを作成し、Lewis Carroll の詩「*You Are Old, Father William*」からスタンザをアップロードし、Amazon S3 のバッチジョブを使用して、さまざまな方法で詩をひねります。
**以下ではその方法を説明しています。**
+ バージョン管理されたオブジェクトを操作する Lambda 関数を作成します。
+ 更新するオブジェクトのマニフェストを作成します。
+ Lambda 関数を呼び出してオブジェクトを更新するバッチジョブを作成します。
+ Lambda 関数を削除します。
+ バージョン管理されているバケットを空にして削除します。
この例は GitHub で最もよく確認できます。完全なソースコードとセットアップおよび実行の手順については、[GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/s3_versioning#batch-operation-demo) で完全な例を参照してください。
**この例で使用されているサービス**
+ Amazon S3
### 大きなファイルをアップロードまたはダウンロードする
次のコード例は、Amazon S3 との間で大きなファイルをアップロードまたはダウンロードする方法を示しています。
詳細については、「[マルチパートアップロードを使用したオブジェクトのアップロード](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpu-upload-object.html)」を参照してください。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/file_transfer#code-examples)での設定と実行の方法を確認してください。
使用可能な転送マネージャの設定を使用して、ファイルを転送する関数を作成します。コールバッククラスを使用して、ファイル転送中にコールバックの進行状況を書き込みます。
```
import sys
import threading
import boto3
from boto3.s3.transfer import TransferConfig
MB = 1024 * 1024
s3 = boto3.resource("s3")
class TransferCallback:
"""
Handle callbacks from the transfer manager.
The transfer manager periodically calls the __call__ method throughout
the upload and download process so that it can take action, such as
displaying progress to the user and collecting data about the transfer.
"""
def __init__(self, target_size):
self._target_size = target_size
self._total_transferred = 0
self._lock = threading.Lock()
self.thread_info = {}
def __call__(self, bytes_transferred):
"""
The callback method that is called by the transfer manager.
Display progress during file transfer and collect per-thread transfer
data. This method can be called by multiple threads, so shared instance
data is protected by a thread lock.
"""
thread = threading.current_thread()
with self._lock:
self._total_transferred += bytes_transferred
if thread.ident not in self.thread_info.keys():
self.thread_info[thread.ident] = bytes_transferred
else:
self.thread_info[thread.ident] += bytes_transferred
target = self._target_size * MB
sys.stdout.write(
f"\r{self._total_transferred} of {target} transferred "
f"({(self._total_transferred / target) * 100:.2f}%)."
)
sys.stdout.flush()
def upload_with_default_configuration(
local_file_path, bucket_name, object_key, file_size_mb
):
"""
Upload a file from a local folder to an Amazon S3 bucket, using the default
configuration.
"""
transfer_callback = TransferCallback(file_size_mb)
s3.Bucket(bucket_name).upload_file(
local_file_path, object_key, Callback=transfer_callback
)
return transfer_callback.thread_info
def upload_with_chunksize_and_meta(
local_file_path, bucket_name, object_key, file_size_mb, metadata=None
):
"""
Upload a file from a local folder to an Amazon S3 bucket, setting a
multipart chunk size and adding metadata to the Amazon S3 object.
The multipart chunk size controls the size of the chunks of data that are
sent in the request. A smaller chunk size typically results in the transfer
manager using more threads for the upload.
The metadata is a set of key-value pairs that are stored with the object
in Amazon S3.
"""
transfer_callback = TransferCallback(file_size_mb)
config = TransferConfig(multipart_chunksize=1 * MB)
extra_args = {"Metadata": metadata} if metadata else None
s3.Bucket(bucket_name).upload_file(
local_file_path,
object_key,
Config=config,
ExtraArgs=extra_args,
Callback=transfer_callback,
)
return transfer_callback.thread_info
def upload_with_high_threshold(local_file_path, bucket_name, object_key, file_size_mb):
"""
Upload a file from a local folder to an Amazon S3 bucket, setting a
multipart threshold larger than the size of the file.
Setting a multipart threshold larger than the size of the file results
in the transfer manager sending the file as a standard upload instead of
a multipart upload.
"""
transfer_callback = TransferCallback(file_size_mb)
config = TransferConfig(multipart_threshold=file_size_mb * 2 * MB)
s3.Bucket(bucket_name).upload_file(
local_file_path, object_key, Config=config, Callback=transfer_callback
)
return transfer_callback.thread_info
def upload_with_sse(
local_file_path, bucket_name, object_key, file_size_mb, sse_key=None
):
"""
Upload a file from a local folder to an Amazon S3 bucket, adding server-side
encryption with customer-provided encryption keys to the object.
When this kind of encryption is specified, Amazon S3 encrypts the object
at rest and allows downloads only when the expected encryption key is
provided in the download request.
"""
transfer_callback = TransferCallback(file_size_mb)
if sse_key:
extra_args = {"SSECustomerAlgorithm": "AES256", "SSECustomerKey": sse_key}
else:
extra_args = None
s3.Bucket(bucket_name).upload_file(
local_file_path, object_key, ExtraArgs=extra_args, Callback=transfer_callback
)
return transfer_callback.thread_info
def download_with_default_configuration(
bucket_name, object_key, download_file_path, file_size_mb
):
"""
Download a file from an Amazon S3 bucket to a local folder, using the
default configuration.
"""
transfer_callback = TransferCallback(file_size_mb)
s3.Bucket(bucket_name).Object(object_key).download_file(
download_file_path, Callback=transfer_callback
)
return transfer_callback.thread_info
def download_with_single_thread(
bucket_name, object_key, download_file_path, file_size_mb
):
"""
Download a file from an Amazon S3 bucket to a local folder, using a
single thread.
"""
transfer_callback = TransferCallback(file_size_mb)
config = TransferConfig(use_threads=False)
s3.Bucket(bucket_name).Object(object_key).download_file(
download_file_path, Config=config, Callback=transfer_callback
)
return transfer_callback.thread_info
def download_with_high_threshold(
bucket_name, object_key, download_file_path, file_size_mb
):
"""
Download a file from an Amazon S3 bucket to a local folder, setting a
multipart threshold larger than the size of the file.
Setting a multipart threshold larger than the size of the file results
in the transfer manager sending the file as a standard download instead
of a multipart download.
"""
transfer_callback = TransferCallback(file_size_mb)
config = TransferConfig(multipart_threshold=file_size_mb * 2 * MB)
s3.Bucket(bucket_name).Object(object_key).download_file(
download_file_path, Config=config, Callback=transfer_callback
)
return transfer_callback.thread_info
def download_with_sse(
bucket_name, object_key, download_file_path, file_size_mb, sse_key
):
"""
Download a file from an Amazon S3 bucket to a local folder, adding a
customer-provided encryption key to the request.
When this kind of encryption is specified, Amazon S3 encrypts the object
at rest and allows downloads only when the expected encryption key is
provided in the download request.
"""
transfer_callback = TransferCallback(file_size_mb)
if sse_key:
extra_args = {"SSECustomerAlgorithm": "AES256", "SSECustomerKey": sse_key}
else:
extra_args = None
s3.Bucket(bucket_name).Object(object_key).download_file(
download_file_path, ExtraArgs=extra_args, Callback=transfer_callback
)
return transfer_callback.thread_info
```
転送マネージャの機能とレポート結果のデモンストレーションを行います。
```
import hashlib
import os
import platform
import shutil
import time
import boto3
from boto3.s3.transfer import TransferConfig
from botocore.exceptions import ClientError
from botocore.exceptions import ParamValidationError
from botocore.exceptions import NoCredentialsError
import file_transfer
MB = 1024 * 1024
# These configuration attributes affect both uploads and downloads.
CONFIG_ATTRS = (
"multipart_threshold",
"multipart_chunksize",
"max_concurrency",
"use_threads",
)
# These configuration attributes affect only downloads.
DOWNLOAD_CONFIG_ATTRS = ("max_io_queue", "io_chunksize", "num_download_attempts")
class TransferDemoManager:
"""
Manages the demonstration. Collects user input from a command line, reports
transfer results, maintains a list of artifacts created during the
demonstration, and cleans them up after the demonstration is completed.
"""
def __init__(self):
self._s3 = boto3.resource("s3")
self._chore_list = []
self._create_file_cmd = None
self._size_multiplier = 0
self.file_size_mb = 30
self.demo_folder = None
self.demo_bucket = None
self._setup_platform_specific()
self._terminal_width = shutil.get_terminal_size(fallback=(80, 80))[0]
def collect_user_info(self):
"""
Collect local folder and Amazon S3 bucket name from the user. These
locations are used to store files during the demonstration.
"""
while not self.demo_folder:
self.demo_folder = input(
"Which file folder do you want to use to store " "demonstration files? "
)
if not os.path.isdir(self.demo_folder):
print(f"{self.demo_folder} isn't a folder!")
self.demo_folder = None
while not self.demo_bucket:
self.demo_bucket = input(
"Which Amazon S3 bucket do you want to use to store "
"demonstration files? "
)
try:
self._s3.meta.client.head_bucket(Bucket=self.demo_bucket)
except ParamValidationError as err:
print(err)
self.demo_bucket = None
except ClientError as err:
print(err)
print(
f"Either {self.demo_bucket} doesn't exist or you don't "
f"have access to it."
)
self.demo_bucket = None
def demo(
self, question, upload_func, download_func, upload_args=None, download_args=None
):
"""Run a demonstration.
Ask the user if they want to run this specific demonstration.
If they say yes, create a file on the local path, upload it
using the specified upload function, then download it using the
specified download function.
"""
if download_args is None:
download_args = {}
if upload_args is None:
upload_args = {}
question = question.format(self.file_size_mb)
answer = input(f"{question} (y/n)")
if answer.lower() == "y":
local_file_path, object_key, download_file_path = self._create_demo_file()
file_transfer.TransferConfig = self._config_wrapper(
TransferConfig, CONFIG_ATTRS
)
self._report_transfer_params(
"Uploading", local_file_path, object_key, **upload_args
)
start_time = time.perf_counter()
thread_info = upload_func(
local_file_path,
self.demo_bucket,
object_key,
self.file_size_mb,
**upload_args,
)
end_time = time.perf_counter()
self._report_transfer_result(thread_info, end_time - start_time)
file_transfer.TransferConfig = self._config_wrapper(
TransferConfig, CONFIG_ATTRS + DOWNLOAD_CONFIG_ATTRS
)
self._report_transfer_params(
"Downloading", object_key, download_file_path, **download_args
)
start_time = time.perf_counter()
thread_info = download_func(
self.demo_bucket,
object_key,
download_file_path,
self.file_size_mb,
**download_args,
)
end_time = time.perf_counter()
self._report_transfer_result(thread_info, end_time - start_time)
def last_name_set(self):
"""Get the name set used for the last demo."""
return self._chore_list[-1]
def cleanup(self):
"""
Remove files from the demo folder, and uploaded objects from the
Amazon S3 bucket.
"""
print("-" * self._terminal_width)
for local_file_path, s3_object_key, downloaded_file_path in self._chore_list:
print(f"Removing {local_file_path}")
try:
os.remove(local_file_path)
except FileNotFoundError as err:
print(err)
print(f"Removing {downloaded_file_path}")
try:
os.remove(downloaded_file_path)
except FileNotFoundError as err:
print(err)
if self.demo_bucket:
print(f"Removing {self.demo_bucket}:{s3_object_key}")
try:
self._s3.Bucket(self.demo_bucket).Object(s3_object_key).delete()
except ClientError as err:
print(err)
def _setup_platform_specific(self):
"""Set up platform-specific command used to create a large file."""
if platform.system() == "Windows":
self._create_file_cmd = "fsutil file createnew {} {}"
self._size_multiplier = MB
elif platform.system() == "Linux" or platform.system() == "Darwin":
self._create_file_cmd = f"dd if=/dev/urandom of={{}} " f"bs={MB} count={{}}"
self._size_multiplier = 1
else:
raise EnvironmentError(
f"Demo of platform {platform.system()} isn't supported."
)
def _create_demo_file(self):
"""
Create a file in the demo folder specified by the user. Store the local
path, object name, and download path for later cleanup.
Only the local file is created by this method. The Amazon S3 object and
download file are created later during the demonstration.
Returns:
A tuple that contains the local file path, object name, and download
file path.
"""
file_name_template = "TestFile{}-{}.demo"
local_suffix = "local"
object_suffix = "s3object"
download_suffix = "downloaded"
file_tag = len(self._chore_list) + 1
local_file_path = os.path.join(
self.demo_folder, file_name_template.format(file_tag, local_suffix)
)
s3_object_key = file_name_template.format(file_tag, object_suffix)
downloaded_file_path = os.path.join(
self.demo_folder, file_name_template.format(file_tag, download_suffix)
)
filled_cmd = self._create_file_cmd.format(
local_file_path, self.file_size_mb * self._size_multiplier
)
print(
f"Creating file of size {self.file_size_mb} MB "
f"in {self.demo_folder} by running:"
)
print(f"{'':4}{filled_cmd}")
os.system(filled_cmd)
chore = (local_file_path, s3_object_key, downloaded_file_path)
self._chore_list.append(chore)
return chore
def _report_transfer_params(self, verb, source_name, dest_name, **kwargs):
"""Report configuration and extra arguments used for a file transfer."""
print("-" * self._terminal_width)
print(f"{verb} {source_name} ({self.file_size_mb} MB) to {dest_name}")
if kwargs:
print("With extra args:")
for arg, value in kwargs.items():
print(f'{"":4}{arg:<20}: {value}')
@staticmethod
def ask_user(question):
"""
Ask the user a yes or no question.
Returns:
True when the user answers 'y' or 'Y'; otherwise, False.
"""
answer = input(f"{question} (y/n) ")
return answer.lower() == "y"
@staticmethod
def _config_wrapper(func, config_attrs):
def wrapper(*args, **kwargs):
config = func(*args, **kwargs)
print("With configuration:")
for attr in config_attrs:
print(f'{"":4}{attr:<20}: {getattr(config, attr)}')
return config
return wrapper
@staticmethod
def _report_transfer_result(thread_info, elapsed):
"""Report the result of a transfer, including per-thread data."""
print(f"\nUsed {len(thread_info)} threads.")
for ident, byte_count in thread_info.items():
print(f"{'':4}Thread {ident} copied {byte_count} bytes.")
print(f"Your transfer took {elapsed:.2f} seconds.")
def main():
"""
Run the demonstration script for s3_file_transfer.
"""
demo_manager = TransferDemoManager()
demo_manager.collect_user_info()
# Upload and download with default configuration. Because the file is 30 MB
# and the default multipart_threshold is 8 MB, both upload and download are
# multipart transfers.
demo_manager.demo(
"Do you want to upload and download a {} MB file "
"using the default configuration?",
file_transfer.upload_with_default_configuration,
file_transfer.download_with_default_configuration,
)
# Upload and download with multipart_threshold set higher than the size of
# the file. This causes the transfer manager to use standard transfers
# instead of multipart transfers.
demo_manager.demo(
"Do you want to upload and download a {} MB file "
"as a standard (not multipart) transfer?",
file_transfer.upload_with_high_threshold,
file_transfer.download_with_high_threshold,
)
# Upload with specific chunk size and additional metadata.
# Download with a single thread.
demo_manager.demo(
"Do you want to upload a {} MB file with a smaller chunk size and "
"then download the same file using a single thread?",
file_transfer.upload_with_chunksize_and_meta,
file_transfer.download_with_single_thread,
upload_args={
"metadata": {
"upload_type": "chunky",
"favorite_color": "aqua",
"size": "medium",
}
},
)
# Upload using server-side encryption with customer-provided
# encryption keys.
# Generate a 256-bit key from a passphrase.
sse_key = hashlib.sha256("demo_passphrase".encode("utf-8")).digest()
demo_manager.demo(
"Do you want to upload and download a {} MB file using "
"server-side encryption?",
file_transfer.upload_with_sse,
file_transfer.download_with_sse,
upload_args={"sse_key": sse_key},
download_args={"sse_key": sse_key},
)
# Download without specifying an encryption key to show that the
# encryption key must be included to download an encrypted object.
if demo_manager.ask_user(
"Do you want to try to download the encrypted "
"object without sending the required key?"
):
try:
_, object_key, download_file_path = demo_manager.last_name_set()
file_transfer.download_with_default_configuration(
demo_manager.demo_bucket,
object_key,
download_file_path,
demo_manager.file_size_mb,
)
except ClientError as err:
print(
"Got expected error when trying to download an encrypted "
"object without specifying encryption info:"
)
print(f"{'':4}{err}")
# Remove all created and downloaded files, remove all objects from
# S3 storage.
if demo_manager.ask_user(
"Demonstration complete. Do you want to remove local files " "and S3 objects?"
):
demo_manager.cleanup()
if __name__ == "__main__":
try:
main()
except NoCredentialsError as error:
print(error)
print(
"To run this example, you must have valid credentials in "
"a shared credential file or set in environment variables."
)
```
### バージョン管理されたオブジェクトを操作する
次のコード例は、以下の操作方法を示しています。
+ バージョニングされた S3 バケットを作成します。
+ オブジェクトのすべてのバージョンを取得します。
+ オブジェクトを以前のバージョンにロールバックします。
+ バージョニングされたオブジェクトを削除して復元します。
+ オブジェクトのバージョンを完全に削除します。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/s3_versioning#code-examples)での設定と実行の方法を確認してください。
S3 アクションをラップする関数を作成します。
```
def create_versioned_bucket(bucket_name, prefix):
"""
Creates an Amazon S3 bucket, enables it for versioning, and configures a lifecycle
that expires noncurrent object versions after 7 days.
Adding a lifecycle configuration to a versioned bucket is a best practice.
It helps prevent objects in the bucket from accumulating a large number of
noncurrent versions, which can slow down request performance.
Usage is shown in the usage_demo_single_object function at the end of this module.
:param bucket_name: The name of the bucket to create.
:param prefix: Identifies which objects are automatically expired under the
configured lifecycle rules.
:return: The newly created bucket.
"""
try:
bucket = s3.create_bucket(
Bucket=bucket_name,
CreateBucketConfiguration={
"LocationConstraint": s3.meta.client.meta.region_name
},
)
logger.info("Created bucket %s.", bucket.name)
except ClientError as error:
if error.response["Error"]["Code"] == "BucketAlreadyOwnedByYou":
logger.warning("Bucket %s already exists! Using it.", bucket_name)
bucket = s3.Bucket(bucket_name)
else:
logger.exception("Couldn't create bucket %s.", bucket_name)
raise
try:
bucket.Versioning().enable()
logger.info("Enabled versioning on bucket %s.", bucket.name)
except ClientError:
logger.exception("Couldn't enable versioning on bucket %s.", bucket.name)
raise
try:
expiration = 7
bucket.LifecycleConfiguration().put(
LifecycleConfiguration={
"Rules": [
{
"Status": "Enabled",
"Prefix": prefix,
"NoncurrentVersionExpiration": {"NoncurrentDays": expiration},
}
]
}
)
logger.info(
"Configured lifecycle to expire noncurrent versions after %s days "
"on bucket %s.",
expiration,
bucket.name,
)
except ClientError as error:
logger.warning(
"Couldn't configure lifecycle on bucket %s because %s. "
"Continuing anyway.",
bucket.name,
error,
)
return bucket
def rollback_object(bucket, object_key, version_id):
"""
Rolls back an object to an earlier version by deleting all versions that
occurred after the specified rollback version.
Usage is shown in the usage_demo_single_object function at the end of this module.
:param bucket: The bucket that holds the object to roll back.
:param object_key: The object to roll back.
:param version_id: The version ID to roll back to.
"""
# Versions must be sorted by last_modified date because delete markers are
# at the end of the list even when they are interspersed in time.
versions = sorted(
bucket.object_versions.filter(Prefix=object_key),
key=attrgetter("last_modified"),
reverse=True,
)
logger.debug(
"Got versions:\n%s",
"\n".join(
[
f"\t{version.version_id}, last modified {version.last_modified}"
for version in versions
]
),
)
if version_id in [ver.version_id for ver in versions]:
print(f"Rolling back to version {version_id}")
for version in versions:
if version.version_id != version_id:
version.delete()
print(f"Deleted version {version.version_id}")
else:
break
print(f"Active version is now {bucket.Object(object_key).version_id}")
else:
raise KeyError(
f"{version_id} was not found in the list of versions for " f"{object_key}."
)
def revive_object(bucket, object_key):
"""
Revives a versioned object that was deleted by removing the object's active
delete marker.
A versioned object presents as deleted when its latest version is a delete marker.
By removing the delete marker, we make the previous version the latest version
and the object then presents as *not* deleted.
Usage is shown in the usage_demo_single_object function at the end of this module.
:param bucket: The bucket that contains the object.
:param object_key: The object to revive.
"""
# Get the latest version for the object.
response = s3.meta.client.list_object_versions(
Bucket=bucket.name, Prefix=object_key, MaxKeys=1
)
if "DeleteMarkers" in response:
latest_version = response["DeleteMarkers"][0]
if latest_version["IsLatest"]:
logger.info(
"Object %s was indeed deleted on %s. Let's revive it.",
object_key,
latest_version["LastModified"],
)
obj = bucket.Object(object_key)
obj.Version(latest_version["VersionId"]).delete()
logger.info(
"Revived %s, active version is now %s with body '%s'",
object_key,
obj.version_id,
obj.get()["Body"].read(),
)
else:
logger.warning(
"Delete marker is not the latest version for %s!", object_key
)
elif "Versions" in response:
logger.warning("Got an active version for %s, nothing to do.", object_key)
else:
logger.error("Couldn't get any version info for %s.", object_key)
def permanently_delete_object(bucket, object_key):
"""
Permanently deletes a versioned object by deleting all of its versions.
Usage is shown in the usage_demo_single_object function at the end of this module.
:param bucket: The bucket that contains the object.
:param object_key: The object to delete.
"""
try:
bucket.object_versions.filter(Prefix=object_key).delete()
logger.info("Permanently deleted all versions of object %s.", object_key)
except ClientError:
logger.exception("Couldn't delete all versions of %s.", object_key)
raise
```
詩のスタンザをバージョニングされたオブジェクトにアップロードし、一連のアクションを実行します。
```
def usage_demo_single_object(obj_prefix="demo-versioning/"):
"""
Demonstrates usage of versioned object functions. This demo uploads a stanza
of a poem and performs a series of revisions, deletions, and revivals on it.
:param obj_prefix: The prefix to assign to objects created by this demo.
"""
with open("father_william.txt") as file:
stanzas = file.read().split("\n\n")
width = get_terminal_size((80, 20))[0]
print("-" * width)
print("Welcome to the usage demonstration of Amazon S3 versioning.")
print(
"This demonstration uploads a single stanza of a poem to an Amazon "
"S3 bucket and then applies various revisions to it."
)
print("-" * width)
print("Creating a version-enabled bucket for the demo...")
bucket = create_versioned_bucket("bucket-" + str(uuid.uuid1()), obj_prefix)
print("\nThe initial version of our stanza:")
print(stanzas[0])
# Add the first stanza and revise it a few times.
print("\nApplying some revisions to the stanza...")
obj_stanza_1 = bucket.Object(f"{obj_prefix}stanza-1")
obj_stanza_1.put(Body=bytes(stanzas[0], "utf-8"))
obj_stanza_1.put(Body=bytes(stanzas[0].upper(), "utf-8"))
obj_stanza_1.put(Body=bytes(stanzas[0].lower(), "utf-8"))
obj_stanza_1.put(Body=bytes(stanzas[0][::-1], "utf-8"))
print(
"The latest version of the stanza is now:",
obj_stanza_1.get()["Body"].read().decode("utf-8"),
sep="\n",
)
# Versions are returned in order, most recent first.
obj_stanza_1_versions = bucket.object_versions.filter(Prefix=obj_stanza_1.key)
print(
"The version data of the stanza revisions:",
*[
f" {version.version_id}, last modified {version.last_modified}"
for version in obj_stanza_1_versions
],
sep="\n",
)
# Rollback two versions.
print("\nRolling back two versions...")
rollback_object(bucket, obj_stanza_1.key, list(obj_stanza_1_versions)[2].version_id)
print(
"The latest version of the stanza:",
obj_stanza_1.get()["Body"].read().decode("utf-8"),
sep="\n",
)
# Delete the stanza
print("\nDeleting the stanza...")
obj_stanza_1.delete()
try:
obj_stanza_1.get()
except ClientError as error:
if error.response["Error"]["Code"] == "NoSuchKey":
print("The stanza is now deleted (as expected).")
else:
raise
# Revive the stanza
print("\nRestoring the stanza...")
revive_object(bucket, obj_stanza_1.key)
print(
"The stanza is restored! The latest version is again:",
obj_stanza_1.get()["Body"].read().decode("utf-8"),
sep="\n",
)
# Permanently delete all versions of the object. This cannot be undone!
print("\nPermanently deleting all versions of the stanza...")
permanently_delete_object(bucket, obj_stanza_1.key)
obj_stanza_1_versions = bucket.object_versions.filter(Prefix=obj_stanza_1.key)
if len(list(obj_stanza_1_versions)) == 0:
print("The stanza has been permanently deleted and now has no versions.")
else:
print("Something went wrong. The stanza still exists!")
print(f"\nRemoving {bucket.name}...")
bucket.delete()
print(f"{bucket.name} deleted.")
print("Demo done!")
```
+ API の詳細については、「**AWS SDK for Python (Boto3) API リファレンス」の以下のトピックを参照してください。
+ [CreateBucket](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/CreateBucket)
+ [DeleteObject](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/DeleteObject)
+ [ListObjectVersions](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/ListObjectVersions)
+ [PutBucketLifecycleConfiguration](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/PutBucketLifecycleConfiguration)
## サーバーレスサンプル
### Amazon S3 トリガーから Lambda 関数を呼び出す
次のコード例は、S3 バケットにオブジェクトをアップロードすることによってトリガーされるイベントを受け取る Lambda 関数を実装する方法を示しています。この関数は、イベントパラメータから S3 バケット名とオブジェクトキーを取得し、Amazon S3 API を呼び出してオブジェクトのコンテンツタイプを取得してログに記録します。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。[サーバーレスサンプル](https://github.com/aws-samples/serverless-snippets/tree/main/integration-s3-to-lambda)リポジトリで完全な例を検索し、設定および実行の方法を確認してください。
Python を使用して Lambda で S3 イベントを消費します。
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
import json
import urllib.parse
import boto3
print('Loading function')
s3 = boto3.client('s3')
def lambda_handler(event, context):
#print("Received event: " + json.dumps(event, indent=2))
# Get the object from the event and show its content type
bucket = event['Records'][0]['s3']['bucket']['name']
key = urllib.parse.unquote_plus(event['Records'][0]['s3']['object']['key'], encoding='utf-8')
try:
response = s3.get_object(Bucket=bucket, Key=key)
print("CONTENT TYPE: " + response['ContentType'])
return response['ContentType']
except Exception as e:
print(e)
print('Error getting object {} from bucket {}. Make sure they exist and your bucket is in the same region as this function.'.format(key, bucket))
raise e
```
# SDK for Python (Boto3) を使用した Amazon S3 Control の例
次のコード例は、Amazon S3 Control AWS SDK for Python (Boto3) で を使用してアクションを実行し、一般的なシナリオを実装する方法を示しています。
*基本* は、重要なオペレーションをサービス内で実行する方法を示すコード例です。
*アクション*はより大きなプログラムからのコードの抜粋であり、コンテキスト内で実行する必要があります。アクションは個々のサービス機能を呼び出す方法を示していますが、コンテキスト内のアクションは、関連するシナリオで確認できます。
各例には完全なソースコードへのリンクが含まれており、コンテキスト内でコードを設定および実行する方法の手順を確認できます。
**Topics**
+ [はじめに](#get_started)
+ [基本](#basics)
+ [アクション](#actions)
## はじめに
### Hello Amazon S3 Control
次のコード例は、Amazon S3 Control の使用を開始する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/scenarios/batch#code-examples)での設定と実行の方法を確認してください。
```
def list_jobs(self, account_id: str) -> None:
"""
List all batch jobs for the account.
Args:
account_id (str): AWS account ID
"""
try:
response = self.s3control_client.list_jobs(
AccountId=account_id,
JobStatuses=['Active', 'Complete', 'Cancelled', 'Failed', 'New', 'Paused', 'Pausing', 'Preparing', 'Ready', 'Suspended']
)
jobs = response.get('Jobs', [])
for job in jobs:
print(f"The job id is {job['JobId']}")
print(f"The job priority is {job['Priority']}")
except ClientError as e:
print(f"Error listing jobs: {e}")
raise
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス* の「[ListJobs](https://docs.aws.amazon.com/goto/boto3/s3control-2018-08-20/ListJobs)」を参照してください。
## 基本
### 基本を学ぶ
次のコード例は、Amazon S3 Control のコアオペレーションを学ぶ方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/scenarios/batch#code-examples)での設定と実行の方法を確認してください。
S3 バッチの基本シナリオについて説明します。
```
class S3BatchWrapper:
"""Wrapper class for managing S3 Batch Operations."""
def __init__(self, s3_client: Any, s3control_client: Any, sts_client: Any) -> None:
"""
Initializes the S3BatchWrapper with AWS service clients.
:param s3_client: A Boto3 Amazon S3 client. This client provides low-level
access to AWS S3 services.
:param s3control_client: A Boto3 Amazon S3 Control client. This client provides
low-level access to AWS S3 Control services.
:param sts_client: A Boto3 AWS STS client. This client provides low-level
access to AWS STS services.
"""
self.s3_client = s3_client
self.s3control_client = s3control_client
self.sts_client = sts_client
# Get region from the client for bucket creation logic
self.region_name = self.s3_client.meta.region_name
def get_account_id(self) -> str:
"""
Get AWS account ID.
Returns:
str: AWS account ID
"""
return self.sts_client.get_caller_identity()["Account"]
def create_bucket(self, bucket_name: str) -> None:
"""
Create an S3 bucket.
Args:
bucket_name (str): Name of the bucket to create
Raises:
ClientError: If bucket creation fails
"""
try:
if self.region_name and self.region_name != 'us-east-1':
self.s3_client.create_bucket(
Bucket=bucket_name,
CreateBucketConfiguration={
'LocationConstraint': self.region_name
}
)
else:
self.s3_client.create_bucket(Bucket=bucket_name)
print(f"Created bucket: {bucket_name}")
except ClientError as e:
print(f"Error creating bucket: {e}")
raise
def upload_files_to_bucket(self, bucket_name: str, file_names: List[str]) -> str:
"""
Upload files to S3 bucket including manifest file.
Args:
bucket_name (str): Target bucket name
file_names (list): List of file names to upload
Returns:
str: ETag of the manifest file
Raises:
ClientError: If file upload fails
"""
try:
for file_name in file_names:
if file_name != "job-manifest.csv":
content = f"Content for {file_name}"
self.s3_client.put_object(
Bucket=bucket_name,
Key=file_name,
Body=content.encode('utf-8')
)
print(f"Uploaded {file_name} to {bucket_name}")
manifest_content = ""
for file_name in file_names:
if file_name != "job-manifest.csv":
manifest_content += f"{bucket_name},{file_name}\n"
manifest_response = self.s3_client.put_object(
Bucket=bucket_name,
Key="job-manifest.csv",
Body=manifest_content.encode('utf-8')
)
print(f"Uploaded manifest file to {bucket_name}")
print(f"Manifest content:\n{manifest_content}")
return manifest_response['ETag'].strip('"')
except ClientError as e:
print(f"Error uploading files: {e}")
raise
def create_s3_batch_job(self, account_id: str, role_arn: str, manifest_location: str,
report_bucket_name: str) -> str:
"""
Create an S3 batch operation job.
Args:
account_id (str): AWS account ID
role_arn (str): IAM role ARN for batch operations
manifest_location (str): Location of the manifest file
report_bucket_name (str): Bucket for job reports
Returns:
str: Job ID
Raises:
ClientError: If job creation fails
"""
try:
bucket_name = manifest_location.split(':::')[1].split('/')[0]
manifest_key = 'job-manifest.csv'
manifest_obj = self.s3_client.head_object(
Bucket=bucket_name,
Key=manifest_key
)
etag = manifest_obj['ETag'].strip('"')
response = self.s3control_client.create_job(
AccountId=account_id,
Operation={
'S3PutObjectTagging': {
'TagSet': [
{
'Key': 'BatchTag',
'Value': 'BatchValue'
},
]
}
},
Report={
'Bucket': report_bucket_name,
'Format': 'Report_CSV_20180820',
'Enabled': True,
'Prefix': 'batch-op-reports',
'ReportScope': 'AllTasks'
},
Manifest={
'Spec': {
'Format': 'S3BatchOperations_CSV_20180820',
'Fields': ['Bucket', 'Key']
},
'Location': {
'ObjectArn': manifest_location,
'ETag': etag
}
},
Priority=10,
RoleArn=role_arn,
Description='Batch job for tagging objects',
ConfirmationRequired=True
)
job_id = response['JobId']
print(f"The Job id is {job_id}")
return job_id
except ClientError as e:
print(f"Error creating batch job: {e}")
if 'Message' in str(e):
print(f"Detailed error message: {e.response['Message']}")
raise
def check_job_failure_reasons(self, job_id: str, account_id: str) -> List[Dict[str, Any]]:
"""
Check for any failure reasons of a batch job.
Args:
job_id (str): ID of the batch job
account_id (str): AWS account ID
Returns:
list: List of failure reasons
Raises:
ClientError: If checking job failure reasons fails
"""
try:
response = self.s3control_client.describe_job(
AccountId=account_id,
JobId=job_id
)
if 'FailureReasons' in response['Job']:
for reason in response['Job']['FailureReasons']:
print(f"- {reason}")
return response['Job'].get('FailureReasons', [])
except ClientError as e:
print(f"Error checking job failure reasons: {e}")
raise
def wait_for_job_ready(self, job_id: str, account_id: str, desired_status: str = 'Ready') -> bool:
"""
Wait for a job to reach the desired status.
Args:
job_id (str): ID of the batch job
account_id (str): AWS account ID
desired_status (str): Target status to wait for
Returns:
bool: True if desired status is reached, False otherwise
Raises:
ClientError: If checking job status fails
"""
print(f"Waiting for job to become {desired_status}...")
max_attempts = 60
attempt = 0
while attempt < max_attempts:
try:
response = self.s3control_client.describe_job(
AccountId=account_id,
JobId=job_id
)
current_status = response['Job']['Status']
print(f"Current job status: {current_status}")
if current_status == desired_status:
return True
if current_status == 'Suspended':
print("Job is in Suspended state, can proceed with activation")
return True
if current_status in ['Active', 'Failed', 'Cancelled', 'Complete']:
print(f"Job is in {current_status} state, cannot reach {desired_status} status")
if 'FailureReasons' in response['Job']:
print("Failure reasons:")
for reason in response['Job']['FailureReasons']:
print(f"- {reason}")
return False
time.sleep(20)
attempt += 1
except ClientError as e:
print(f"Error checking job status: {e}")
raise
print(f"Timeout waiting for job to become {desired_status}")
return False
def update_job_priority(self, job_id: str, account_id: str) -> None:
"""
Update the priority of a batch job and start it.
Args:
job_id (str): ID of the batch job
account_id (str): AWS account ID
"""
try:
response = self.s3control_client.describe_job(
AccountId=account_id,
JobId=job_id
)
current_status = response['Job']['Status']
print(f"Current job status: {current_status}")
if current_status in ['Ready', 'Suspended']:
self.s3control_client.update_job_priority(
AccountId=account_id,
JobId=job_id,
Priority=60
)
print("The job priority was updated")
try:
self.s3control_client.update_job_status(
AccountId=account_id,
JobId=job_id,
RequestedJobStatus='Ready'
)
print("Job activated successfully")
except ClientError as activation_error:
print(f"Note: Could not activate job automatically: {activation_error}")
print("Job priority was updated successfully. Job may need manual activation in the console.")
elif current_status in ['Active', 'Completing', 'Complete']:
print(f"Job is in '{current_status}' state - priority cannot be updated")
if current_status == 'Completing':
print("Job is finishing up and will complete soon.")
elif current_status == 'Complete':
print("Job has already completed successfully.")
else:
print("Job is currently running.")
else:
print(f"Job is in '{current_status}' state - priority update not allowed")
except ClientError as e:
print(f"Error updating job priority: {e}")
print("Continuing with the scenario...")
return
def cancel_job(self, job_id: str, account_id: str) -> None:
"""
Cancel an S3 batch job.
Args:
job_id (str): ID of the batch job
account_id (str): AWS account ID
"""
try:
response = self.s3control_client.describe_job(
AccountId=account_id,
JobId=job_id
)
current_status = response['Job']['Status']
print(f"Current job status: {current_status}")
if current_status in ['Ready', 'Suspended', 'Active']:
self.s3control_client.update_job_status(
AccountId=account_id,
JobId=job_id,
RequestedJobStatus='Cancelled'
)
print(f"Job {job_id} was successfully canceled.")
elif current_status in ['Completing', 'Complete']:
print(f"Job is in '{current_status}' state - cannot be cancelled")
if current_status == 'Completing':
print("Job is finishing up and will complete soon.")
elif current_status == 'Complete':
print("Job has already completed successfully.")
else:
print(f"Job is in '{current_status}' state - cancel not allowed")
except ClientError as e:
print(f"Error canceling job: {e}")
raise
def describe_job_details(self, job_id: str, account_id: str) -> None:
"""
Describe detailed information about a batch job.
Args:
job_id (str): ID of the batch job
account_id (str): AWS account ID
"""
try:
response = self.s3control_client.describe_job(
AccountId=account_id,
JobId=job_id
)
job = response['Job']
print(f"Job ID: {job['JobId']}")
print(f"Description: {job.get('Description', 'N/A')}")
print(f"Status: {job['Status']}")
print(f"Role ARN: {job['RoleArn']}")
print(f"Priority: {job['Priority']}")
if 'ProgressSummary' in job:
progress = job['ProgressSummary']
print(f"Progress Summary: Total={progress.get('TotalNumberOfTasks', 0)}, "
f"Succeeded={progress.get('NumberOfTasksSucceeded', 0)}, "
f"Failed={progress.get('NumberOfTasksFailed', 0)}")
except ClientError as e:
print(f"Error describing job: {e}")
raise
def get_job_tags(self, job_id: str, account_id: str) -> None:
"""
Get tags associated with a batch job.
Args:
job_id (str): ID of the batch job
account_id (str): AWS account ID
"""
try:
response = self.s3control_client.get_job_tagging(
AccountId=account_id,
JobId=job_id
)
tags = response.get('Tags', [])
if tags:
print(f"Tags for job {job_id}:")
for tag in tags:
print(f" {tag['Key']}: {tag['Value']}")
else:
print(f"No tags found for job ID: {job_id}")
except ClientError as e:
print(f"Error getting job tags: {e}")
raise
def put_job_tags(self, job_id: str, account_id: str) -> None:
"""
Add tags to a batch job.
Args:
job_id (str): ID of the batch job
account_id (str): AWS account ID
"""
try:
self.s3control_client.put_job_tagging(
AccountId=account_id,
JobId=job_id,
Tags=[
{'Key': 'Environment', 'Value': 'Development'},
{'Key': 'Team', 'Value': 'DataProcessing'}
]
)
print(f"Additional tags were added to job {job_id}")
except ClientError as e:
print(f"Error adding job tags: {e}")
raise
def list_jobs(self, account_id: str) -> None:
"""
List all batch jobs for the account.
Args:
account_id (str): AWS account ID
"""
try:
response = self.s3control_client.list_jobs(
AccountId=account_id,
JobStatuses=['Active', 'Complete', 'Cancelled', 'Failed', 'New', 'Paused', 'Pausing', 'Preparing', 'Ready', 'Suspended']
)
jobs = response.get('Jobs', [])
for job in jobs:
print(f"The job id is {job['JobId']}")
print(f"The job priority is {job['Priority']}")
except ClientError as e:
print(f"Error listing jobs: {e}")
raise
def delete_job_tags(self, job_id: str, account_id: str) -> None:
"""
Delete all tags from a batch job.
Args:
job_id (str): ID of the batch job
account_id (str): AWS account ID
"""
try:
self.s3control_client.delete_job_tagging(
AccountId=account_id,
JobId=job_id
)
print(f"You have successfully deleted {job_id} tagging.")
except ClientError as e:
print(f"Error deleting job tags: {e}")
raise
def cleanup_resources(self, bucket_name: str, file_names: List[str]) -> None:
"""
Clean up all resources created during the scenario.
Args:
bucket_name (str): Name of the bucket to clean up
file_names (list): List of files to delete
Raises:
ClientError: If cleanup fails
"""
try:
for file_name in file_names:
self.s3_client.delete_object(Bucket=bucket_name, Key=file_name)
print(f"Deleted {file_name}")
response = self.s3_client.list_objects_v2(
Bucket=bucket_name,
Prefix='batch-op-reports/'
)
if 'Contents' in response:
for obj in response['Contents']:
self.s3_client.delete_object(
Bucket=bucket_name,
Key=obj['Key']
)
print(f"Deleted {obj['Key']}")
self.s3_client.delete_bucket(Bucket=bucket_name)
print(f"Deleted bucket {bucket_name}")
except ClientError as e:
print(f"Error in cleanup: {e}")
raise
```
+ API の詳細については、『*AWS SDK for Python (Boto3) API リファレンス*』の以下のトピックを参照してください。
+ [CreateJob](https://docs.aws.amazon.com/goto/boto3/s3control-2018-08-20/CreateJob)
+ [DeleteJobTagging](https://docs.aws.amazon.com/goto/boto3/s3control-2018-08-20/DeleteJobTagging)
+ [DescribeJob](https://docs.aws.amazon.com/goto/boto3/s3control-2018-08-20/DescribeJob)
+ [GetJobTagging](https://docs.aws.amazon.com/goto/boto3/s3control-2018-08-20/GetJobTagging)
+ [ListJobs](https://docs.aws.amazon.com/goto/boto3/s3control-2018-08-20/ListJobs)
+ [PutJobTagging](https://docs.aws.amazon.com/goto/boto3/s3control-2018-08-20/PutJobTagging)
+ [UpdateJobPriority](https://docs.aws.amazon.com/goto/boto3/s3control-2018-08-20/UpdateJobPriority)
+ [UpdateJobStatus](https://docs.aws.amazon.com/goto/boto3/s3control-2018-08-20/UpdateJobStatus)
## アクション
### `CreateJob`
次の例は、`CreateJob` を使用する方法を説明しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/scenarios/batch#code-examples)での設定と実行の方法を確認してください。
```
def create_s3_batch_job(self, account_id: str, role_arn: str, manifest_location: str,
report_bucket_name: str) -> str:
"""
Create an S3 batch operation job.
Args:
account_id (str): AWS account ID
role_arn (str): IAM role ARN for batch operations
manifest_location (str): Location of the manifest file
report_bucket_name (str): Bucket for job reports
Returns:
str: Job ID
Raises:
ClientError: If job creation fails
"""
try:
bucket_name = manifest_location.split(':::')[1].split('/')[0]
manifest_key = 'job-manifest.csv'
manifest_obj = self.s3_client.head_object(
Bucket=bucket_name,
Key=manifest_key
)
etag = manifest_obj['ETag'].strip('"')
response = self.s3control_client.create_job(
AccountId=account_id,
Operation={
'S3PutObjectTagging': {
'TagSet': [
{
'Key': 'BatchTag',
'Value': 'BatchValue'
},
]
}
},
Report={
'Bucket': report_bucket_name,
'Format': 'Report_CSV_20180820',
'Enabled': True,
'Prefix': 'batch-op-reports',
'ReportScope': 'AllTasks'
},
Manifest={
'Spec': {
'Format': 'S3BatchOperations_CSV_20180820',
'Fields': ['Bucket', 'Key']
},
'Location': {
'ObjectArn': manifest_location,
'ETag': etag
}
},
Priority=10,
RoleArn=role_arn,
Description='Batch job for tagging objects',
ConfirmationRequired=True
)
job_id = response['JobId']
print(f"The Job id is {job_id}")
return job_id
except ClientError as e:
print(f"Error creating batch job: {e}")
if 'Message' in str(e):
print(f"Detailed error message: {e.response['Message']}")
raise
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス* の「[CreateJob](https://docs.aws.amazon.com/goto/boto3/s3control-2018-08-20/CreateJob)」を参照してください。
### `DeleteJobTagging`
次の例は、`DeleteJobTagging` を使用する方法を説明しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/scenarios/batch#code-examples)での設定と実行の方法を確認してください。
```
def delete_job_tags(self, job_id: str, account_id: str) -> None:
"""
Delete all tags from a batch job.
Args:
job_id (str): ID of the batch job
account_id (str): AWS account ID
"""
try:
self.s3control_client.delete_job_tagging(
AccountId=account_id,
JobId=job_id
)
print(f"You have successfully deleted {job_id} tagging.")
except ClientError as e:
print(f"Error deleting job tags: {e}")
raise
```
+ API の詳細については、 *AWS SDK for Python (Boto3) API リファレンス*の[DeleteJobTagging](https://docs.aws.amazon.com/goto/boto3/s3control-2018-08-20/DeleteJobTagging)」を参照してください。
### `DescribeJob`
次の例は、`DescribeJob` を使用する方法を説明しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/scenarios/batch#code-examples)での設定と実行の方法を確認してください。
```
def describe_job_details(self, job_id: str, account_id: str) -> None:
"""
Describe detailed information about a batch job.
Args:
job_id (str): ID of the batch job
account_id (str): AWS account ID
"""
try:
response = self.s3control_client.describe_job(
AccountId=account_id,
JobId=job_id
)
job = response['Job']
print(f"Job ID: {job['JobId']}")
print(f"Description: {job.get('Description', 'N/A')}")
print(f"Status: {job['Status']}")
print(f"Role ARN: {job['RoleArn']}")
print(f"Priority: {job['Priority']}")
if 'ProgressSummary' in job:
progress = job['ProgressSummary']
print(f"Progress Summary: Total={progress.get('TotalNumberOfTasks', 0)}, "
f"Succeeded={progress.get('NumberOfTasksSucceeded', 0)}, "
f"Failed={progress.get('NumberOfTasksFailed', 0)}")
except ClientError as e:
print(f"Error describing job: {e}")
raise
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[DescribeJob](https://docs.aws.amazon.com/goto/boto3/s3control-2018-08-20/DescribeJob)」を参照してください。
### `GetJobTagging`
次の例は、`GetJobTagging` を使用する方法を説明しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/scenarios/batch#code-examples)での設定と実行の方法を確認してください。
```
def get_job_tags(self, job_id: str, account_id: str) -> None:
"""
Get tags associated with a batch job.
Args:
job_id (str): ID of the batch job
account_id (str): AWS account ID
"""
try:
response = self.s3control_client.get_job_tagging(
AccountId=account_id,
JobId=job_id
)
tags = response.get('Tags', [])
if tags:
print(f"Tags for job {job_id}:")
for tag in tags:
print(f" {tag['Key']}: {tag['Value']}")
else:
print(f"No tags found for job ID: {job_id}")
except ClientError as e:
print(f"Error getting job tags: {e}")
raise
```
+ API の詳細については、 *AWS SDK for Python (Boto3) API リファレンスの*「[GetJobTagging](https://docs.aws.amazon.com/goto/boto3/s3control-2018-08-20/GetJobTagging)」を参照してください。
### `PutJobTagging`
次の例は、`PutJobTagging` を使用する方法を説明しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/scenarios/batch#code-examples)での設定と実行の方法を確認してください。
```
def put_job_tags(self, job_id: str, account_id: str) -> None:
"""
Add tags to a batch job.
Args:
job_id (str): ID of the batch job
account_id (str): AWS account ID
"""
try:
self.s3control_client.put_job_tagging(
AccountId=account_id,
JobId=job_id,
Tags=[
{'Key': 'Environment', 'Value': 'Development'},
{'Key': 'Team', 'Value': 'DataProcessing'}
]
)
print(f"Additional tags were added to job {job_id}")
except ClientError as e:
print(f"Error adding job tags: {e}")
raise
```
+ API の詳細については、 *AWS SDK for Python (Boto3) API リファレンスの*「[PutJobTagging](https://docs.aws.amazon.com/goto/boto3/s3control-2018-08-20/PutJobTagging)」を参照してください。
### `UpdateJobPriority`
次の例は、`UpdateJobPriority` を使用する方法を説明しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/scenarios/batch#code-examples)での設定と実行の方法を確認してください。
```
def update_job_priority(self, job_id: str, account_id: str) -> None:
"""
Update the priority of a batch job and start it.
Args:
job_id (str): ID of the batch job
account_id (str): AWS account ID
"""
try:
response = self.s3control_client.describe_job(
AccountId=account_id,
JobId=job_id
)
current_status = response['Job']['Status']
print(f"Current job status: {current_status}")
if current_status in ['Ready', 'Suspended']:
self.s3control_client.update_job_priority(
AccountId=account_id,
JobId=job_id,
Priority=60
)
print("The job priority was updated")
try:
self.s3control_client.update_job_status(
AccountId=account_id,
JobId=job_id,
RequestedJobStatus='Ready'
)
print("Job activated successfully")
except ClientError as activation_error:
print(f"Note: Could not activate job automatically: {activation_error}")
print("Job priority was updated successfully. Job may need manual activation in the console.")
elif current_status in ['Active', 'Completing', 'Complete']:
print(f"Job is in '{current_status}' state - priority cannot be updated")
if current_status == 'Completing':
print("Job is finishing up and will complete soon.")
elif current_status == 'Complete':
print("Job has already completed successfully.")
else:
print("Job is currently running.")
else:
print(f"Job is in '{current_status}' state - priority update not allowed")
except ClientError as e:
print(f"Error updating job priority: {e}")
print("Continuing with the scenario...")
return
```
+ API の詳細については、 *AWS SDK for Python (Boto3) API リファレンスの*[UpdateJobPriority](https://docs.aws.amazon.com/goto/boto3/s3control-2018-08-20/UpdateJobPriority)」を参照してください。
### `UpdateJobStatus`
次の例は、`UpdateJobStatus` を使用する方法を説明しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/scenarios/batch#code-examples)での設定と実行の方法を確認してください。
```
def cancel_job(self, job_id: str, account_id: str) -> None:
"""
Cancel an S3 batch job.
Args:
job_id (str): ID of the batch job
account_id (str): AWS account ID
"""
try:
response = self.s3control_client.describe_job(
AccountId=account_id,
JobId=job_id
)
current_status = response['Job']['Status']
print(f"Current job status: {current_status}")
if current_status in ['Ready', 'Suspended', 'Active']:
self.s3control_client.update_job_status(
AccountId=account_id,
JobId=job_id,
RequestedJobStatus='Cancelled'
)
print(f"Job {job_id} was successfully canceled.")
elif current_status in ['Completing', 'Complete']:
print(f"Job is in '{current_status}' state - cannot be cancelled")
if current_status == 'Completing':
print("Job is finishing up and will complete soon.")
elif current_status == 'Complete':
print("Job has already completed successfully.")
else:
print(f"Job is in '{current_status}' state - cancel not allowed")
except ClientError as e:
print(f"Error canceling job: {e}")
raise
```
+ API の詳細については、 *AWS SDK for Python (Boto3) API リファレンスの*[UpdateJobStatus](https://docs.aws.amazon.com/goto/boto3/s3control-2018-08-20/UpdateJobStatus)」を参照してください。
# SDK for Python (Boto3) を使用した S3 ディレクトリバケットの例
次のコード例は、S3 ディレクトリバケット AWS SDK for Python (Boto3) で を使用してアクションを実行し、一般的なシナリオを実装する方法を示しています。
*基本* は、重要なオペレーションをサービス内で実行する方法を示すコード例です。
*アクション*はより大きなプログラムからのコードの抜粋であり、コンテキスト内で実行する必要があります。アクションは個々のサービス機能を呼び出す方法を示していますが、コンテキスト内のアクションは、関連するシナリオで確認できます。
各例には、完全なソースコードへのリンクが含まれており、そこからコードの設定方法と実行方法に関する手順を確認できます。
**Topics**
+ [基本](#basics)
+ [アクション](#actions)
## 基本
### 基本を学ぶ
次のコード例は、以下の操作方法を示しています。
+ VPC と VPC エンドポイントをセットアップします。
+ S3 ディレクトリバケットと S3 Express One Zone ストレージクラスを操作するようにポリシー、ロール、ユーザーを設定します。
+ 2 つの S3 クライアントを作成します。
+ バケットを 2 つ作成します。
+ オブジェクトを作成し、それをコピーします。
+ パフォーマンスの違いを示します。
+ 辞書順の違いを示すために、バケットをデータを追加します。
+ ユーザーにリソースをクリーンアップするかどうかを確認するプロンプトを表示します。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3-directory-buckets/#code-examples)での設定と実行の方法を確認してください。
Amazon S3 ディレクトリバケットと S3 Express One Zone の基本を示すシナリオを実行します。
```
class S3ExpressScenario:
"""Runs an interactive scenario that shows how to get started with S3 Express."""
def __init__(
self,
cloud_formation_resource: ServiceResource,
ec2_client: client,
iam_client: client,
):
self.cloud_formation_resource = cloud_formation_resource
self.ec2_client = ec2_client
self.iam_client = iam_client
self.region = ec2_client.meta.region_name
self.stack = None
self.vpc_id = None
self.vpc_endpoint_id = None
self.regular_bucket_name = None
self.directory_bucket_name = None
self.s3_express_wrapper = None
self.s3_regular_wrapper = None
def s3_express_scenario(self):
"""
Runs the scenario.
"""
print("")
print_dashes()
print("Welcome to the Amazon S3 Express Basics demo using Python (Boto 3)!")
print_dashes()
print(
"""
Let's get started! First, please note that S3 Express One Zone works best when working within the AWS infrastructure,
specifically when working in the same Availability Zone. To see the best results in this example and when you implement
Directory buckets into your infrastructure, it is best to put your compute resources in the same AZ as your Directory
bucket.
"""
)
press_enter_to_continue()
# Create an optional VPC and create 2 IAM users.
express_user_name, regular_user_name = self.create_vpc_and_users()
# Set up two S3 clients, one regular and one express, and two buckets, one regular and one express.
self.setup_clients_and_buckets(express_user_name, regular_user_name)
# Create an S3 session for the express S3 client and add objects to the buckets.
bucket_object = self.create_session_and_add_objects()
# Demonstrate performance differences between regular and express buckets.
self.demonstrate_performance(bucket_object)
# Populate the buckets to show the lexicographical difference between regular and express buckets.
self.show_lexicographical_differences(bucket_object)
print("")
print("That's it for our tour of the basic operations for S3 Express One Zone.")
if q.ask(
"Would you like to delete all the resources created during this demo (y/n)? ",
q.is_yesno,
):
self.cleanup()
def create_vpc_and_users(self) -> None:
"""
Optionally create a VPC.
Create two IAM users, one with S3 Express One Zone permissions and one without.
"""
# Configure a gateway VPC endpoint. This is the recommended method to allow S3 Express One Zone traffic without
# the need to pass through an internet gateway or NAT device.
print(
"""
1. First, we'll set up a new VPC and VPC Endpoint if this program is running in an EC2 instance in the same AZ as your
Directory buckets will be. Are you running this in an EC2 instance located in the same AZ as your intended Directory buckets?
"""
)
if q.ask("Do you want to setup a VPC Endpoint? (y/n) ", q.is_yesno):
print(
"Great! Let's set up a VPC, retrieve the Route Table from it, and create a VPC Endpoint to connect the S3 Client to."
)
self.setup_vpc()
press_enter_to_continue()
else:
print("Skipping the VPC setup. Don't forget to use this in production!")
print(
"""
2. Policies, users, and roles with CDK.
Now, we'll set up some policies, roles, and a user. This user will only have permissions to do S3 Express One Zone actions.
"""
)
press_enter_to_continue()
stack_name = f"cfn-stack-s3-express-basics--{uuid.uuid4()}"
template_as_string = S3ExpressScenario.get_template_as_string()
self.stack = self.deploy_cloudformation_stack(stack_name, template_as_string)
regular_user_name = None
express_user_name = None
outputs = self.stack.outputs
for output in outputs:
if output.get("OutputKey") == "RegularUser":
regular_user_name = output.get("OutputValue")
elif output.get("OutputKey") == "ExpressUser":
express_user_name = output.get("OutputValue")
if not regular_user_name or not express_user_name:
error_string = f"""
Failed to retrieve required outputs from CloudFormation stack.
'regular_user_name'={regular_user_name}, 'express_user_name'={express_user_name}
"""
logger.error(error_string)
raise ValueError(error_string)
return express_user_name, regular_user_name
def setup_clients_and_buckets(
self, express_user_name: str, regular_user_name: str
) -> None:
"""
Set up two S3 clients, one regular and one express, and two buckets, one regular and one express.
:param express_user_name: The name of the user with S3 Express permissions.
:param regular_user_name: The name of the user with regular S3 permissions.
"""
regular_credentials = self.create_access_key(regular_user_name)
express_credentials = self.create_access_key(express_user_name)
# 3. Create an additional client using the credentials with S3 Express permissions.
print(
"""
3. Create an additional client using the credentials with S3 Express permissions. This client is created with the
credentials associated with the user account with the S3 Express policy attached, so it can perform S3 Express operations.
"""
)
press_enter_to_continue()
s3_regular_client = self.create_s3__client_with_access_key_credentials(
regular_credentials
)
self.s3_regular_wrapper = S3ExpressWrapper(s3_regular_client)
s3_express_client = self.create_s3__client_with_access_key_credentials(
express_credentials
)
self.s3_express_wrapper = S3ExpressWrapper(s3_express_client)
print(
"""
All the roles and policies were created and attached to the user. Then a new S3 Client were created using
that user's credentials. We can now use this client to make calls to S3 Express operations. Keeping permissions in mind
(and adhering to least-privilege) is crucial to S3 Express.
"""
)
press_enter_to_continue()
# 4. Create two buckets.
print(
"""
3. Create two buckets.
Now we will create a Directory bucket which is the linchpin of the S3 Express One Zone service. Directory buckets
behave in different ways from regular S3 buckets which we will explore here. We'll also create a normal bucket, put
an object into the normal bucket, and copy it over to the Directory bucket.
"""
)
# Create a directory bucket. These are different from normal S3 buckets in subtle ways.
bucket_prefix = q.ask(
"Enter a bucket name prefix that will be used for both buckets: ",
q.re_match(r"[a-z0-9](?:[a-z0-9-\.]*)[a-z0-9]$"),
)
# Some availability zones are not supported for Directory buckets. We'll choose one that is supported.
print(
"Now, let's choose an availability zone for the Directory bucket. We'll choose one that is supported."
)
while True:
availability_zone = self.select_availability_zone_id(self.region)
# Construct the parts of a directory bucket name that is made unique with a UUID string.
directory_bucket_suffix = f"--{availability_zone['ZoneId']}--x-s3"
max_uuid_length = 63 - len(bucket_prefix) - len(directory_bucket_suffix) - 1
bucket_uuid = str(uuid.uuid4()).replace("-", "")[:max_uuid_length]
directory_bucket_name = (
f"{bucket_prefix}-{bucket_uuid}{directory_bucket_suffix}"
)
regular_bucket_name = f"{bucket_prefix}-regular-{bucket_uuid}"
configuration = {
"Bucket": {
"Type": "Directory",
"DataRedundancy": "SingleAvailabilityZone",
},
"Location": {
"Name": availability_zone["ZoneId"],
"Type": "AvailabilityZone",
},
}
press_enter_to_continue()
print(
"Now, let's create the actual Directory bucket, as well as a regular bucket."
)
press_enter_to_continue()
try:
self.s3_express_wrapper.create_bucket(
directory_bucket_name, configuration
)
break
except ClientError as client_error:
if client_error.response["Error"]["Code"] == "InvalidBucketName":
print(
f"Bucket '{directory_bucket_name}' is invalid. This may be because of selected availability zone."
)
if q.ask(
"Would you like to select a different availability zone? ",
q.is_yesno,
):
continue
else:
raise
else:
raise
print(f"Created directory bucket, '{directory_bucket_name}'")
self.directory_bucket_name = directory_bucket_name
self.s3_regular_wrapper.create_bucket(regular_bucket_name)
print(f"Created regular bucket, '{regular_bucket_name}'")
self.regular_bucket_name = regular_bucket_name
print("Great! Both buckets were created.")
press_enter_to_continue()
def create_session_and_add_objects(self) -> None:
"""
Create a session for the express S3 client and add objects to the buckets.
"""
print(
"""
5. Create an object and copy it over.
We'll create a basic object consisting of some text and upload it to the normal bucket. Next we'll copy the object
into the Directory bucket using the regular client. This works fine because copy operations are not restricted for
Directory buckets.
"""
)
press_enter_to_continue()
bucket_object = "basic-text-object"
self.s3_regular_wrapper.put_object(
self.regular_bucket_name, bucket_object, "Look Ma, I'm a bucket!"
)
self.s3_express_wrapper.create_session(self.directory_bucket_name)
self.s3_express_wrapper.copy_object(
self.regular_bucket_name,
bucket_object,
self.directory_bucket_name,
bucket_object,
)
print(
"""
It worked! It's important to remember the user permissions when interacting with Directory buckets. Instead of validating
permissions on every call as normal buckets do, Directory buckets utilize the user credentials and session token to validate.
This allows for much faster connection speeds on every call. For single calls, this is low, but for many concurrent calls
this adds up to a lot of time saved.
"""
)
press_enter_to_continue()
return bucket_object
def demonstrate_performance(self, bucket_object: str) -> None:
"""
Demonstrate performance differences between regular and Directory buckets.
:param bucket_object: The name of the object to download from each bucket.
"""
print("")
print("6. Demonstrate performance difference.")
print(
"""
Now, let's do a performance test. We'll download the same object from each bucket 'downloads' times
and compare the total time needed. Note: the performance difference will be much more pronounced if this
example is run in an EC2 instance in the same Availability Zone as the bucket.
"""
)
downloads = 1000
print(
f"The number of downloads of the same object for this example is set at {downloads}."
)
if q.ask("Would you like to download a different number? (y/n) ", q.is_yesno):
max_downloads = 1000000
downloads = q.ask(
f"Enter a number between 1 and {max_downloads} for the number of downloads: ",
q.is_int,
q.in_range(1, max_downloads),
)
# Download the object 'downloads' times from each bucket and time it to demonstrate the speed difference.
print("Downloading from the Directory bucket.")
directory_time_start = time.time_ns()
for index in range(downloads):
if index % 10 == 0:
print(f"Download {index} of {downloads}")
self.s3_express_wrapper.get_object(
self.directory_bucket_name, bucket_object
)
directory_time_difference = time.time_ns() - directory_time_start
print("Downloading from the normal bucket.")
normal_time_start = time.time_ns()
for index in range(downloads):
if index % 10 == 0:
print(f"Download {index} of {downloads}")
self.s3_regular_wrapper.get_object(self.regular_bucket_name, bucket_object)
normal_time_difference = time.time_ns() - normal_time_start
print(
f"The directory bucket took {directory_time_difference} nanoseconds, while the normal bucket took {normal_time_difference}."
)
difference = normal_time_difference - directory_time_difference
print(f"That's a difference of {difference} nanoseconds, or")
print(f"{(difference) / 1000000000} seconds.")
if difference < 0:
print(
"The directory buckets were slower. This can happen if you are not running on the cloud within a vpc."
)
press_enter_to_continue()
def show_lexicographical_differences(self, bucket_object: str) -> None:
"""
Show the lexicographical difference between Directory buckets and regular buckets.
This is done by creating a few objects in each bucket and listing them to show the difference.
:param bucket_object: The object to use for the listing operations.
"""
print(
"""
7. Populate the buckets to show the lexicographical difference.
Now let's explore how Directory buckets store objects in a different manner to regular buckets. The key is in the name
"Directory". Where regular buckets store their key/value pairs in a flat manner, Directory buckets use actual
directories/folders. This allows for more rapid indexing, traversing, and therefore retrieval times! The more segmented
your bucket is, with lots of directories, sub-directories, and objects, the more efficient it becomes. This structural
difference also causes ListObjects to behave differently, which can cause unexpected results. Let's add a few more
objects with layered directories to see how the output of ListObjects changes.
"""
)
press_enter_to_continue()
# Populate a few more files in each bucket so that we can use ListObjects and show the difference.
other_object = f"other/{bucket_object}"
alt_object = f"alt/{bucket_object}"
other_alt_object = f"other/alt/{bucket_object}"
self.s3_regular_wrapper.put_object(self.regular_bucket_name, other_object, "")
self.s3_express_wrapper.put_object(self.directory_bucket_name, other_object, "")
self.s3_regular_wrapper.put_object(self.regular_bucket_name, alt_object, "")
self.s3_express_wrapper.put_object(self.directory_bucket_name, alt_object, "")
self.s3_regular_wrapper.put_object(
self.regular_bucket_name, other_alt_object, ""
)
self.s3_express_wrapper.put_object(
self.directory_bucket_name, other_alt_object, ""
)
directory_bucket_objects = self.s3_express_wrapper.list_objects(
self.directory_bucket_name
)
regular_bucket_objects = self.s3_regular_wrapper.list_objects(
self.regular_bucket_name
)
print("Directory bucket content")
for bucket_object in directory_bucket_objects:
print(f" {bucket_object['Key']}")
print("Normal bucket content")
for bucket_object in regular_bucket_objects:
print(f" {bucket_object['Key']}")
print(
"""
Notice how the normal bucket lists objects in lexicographical order, while the directory bucket does not. This is
because the normal bucket considers the whole "key" to be the object identifier, while the directory bucket actually
creates directories and uses the object "key" as a path to the object.
"""
)
press_enter_to_continue()
def cleanup(self) -> None:
"""
Delete resources created by this scenario.
"""
if self.directory_bucket_name is not None:
self.s3_express_wrapper.delete_bucket_and_objects(
self.directory_bucket_name
)
print(f"Deleted directory bucket, '{self.directory_bucket_name}'")
self.directory_bucket_name = None
if self.regular_bucket_name is not None:
self.s3_regular_wrapper.delete_bucket_and_objects(self.regular_bucket_name)
print(f"Deleted regular bucket, '{self.regular_bucket_name}'")
self.regular_bucket_name = None
if self.stack is not None:
self.destroy_cloudformation_stack(self.stack)
self.stack = None
self.tear_done_vpc()
def create_access_key(self, user_name: str) -> dict[str, any]:
"""
Creates an access key for the user.
:param user_name: The name of the user.
:return: The access key for the user.
"""
try:
access_key = self.iam_client.create_access_key(UserName=user_name)
return access_key["AccessKey"]
except ClientError as client_error:
logging.error(
"Couldn't create the access key. Here's why: %s",
client_error.response["Error"]["Message"],
)
raise
def create_s3__client_with_access_key_credentials(
self, access_key: dict[str, any]
) -> client:
"""
Creates an S3 client with access key credentials.
:param access_key: The access key for the user.
:return: The S3 Express One Zone client.
"""
try:
s3_express_client = boto3.client(
"s3",
aws_access_key_id=access_key["AccessKeyId"],
aws_secret_access_key=access_key["SecretAccessKey"],
region_name=self.region,
)
return s3_express_client
except ClientError as client_error:
logging.error(
"Couldn't create the S3 Express One Zone client. Here's why: %s",
client_error.response["Error"]["Message"],
)
raise
def select_availability_zone_id(self, region: str) -> dict[str, any]:
"""
Selects an availability zone.
:param region: The region to select the availability zone from.
:return: The availability zone dictionary.
"""
try:
response = self.ec2_client.describe_availability_zones(
Filters=[{"Name": "region-name", "Values": [region]}]
)
availability_zones = response["AvailabilityZones"]
zone_names = [zone["ZoneName"] for zone in availability_zones]
index = q.choose("Select an availability zone: ", zone_names)
return availability_zones[index]
except ClientError as client_error:
logging.error(
"Couldn't describe availability zones. Here's why: %s",
client_error.response["Error"]["Message"],
)
raise
def deploy_cloudformation_stack(
self, stack_name: str, cfn_template: str
) -> ServiceResource:
"""
Deploys prerequisite resources used by the scenario. The resources are
defined in the associated `cfn_template.yaml` AWS CloudFormation script and are deployed
as a CloudFormation stack, so they can be easily managed and destroyed.
:param stack_name: The name of the CloudFormation stack.
:param cfn_template: The CloudFormation template as a string.
:return: The CloudFormation stack resource.
"""
print(f"Deploying CloudFormation stack: {stack_name}.")
stack = self.cloud_formation_resource.create_stack(
StackName=stack_name,
TemplateBody=cfn_template,
Capabilities=["CAPABILITY_NAMED_IAM"],
)
print(f"CloudFormation stack creation started: {stack_name}")
print("Waiting for CloudFormation stack creation to complete...")
waiter = self.cloud_formation_resource.meta.client.get_waiter(
"stack_create_complete"
)
waiter.wait(StackName=stack.name)
stack.load()
print("CloudFormation stack creation complete.")
return stack
def destroy_cloudformation_stack(self, stack: ServiceResource) -> None:
"""
Destroys the resources managed by the CloudFormation stack, and the CloudFormation
stack itself.
:param stack: The CloudFormation stack that manages the example resources.
"""
try:
print(
f"CloudFormation stack '{stack.name}' is being deleted. This may take a few minutes."
)
stack.delete()
waiter = self.cloud_formation_resource.meta.client.get_waiter(
"stack_delete_complete"
)
waiter.wait(StackName=stack.name)
print(f"CloudFormation stack '{stack.name}' has been deleted.")
except ClientError as client_error:
logging.error(
"Couldn't delete the CloudFormation stack. Here's why: %s",
client_error.response["Error"]["Message"],
)
@staticmethod
def get_template_as_string() -> str:
"""
Returns a string containing this scenario's CloudFormation template.
"""
script_directory = os.path.dirname(os.path.abspath(__file__))
template_file_path = os.path.join(script_directory, "s3_express_template.yaml")
file = open(template_file_path, "r")
return file.read()
def setup_vpc(self):
cidr = "10.0.0.0/16"
try:
response = self.ec2_client.create_vpc(CidrBlock=cidr)
self.vpc_id = response["Vpc"]["VpcId"]
waiter = self.ec2_client.get_waiter("vpc_available")
waiter.wait(VpcIds=[self.vpc_id])
print(f"Created vpc {self.vpc_id}")
except ClientError as client_error:
logging.error(
"Couldn't create the vpc. Here's why: %s",
client_error.response["Error"]["Message"],
)
raise
try:
response = self.ec2_client.describe_route_tables(
Filters=[{"Name": "vpc-id", "Values": [self.vpc_id]}]
)
route_table_id = response["RouteTables"][0]["RouteTableId"]
service_name = f"com.amazonaws.{self.ec2_client.meta.region_name}.s3express"
response = self.ec2_client.create_vpc_endpoint(
VpcId=self.vpc_id,
RouteTableIds=[route_table_id],
ServiceName=service_name,
)
self.vpc_endpoint_id = response["VpcEndpoint"]["VpcEndpointId"]
print(f"Created vpc endpoint {self.vpc_endpoint_id}")
except ClientError as client_error:
logging.error(
"Couldn't create the vpc endpoint. Here's why: %s",
client_error.response["Error"]["Message"],
)
raise
def tear_done_vpc(self) -> None:
if self.vpc_endpoint_id is not None:
try:
self.ec2_client.delete_vpc_endpoints(
VpcEndpointIds=[self.vpc_endpoint_id]
)
print(f"Deleted vpc endpoint {self.vpc_endpoint_id}.")
self.vpc_endpoint_id = None
except ClientError as client_error:
logging.error(
"Couldn't delete the vpc endpoint %s. Here's why: %s",
self.vpc_endpoint_id,
client_error.response["Error"]["Message"],
)
if self.vpc_id is not None:
try:
self.ec2_client.delete_vpc(VpcId=self.vpc_id)
print(f"Deleted vpc {self.vpc_id}")
self.vpc_id = None
except ClientError as client_error:
logging.error(
"Couldn't delete the vpc %s. Here's why: %s",
self.vpc_id,
client_error.response["Error"]["Message"],
)
```
Amazon S3 Express SDK 関数のラッパークラス。
```
class S3ExpressWrapper:
"""Encapsulates Amazon S3 Express One Zone actions using the client interface."""
def __init__(self, s3_client: Any) -> None:
"""
Initializes the S3ExpressWrapper with an S3 client.
:param s3_client: A Boto3 Amazon S3 client. This client provides low-level
access to AWS S3 services.
"""
self.s3_client = s3_client
@classmethod
def from_client(cls) -> "S3ExpressWrapper":
"""
Creates an S3ExpressWrapper instance with a default s3 client.
:return: An instance of S3ExpressWrapper initialized with the default S3 client.
"""
s3_client = boto3.client("s3")
return cls(s3_client)
def create_bucket(
self, bucket_name: str, bucket_configuration: dict[str, any] = None
) -> None:
"""
Creates a bucket.
:param bucket_name: The name of the bucket.
:param bucket_configuration: The optional configuration for the bucket.
"""
try:
params = {"Bucket": bucket_name}
if bucket_configuration:
params["CreateBucketConfiguration"] = bucket_configuration
self.s3_client.create_bucket(**params)
except ClientError as client_error:
# Do not log InvalidBucketName error because it is logged elsewhere.
if client_error.response["Error"]["Code"] != "InvalidBucketName":
logging.error(
"Couldn't create the bucket %s. Here's why: %s",
bucket_name,
client_error.response["Error"]["Message"],
)
raise
def delete_bucket_and_objects(self, bucket_name: str) -> None:
"""
Deletes a bucket and its objects.
:param bucket_name: The name of the bucket.
"""
try:
# Delete the objects in the bucket first. This is required for a bucket to be deleted.
paginator = self.s3_client.get_paginator("list_objects_v2")
page_iterator = paginator.paginate(Bucket=bucket_name)
for page in page_iterator:
if "Contents" in page:
delete_keys = {
"Objects": [{"Key": obj["Key"]} for obj in page["Contents"]]
}
response = self.s3_client.delete_objects(
Bucket=bucket_name, Delete=delete_keys
)
if "Errors" in response:
for error in response["Errors"]:
logging.error(
"Couldn't delete object %s. Here's why: %s",
error["Key"],
error["Message"],
)
self.s3_client.delete_bucket(Bucket=bucket_name)
except ClientError as client_error:
logging.error(
"Couldn't delete the bucket %s. Here's why: %s",
bucket_name,
client_error.response["Error"]["Message"],
)
def put_object(self, bucket_name: str, object_key: str, content: str) -> None:
"""
Puts an object into a bucket.
:param bucket_name: The name of the bucket.
:param object_key: The key of the object.
:param content: The content of the object.
"""
try:
self.s3_client.put_object(Body=content, Bucket=bucket_name, Key=object_key)
except ClientError as client_error:
logging.error(
"Couldn't put the object %s into bucket %s. Here's why: %s",
object_key,
bucket_name,
client_error.response["Error"]["Message"],
)
raise
def list_objects(self, bucket: str) -> list[str]:
"""
Lists objects in a bucket.
:param bucket: The name of the bucket.
:return: The list of objects in the bucket.
"""
try:
response = self.s3_client.list_objects_v2(Bucket=bucket)
return response.get("Contents", [])
except ClientError as client_error:
logging.error(
"Couldn't list objects in bucket %s. Here's why: %s",
bucket,
client_error.response["Error"]["Message"],
)
raise
def copy_object(
self,
source_bucket: str,
source_key: str,
destination_bucket: str,
destination_key: str,
) -> None:
"""
Copies an object from one bucket to another.
:param source_bucket: The source bucket.
:param source_key: The source key.
:param destination_bucket: The destination bucket.
:param destination_key: The destination key.
:return: None
"""
try:
self.s3_client.copy_object(
CopySource={"Bucket": source_bucket, "Key": source_key},
Bucket=destination_bucket,
Key=destination_key,
)
except ClientError as client_error:
logging.error(
"Couldn't copy object %s from bucket %s to bucket %s. Here's why: %s",
source_key,
source_bucket,
destination_bucket,
client_error.response["Error"]["Message"],
)
raise
def create_session(self, bucket_name: str) -> None:
"""
Creates an express session.
:param bucket_name: The name of the bucket.
"""
try:
self.s3_client.create_session(Bucket=bucket_name)
except ClientError as client_error:
logging.error(
"Couldn't create the express session for bucket %s. Here's why: %s",
bucket_name,
client_error.response["Error"]["Message"],
)
raise
def get_object(self, bucket_name: str, object_key: str) -> None:
"""
Gets an object from a bucket.
:param bucket_name: The name of the bucket.
:param object_key: The key of the object.
"""
try:
self.s3_client.get_object(Bucket=bucket_name, Key=object_key)
except ClientError as client_error:
logging.error(
"Couldn't get the object %s from bucket %s. Here's why: %s",
object_key,
bucket_name,
client_error.response["Error"]["Message"],
)
raise
```
+ API の詳細については、「**AWS SDK for Python (Boto3) API リファレンス」の以下のトピックを参照してください。
+ [CopyObject](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/CopyObject)
+ [CreateBucket](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/CreateBucket)
+ [DeleteBucket](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/DeleteBucket)
+ [DeleteObject](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/DeleteObject)
+ [GetObject](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/GetObject)
+ [ListObjects](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/ListObjects)
+ [PutObject](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/PutObject)
## アクション
### `CreateSession`
次のコード例は、`CreateSession` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3-directory-buckets#code-examples)での設定と実行の方法を確認してください。
```
class S3ExpressWrapper:
"""Encapsulates Amazon S3 Express One Zone actions using the client interface."""
def __init__(self, s3_client: Any) -> None:
"""
Initializes the S3ExpressWrapper with an S3 client.
:param s3_client: A Boto3 Amazon S3 client. This client provides low-level
access to AWS S3 services.
"""
self.s3_client = s3_client
@classmethod
def from_client(cls) -> "S3ExpressWrapper":
"""
Creates an S3ExpressWrapper instance with a default s3 client.
:return: An instance of S3ExpressWrapper initialized with the default S3 client.
"""
s3_client = boto3.client("s3")
return cls(s3_client)
def create_session(self, bucket_name: str) -> None:
"""
Creates an express session.
:param bucket_name: The name of the bucket.
"""
try:
self.s3_client.create_session(Bucket=bucket_name)
except ClientError as client_error:
logging.error(
"Couldn't create the express session for bucket %s. Here's why: %s",
bucket_name,
client_error.response["Error"]["Message"],
)
raise
```
+ API の詳細については、AWS SDK for Python (Boto3) API リファレンスの「[CreateSession](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/CreateSession)」を参照してください。**
# SDK for Python (Boto3) を使用した Secrets Manager の例
次のコード例は、Secrets Manager AWS SDK for Python (Boto3) で を使用してアクションを実行し、一般的なシナリオを実装する方法を示しています。
*アクション*はより大きなプログラムからのコードの抜粋であり、コンテキスト内で実行する必要があります。アクションは個々のサービス機能を呼び出す方法を示していますが、コンテキスト内のアクションは、関連するシナリオで確認できます。
*シナリオ*は、1 つのサービス内から、または他の AWS のサービスと組み合わせて複数の関数を呼び出し、特定のタスクを実行する方法を示すコード例です。
各例には完全なソースコードへのリンクが含まれており、コードの設定方法と実行方法に関する手順を確認できます。
**Topics**
+ [アクション](#actions)
+ [シナリオ](#scenarios)
## アクション
### `BatchGetSecretValue`
次のコード例は、`BatchGetSecretValue` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/secretsmanager#code-examples)での設定と実行の方法を確認してください。
```
class BatchGetSecretsWrapper:
def __init__(self, secretsmanager_client):
self.client = secretsmanager_client
def batch_get_secrets(self, filter_name):
"""
Retrieve multiple secrets from AWS Secrets Manager using the batch_get_secret_value API.
This function assumes the stack mentioned in the source code README has been successfully deployed.
This stack includes 7 secrets, all of which have names beginning with "mySecret".
:param filter_name: The full or partial name of secrets to be fetched.
:type filter_name: str
"""
try:
secrets = []
response = self.client.batch_get_secret_value(
Filters=[{"Key": "name", "Values": [f"{filter_name}"]}]
)
for secret in response["SecretValues"]:
secrets.append(json.loads(secret["SecretString"]))
if secrets:
logger.info("Secrets retrieved successfully.")
else:
logger.info("Zero secrets returned without error.")
return secrets
except self.client.exceptions.ResourceNotFoundException:
msg = f"One or more requested secrets were not found with filter: {filter_name}"
logger.info(msg)
return msg
except Exception as e:
logger.error(f"An unknown error occurred:\n{str(e)}.")
raise
```
+ API の詳細については、「AWS SDK for Python (Boto3) API リファレンス」の「[BatchGetSecretValue](https://docs.aws.amazon.com/goto/boto3/secretsmanager-2017-10-17/BatchGetSecretValue)」を参照してください。**
### `GetSecretValue`
次のコード例は、`GetSecretValue` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/secretsmanager#code-examples)での設定と実行の方法を確認してください。
```
class GetSecretWrapper:
def __init__(self, secretsmanager_client):
self.client = secretsmanager_client
def get_secret(self, secret_name):
"""
Retrieve individual secrets from AWS Secrets Manager using the get_secret_value API.
This function assumes the stack mentioned in the source code README has been successfully deployed.
This stack includes 7 secrets, all of which have names beginning with "mySecret".
:param secret_name: The name of the secret fetched.
:type secret_name: str
"""
try:
get_secret_value_response = self.client.get_secret_value(
SecretId=secret_name
)
logging.info("Secret retrieved successfully.")
return get_secret_value_response["SecretString"]
except self.client.exceptions.ResourceNotFoundException:
msg = f"The requested secret {secret_name} was not found."
logger.info(msg)
return msg
except Exception as e:
logger.error(f"An unknown error occurred: {str(e)}.")
raise
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[GetSecretValue](https://docs.aws.amazon.com/goto/boto3/secretsmanager-2017-10-17/GetSecretValue)」を参照してください。
## シナリオ
### 貸出ライブラリ REST API を作成する
以下のコード例は、Amazon Aurora データベースでバックアップされた REST API を使用して、常連客が書籍の貸出と返却できる貸出ライブラリを作成する方法を示しています。
**SDK for Python (Boto3)**
Amazon Relational Database Service (Amazon RDS) API と AWS Chalice AWS SDK for Python (Boto3) で を使用して、Amazon Aurora データベースにバックアップされた REST API を作成する方法を示します。Web サービスは完全にサーバーレスであり、常連客が本を借りたり返却したりできるシンプルな貸し出しライブラリを表しています。以下ではその方法を説明しています。
+ サーバーレス Aurora データベースクラスターを作成および管理します。
+ AWS Secrets Manager を使用してデータベース認証情報を管理します。
+ Amazon RDS を使用してデータをデータベースに出し入れするデータストレージレイヤーを実装します。
+ AWS Chalice を使用して、サーバーレス REST API を Amazon API Gateway および にデプロイします AWS Lambda。
+ リクエストパッケージを使用して、Web サービスにリクエストを送信します。
完全なソースコードとセットアップおよび実行の手順については、[GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/aurora_rest_lending_library) で完全な例を参照してください。
**この例で使用されているサービス**
+ API ゲートウェイ
+ Aurora
+ Lambda
+ Secrets Manager
# SDK for Python (Boto3) を使用する Amazon SES の例
次のコード例は、Amazon SES AWS SDK for Python (Boto3) で を使用してアクションを実行し、一般的なシナリオを実装する方法を示しています。
*アクション*はより大きなプログラムからのコードの抜粋であり、コンテキスト内で実行する必要があります。アクションは個々のサービス機能を呼び出す方法を示していますが、コンテキスト内のアクションは、関連するシナリオで確認できます。
*シナリオ*は、1 つのサービス内から、または他の AWS のサービスと組み合わせて複数の関数を呼び出し、特定のタスクを実行する方法を示すコード例です。
各例には完全なソースコードへのリンクが含まれており、コードの設定方法と実行方法に関する手順を確認できます。
**Topics**
+ [アクション](#actions)
+ [シナリオ](#scenarios)
## アクション
### `CreateReceiptFilter`
次のコード例は、`CreateReceiptFilter` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ses#code-examples)での設定と実行の方法を確認してください。
```
class SesReceiptHandler:
"""Encapsulates Amazon SES receipt handling functions."""
def __init__(self, ses_client, s3_resource):
"""
:param ses_client: A Boto3 Amazon SES client.
:param s3_resource: A Boto3 Amazon S3 resource.
"""
self.ses_client = ses_client
self.s3_resource = s3_resource
def create_receipt_filter(self, filter_name, ip_address_or_range, allow):
"""
Creates a filter that allows or blocks incoming mail from an IP address or
range.
:param filter_name: The name to give the filter.
:param ip_address_or_range: The IP address or range to block or allow.
:param allow: When True, incoming mail is allowed from the specified IP
address or range; otherwise, it is blocked.
"""
try:
policy = "Allow" if allow else "Block"
self.ses_client.create_receipt_filter(
Filter={
"Name": filter_name,
"IpFilter": {"Cidr": ip_address_or_range, "Policy": policy},
}
)
logger.info(
"Created receipt filter %s to %s IP of %s.",
filter_name,
policy,
ip_address_or_range,
)
except ClientError:
logger.exception("Couldn't create receipt filter %s.", filter_name)
raise
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[CreateReceiptFilter](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/CreateReceiptFilter)」を参照してください。
### `CreateReceiptRule`
次のコード例は、`CreateReceiptRule` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ses#code-examples)での設定と実行の方法を確認してください。
Amazon SES が受信 E メールのコピーを配置できる Amazon S3 バケットを作成し、特定の受信者のリストに対して受信 E メールをバケットにコピーするルールを作成します。
```
class SesReceiptHandler:
"""Encapsulates Amazon SES receipt handling functions."""
def __init__(self, ses_client, s3_resource):
"""
:param ses_client: A Boto3 Amazon SES client.
:param s3_resource: A Boto3 Amazon S3 resource.
"""
self.ses_client = ses_client
self.s3_resource = s3_resource
def create_bucket_for_copy(self, bucket_name):
"""
Creates a bucket that can receive copies of emails from Amazon SES. This
includes adding a policy to the bucket that grants Amazon SES permission
to put objects in the bucket.
:param bucket_name: The name of the bucket to create.
:return: The newly created bucket.
"""
allow_ses_put_policy = {
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowSESPut",
"Effect": "Allow",
"Principal": {"Service": "ses.amazonaws.com"},
"Action": "s3:PutObject",
"Resource": f"arn:aws:s3:::{bucket_name}/*",
}
],
}
bucket = None
try:
bucket = self.s3_resource.create_bucket(
Bucket=bucket_name,
CreateBucketConfiguration={
"LocationConstraint": self.s3_resource.meta.client.meta.region_name
},
)
bucket.wait_until_exists()
bucket.Policy().put(Policy=json.dumps(allow_ses_put_policy))
logger.info("Created bucket %s to receive copies of emails.", bucket_name)
except ClientError:
logger.exception("Couldn't create bucket to receive copies of emails.")
if bucket is not None:
bucket.delete()
raise
else:
return bucket
def create_s3_copy_rule(
self, rule_set_name, rule_name, recipients, bucket_name, prefix
):
"""
Creates a rule so that all emails received by the specified recipients are
copied to an Amazon S3 bucket.
:param rule_set_name: The name of a previously created rule set to contain
this rule.
:param rule_name: The name to give the rule.
:param recipients: When an email is received by one of these recipients, it
is copied to the Amazon S3 bucket.
:param bucket_name: The name of the bucket to receive email copies. This
bucket must allow Amazon SES to put objects into it.
:param prefix: An object key prefix to give the emails copied to the bucket.
"""
try:
self.ses_client.create_receipt_rule(
RuleSetName=rule_set_name,
Rule={
"Name": rule_name,
"Enabled": True,
"Recipients": recipients,
"Actions": [
{
"S3Action": {
"BucketName": bucket_name,
"ObjectKeyPrefix": prefix,
}
}
],
},
)
logger.info(
"Created rule %s to copy mail received by %s to bucket %s.",
rule_name,
recipients,
bucket_name,
)
except ClientError:
logger.exception("Couldn't create rule %s.", rule_name)
raise
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[CreateReceiptRule](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/CreateReceiptRule)」を参照してください。
### `CreateReceiptRuleSet`
次のコード例は、`CreateReceiptRuleSet` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ses#code-examples)での設定と実行の方法を確認してください。
```
class SesReceiptHandler:
"""Encapsulates Amazon SES receipt handling functions."""
def __init__(self, ses_client, s3_resource):
"""
:param ses_client: A Boto3 Amazon SES client.
:param s3_resource: A Boto3 Amazon S3 resource.
"""
self.ses_client = ses_client
self.s3_resource = s3_resource
def create_receipt_rule_set(self, rule_set_name):
"""
Creates an empty rule set. Rule sets contain individual rules and can be
used to organize rules.
:param rule_set_name: The name to give the rule set.
"""
try:
self.ses_client.create_receipt_rule_set(RuleSetName=rule_set_name)
logger.info("Created receipt rule set %s.", rule_set_name)
except ClientError:
logger.exception("Couldn't create receipt rule set %s.", rule_set_name)
raise
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[CreateReceiptRuleSet](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/CreateReceiptRuleSet)」を参照してください。
### `CreateTemplate`
次のコード例は、`CreateTemplate` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ses#code-examples)での設定と実行の方法を確認してください。
```
class SesTemplate:
"""Encapsulates Amazon SES template functions."""
def __init__(self, ses_client):
"""
:param ses_client: A Boto3 Amazon SES client.
"""
self.ses_client = ses_client
self.template = None
self.template_tags = set()
def _extract_tags(self, subject, text, html):
"""
Extracts tags from a template as a set of unique values.
:param subject: The subject of the email.
:param text: The text version of the email.
:param html: The html version of the email.
"""
self.template_tags = set(re.findall(TEMPLATE_REGEX, subject + text + html))
logger.info("Extracted template tags: %s", self.template_tags)
def create_template(self, name, subject, text, html):
"""
Creates an email template.
:param name: The name of the template.
:param subject: The subject of the email.
:param text: The plain text version of the email.
:param html: The HTML version of the email.
"""
try:
template = {
"TemplateName": name,
"SubjectPart": subject,
"TextPart": text,
"HtmlPart": html,
}
self.ses_client.create_template(Template=template)
logger.info("Created template %s.", name)
self.template = template
self._extract_tags(subject, text, html)
except ClientError:
logger.exception("Couldn't create template %s.", name)
raise
```
+ API の詳細については、AWS SDK for Python (Boto3) API リファレンスの「[CreateTemplate](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/CreateTemplate)」を参照してください。**
### `DeleteIdentity`
次のコード例は、`DeleteIdentity` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ses#code-examples)での設定と実行の方法を確認してください。
```
class SesIdentity:
"""Encapsulates Amazon SES identity functions."""
def __init__(self, ses_client):
"""
:param ses_client: A Boto3 Amazon SES client.
"""
self.ses_client = ses_client
def delete_identity(self, identity):
"""
Deletes an identity.
:param identity: The identity to remove.
"""
try:
self.ses_client.delete_identity(Identity=identity)
logger.info("Deleted identity %s.", identity)
except ClientError:
logger.exception("Couldn't delete identity %s.", identity)
raise
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[DeleteIdentity](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/DeleteIdentity)」を参照してください。
### `DeleteReceiptFilter`
次のコード例は、`DeleteReceiptFilter` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ses#code-examples)での設定と実行の方法を確認してください。
```
class SesReceiptHandler:
"""Encapsulates Amazon SES receipt handling functions."""
def __init__(self, ses_client, s3_resource):
"""
:param ses_client: A Boto3 Amazon SES client.
:param s3_resource: A Boto3 Amazon S3 resource.
"""
self.ses_client = ses_client
self.s3_resource = s3_resource
def delete_receipt_filter(self, filter_name):
"""
Deletes a receipt filter.
:param filter_name: The name of the filter to delete.
"""
try:
self.ses_client.delete_receipt_filter(FilterName=filter_name)
logger.info("Deleted receipt filter %s.", filter_name)
except ClientError:
logger.exception("Couldn't delete receipt filter %s.", filter_name)
raise
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[DeleteReceiptFilter](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/DeleteReceiptFilter)」を参照してください。
### `DeleteReceiptRule`
次のコード例は、`DeleteReceiptRule` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ses#code-examples)での設定と実行の方法を確認してください。
```
class SesReceiptHandler:
"""Encapsulates Amazon SES receipt handling functions."""
def __init__(self, ses_client, s3_resource):
"""
:param ses_client: A Boto3 Amazon SES client.
:param s3_resource: A Boto3 Amazon S3 resource.
"""
self.ses_client = ses_client
self.s3_resource = s3_resource
def delete_receipt_rule(self, rule_set_name, rule_name):
"""
Deletes a rule.
:param rule_set_name: The rule set that contains the rule to delete.
:param rule_name: The rule to delete.
"""
try:
self.ses_client.delete_receipt_rule(
RuleSetName=rule_set_name, RuleName=rule_name
)
logger.info("Removed rule %s from rule set %s.", rule_name, rule_set_name)
except ClientError:
logger.exception(
"Couldn't remove rule %s from rule set %s.", rule_name, rule_set_name
)
raise
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[DeleteReceiptRule](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/DeleteReceiptRule)」を参照してください。
### `DeleteReceiptRuleSet`
次のコード例は、`DeleteReceiptRuleSet` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ses#code-examples)での設定と実行の方法を確認してください。
```
class SesReceiptHandler:
"""Encapsulates Amazon SES receipt handling functions."""
def __init__(self, ses_client, s3_resource):
"""
:param ses_client: A Boto3 Amazon SES client.
:param s3_resource: A Boto3 Amazon S3 resource.
"""
self.ses_client = ses_client
self.s3_resource = s3_resource
def delete_receipt_rule_set(self, rule_set_name):
"""
Deletes a rule set. When a rule set is deleted, all of the rules it contains
are also deleted.
:param rule_set_name: The name of the rule set to delete.
"""
try:
self.ses_client.delete_receipt_rule_set(RuleSetName=rule_set_name)
logger.info("Deleted rule set %s.", rule_set_name)
except ClientError:
logger.exception("Couldn't delete rule set %s.", rule_set_name)
raise
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[DeleteReceiptRuleSet](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/DeleteReceiptRuleSet)」を参照してください。
### `DeleteTemplate`
次のコード例は、`DeleteTemplate` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ses#code-examples)での設定と実行の方法を確認してください。
```
class SesTemplate:
"""Encapsulates Amazon SES template functions."""
def __init__(self, ses_client):
"""
:param ses_client: A Boto3 Amazon SES client.
"""
self.ses_client = ses_client
self.template = None
self.template_tags = set()
def _extract_tags(self, subject, text, html):
"""
Extracts tags from a template as a set of unique values.
:param subject: The subject of the email.
:param text: The text version of the email.
:param html: The html version of the email.
"""
self.template_tags = set(re.findall(TEMPLATE_REGEX, subject + text + html))
logger.info("Extracted template tags: %s", self.template_tags)
def delete_template(self):
"""
Deletes an email template.
"""
try:
self.ses_client.delete_template(TemplateName=self.template["TemplateName"])
logger.info("Deleted template %s.", self.template["TemplateName"])
self.template = None
self.template_tags = None
except ClientError:
logger.exception(
"Couldn't delete template %s.", self.template["TemplateName"]
)
raise
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[DeleteTemplate](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/DeleteTemplate)」を参照してください。
### `DescribeReceiptRuleSet`
次のコード例は、`DescribeReceiptRuleSet` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ses#code-examples)での設定と実行の方法を確認してください。
```
class SesReceiptHandler:
"""Encapsulates Amazon SES receipt handling functions."""
def __init__(self, ses_client, s3_resource):
"""
:param ses_client: A Boto3 Amazon SES client.
:param s3_resource: A Boto3 Amazon S3 resource.
"""
self.ses_client = ses_client
self.s3_resource = s3_resource
def describe_receipt_rule_set(self, rule_set_name):
"""
Gets data about a rule set.
:param rule_set_name: The name of the rule set to retrieve.
:return: Data about the rule set.
"""
try:
response = self.ses_client.describe_receipt_rule_set(
RuleSetName=rule_set_name
)
logger.info("Got data for rule set %s.", rule_set_name)
except ClientError:
logger.exception("Couldn't get data for rule set %s.", rule_set_name)
raise
else:
return response
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[DescribeReceiptRuleSet](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/DescribeReceiptRuleSet)」を参照してください。
### `GetIdentityVerificationAttributes`
次のコード例は、`GetIdentityVerificationAttributes` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ses#code-examples)での設定と実行の方法を確認してください。
```
class SesIdentity:
"""Encapsulates Amazon SES identity functions."""
def __init__(self, ses_client):
"""
:param ses_client: A Boto3 Amazon SES client.
"""
self.ses_client = ses_client
def get_identity_status(self, identity):
"""
Gets the status of an identity. This can be used to discover whether
an identity has been successfully verified.
:param identity: The identity to query.
:return: The status of the identity.
"""
try:
response = self.ses_client.get_identity_verification_attributes(
Identities=[identity]
)
status = response["VerificationAttributes"].get(
identity, {"VerificationStatus": "NotFound"}
)["VerificationStatus"]
logger.info("Got status of %s for %s.", status, identity)
except ClientError:
logger.exception("Couldn't get status for %s.", identity)
raise
else:
return status
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[GetIdentityVerificationAttributes](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/GetIdentityVerificationAttributes)」を参照してください。
### `GetTemplate`
次のコード例は、`GetTemplate` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ses#code-examples)での設定と実行の方法を確認してください。
```
class SesTemplate:
"""Encapsulates Amazon SES template functions."""
def __init__(self, ses_client):
"""
:param ses_client: A Boto3 Amazon SES client.
"""
self.ses_client = ses_client
self.template = None
self.template_tags = set()
def _extract_tags(self, subject, text, html):
"""
Extracts tags from a template as a set of unique values.
:param subject: The subject of the email.
:param text: The text version of the email.
:param html: The html version of the email.
"""
self.template_tags = set(re.findall(TEMPLATE_REGEX, subject + text + html))
logger.info("Extracted template tags: %s", self.template_tags)
def get_template(self, name):
"""
Gets a previously created email template.
:param name: The name of the template to retrieve.
:return: The retrieved email template.
"""
try:
response = self.ses_client.get_template(TemplateName=name)
self.template = response["Template"]
logger.info("Got template %s.", name)
self._extract_tags(
self.template["SubjectPart"],
self.template["TextPart"],
self.template["HtmlPart"],
)
except ClientError:
logger.exception("Couldn't get template %s.", name)
raise
else:
return self.template
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[GetTemplate](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/GetTemplate)」を参照してください。
### `ListIdentities`
次のコード例は、`ListIdentities` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ses#code-examples)での設定と実行の方法を確認してください。
```
class SesIdentity:
"""Encapsulates Amazon SES identity functions."""
def __init__(self, ses_client):
"""
:param ses_client: A Boto3 Amazon SES client.
"""
self.ses_client = ses_client
def list_identities(self, identity_type, max_items):
"""
Gets the identities of the specified type for the current account.
:param identity_type: The type of identity to retrieve, such as EmailAddress.
:param max_items: The maximum number of identities to retrieve.
:return: The list of retrieved identities.
"""
try:
response = self.ses_client.list_identities(
IdentityType=identity_type, MaxItems=max_items
)
identities = response["Identities"]
logger.info("Got %s identities for the current account.", len(identities))
except ClientError:
logger.exception("Couldn't list identities for the current account.")
raise
else:
return identities
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[ListIdentities](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/ListIdentities)」を参照してください。
### `ListReceiptFilters`
次のコード例は、`ListReceiptFilters` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ses#code-examples)での設定と実行の方法を確認してください。
```
class SesReceiptHandler:
"""Encapsulates Amazon SES receipt handling functions."""
def __init__(self, ses_client, s3_resource):
"""
:param ses_client: A Boto3 Amazon SES client.
:param s3_resource: A Boto3 Amazon S3 resource.
"""
self.ses_client = ses_client
self.s3_resource = s3_resource
def list_receipt_filters(self):
"""
Gets the list of receipt filters for the current account.
:return: The list of receipt filters.
"""
try:
response = self.ses_client.list_receipt_filters()
filters = response["Filters"]
logger.info("Got %s receipt filters.", len(filters))
except ClientError:
logger.exception("Couldn't get receipt filters.")
raise
else:
return filters
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[ListReceiptFilters](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/ListReceiptFilters)」を参照してください。
### `ListTemplates`
次のコード例は、`ListTemplates` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ses#code-examples)での設定と実行の方法を確認してください。
```
class SesTemplate:
"""Encapsulates Amazon SES template functions."""
def __init__(self, ses_client):
"""
:param ses_client: A Boto3 Amazon SES client.
"""
self.ses_client = ses_client
self.template = None
self.template_tags = set()
def _extract_tags(self, subject, text, html):
"""
Extracts tags from a template as a set of unique values.
:param subject: The subject of the email.
:param text: The text version of the email.
:param html: The html version of the email.
"""
self.template_tags = set(re.findall(TEMPLATE_REGEX, subject + text + html))
logger.info("Extracted template tags: %s", self.template_tags)
def list_templates(self):
"""
Gets a list of all email templates for the current account.
:return: The list of retrieved email templates.
"""
try:
response = self.ses_client.list_templates()
templates = response["TemplatesMetadata"]
logger.info("Got %s templates.", len(templates))
except ClientError:
logger.exception("Couldn't get templates.")
raise
else:
return templates
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[ListTemplates](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/ListTemplates)」を参照してください。
### `SendEmail`
次のコード例は、`SendEmail` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ses#code-examples)での設定と実行の方法を確認してください。
```
class SesMailSender:
"""Encapsulates functions to send emails with Amazon SES."""
def __init__(self, ses_client):
"""
:param ses_client: A Boto3 Amazon SES client.
"""
self.ses_client = ses_client
def send_email(self, source, destination, subject, text, html, reply_tos=None):
"""
Sends an email.
Note: If your account is in the Amazon SES sandbox, the source and
destination email accounts must both be verified.
:param source: The source email account.
:param destination: The destination email account.
:param subject: The subject of the email.
:param text: The plain text version of the body of the email.
:param html: The HTML version of the body of the email.
:param reply_tos: Email accounts that will receive a reply if the recipient
replies to the message.
:return: The ID of the message, assigned by Amazon SES.
"""
send_args = {
"Source": source,
"Destination": destination.to_service_format(),
"Message": {
"Subject": {"Data": subject},
"Body": {"Text": {"Data": text}, "Html": {"Data": html}},
},
}
if reply_tos is not None:
send_args["ReplyToAddresses"] = reply_tos
try:
response = self.ses_client.send_email(**send_args)
message_id = response["MessageId"]
logger.info(
"Sent mail %s from %s to %s.", message_id, source, destination.tos
)
except ClientError:
logger.exception(
"Couldn't send mail from %s to %s.", source, destination.tos
)
raise
else:
return message_id
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[SendEmail](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/SendEmail)」を参照してください。
### `SendTemplatedEmail`
次のコード例は、`SendTemplatedEmail` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ses#code-examples)での設定と実行の方法を確認してください。
```
class SesMailSender:
"""Encapsulates functions to send emails with Amazon SES."""
def __init__(self, ses_client):
"""
:param ses_client: A Boto3 Amazon SES client.
"""
self.ses_client = ses_client
def send_templated_email(
self, source, destination, template_name, template_data, reply_tos=None
):
"""
Sends an email based on a template. A template contains replaceable tags
each enclosed in two curly braces, such as {{name}}. The template data passed
in this function contains key-value pairs that define the values to insert
in place of the template tags.
Note: If your account is in the Amazon SES sandbox, the source and
destination email accounts must both be verified.
:param source: The source email account.
:param destination: The destination email account.
:param template_name: The name of a previously created template.
:param template_data: JSON-formatted key-value pairs of replacement values
that are inserted in the template before it is sent.
:return: The ID of the message, assigned by Amazon SES.
"""
send_args = {
"Source": source,
"Destination": destination.to_service_format(),
"Template": template_name,
"TemplateData": json.dumps(template_data),
}
if reply_tos is not None:
send_args["ReplyToAddresses"] = reply_tos
try:
response = self.ses_client.send_templated_email(**send_args)
message_id = response["MessageId"]
logger.info(
"Sent templated mail %s from %s to %s.",
message_id,
source,
destination.tos,
)
except ClientError:
logger.exception(
"Couldn't send templated mail from %s to %s.", source, destination.tos
)
raise
else:
return message_id
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[SendTemplatedEmail](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/SendTemplatedEmail)」を参照してください。
### `UpdateTemplate`
次のコード例は、`UpdateTemplate` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ses#code-examples)での設定と実行の方法を確認してください。
```
class SesTemplate:
"""Encapsulates Amazon SES template functions."""
def __init__(self, ses_client):
"""
:param ses_client: A Boto3 Amazon SES client.
"""
self.ses_client = ses_client
self.template = None
self.template_tags = set()
def _extract_tags(self, subject, text, html):
"""
Extracts tags from a template as a set of unique values.
:param subject: The subject of the email.
:param text: The text version of the email.
:param html: The html version of the email.
"""
self.template_tags = set(re.findall(TEMPLATE_REGEX, subject + text + html))
logger.info("Extracted template tags: %s", self.template_tags)
def update_template(self, name, subject, text, html):
"""
Updates a previously created email template.
:param name: The name of the template.
:param subject: The subject of the email.
:param text: The plain text version of the email.
:param html: The HTML version of the email.
"""
try:
template = {
"TemplateName": name,
"SubjectPart": subject,
"TextPart": text,
"HtmlPart": html,
}
self.ses_client.update_template(Template=template)
logger.info("Updated template %s.", name)
self.template = template
self._extract_tags(subject, text, html)
except ClientError:
logger.exception("Couldn't update template %s.", name)
raise
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[UpdateTemplate](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/UpdateTemplate)」を参照してください。
### `VerifyDomainIdentity`
次のコード例は、`VerifyDomainIdentity` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ses#code-examples)での設定と実行の方法を確認してください。
```
class SesIdentity:
"""Encapsulates Amazon SES identity functions."""
def __init__(self, ses_client):
"""
:param ses_client: A Boto3 Amazon SES client.
"""
self.ses_client = ses_client
def verify_domain_identity(self, domain_name):
"""
Starts verification of a domain identity. To complete verification, you must
create a TXT record with a specific format through your DNS provider.
For more information, see *Verifying a domain with Amazon SES* in the
Amazon SES documentation:
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/verify-domain-procedure.html
:param domain_name: The name of the domain to verify.
:return: The token to include in the TXT record with your DNS provider.
"""
try:
response = self.ses_client.verify_domain_identity(Domain=domain_name)
token = response["VerificationToken"]
logger.info("Got domain verification token for %s.", domain_name)
except ClientError:
logger.exception("Couldn't verify domain %s.", domain_name)
raise
else:
return token
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[VerifyDomainIdentity](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/VerifyDomainIdentity)」を参照してください。
### `VerifyEmailIdentity`
次のコード例は、`VerifyEmailIdentity` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ses#code-examples)での設定と実行の方法を確認してください。
```
class SesIdentity:
"""Encapsulates Amazon SES identity functions."""
def __init__(self, ses_client):
"""
:param ses_client: A Boto3 Amazon SES client.
"""
self.ses_client = ses_client
def verify_email_identity(self, email_address):
"""
Starts verification of an email identity. This function causes an email
to be sent to the specified email address from Amazon SES. To complete
verification, follow the instructions in the email.
:param email_address: The email address to verify.
"""
try:
self.ses_client.verify_email_identity(EmailAddress=email_address)
logger.info("Started verification of %s.", email_address)
except ClientError:
logger.exception("Couldn't start verification of %s.", email_address)
raise
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[VerifyEmailIdentity](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/VerifyEmailIdentity)」を参照してください。
## シナリオ
### リージョン間で E メールとドメイン ID をコピーする
次のコード例は、Amazon SES E メールとドメイン ID をあるリージョンから別の AWS リージョンにコピーする方法を示しています。ドメイン ID が Route 53 で管理されている場合、検証レコードはコピー先リージョンのドメインにコピーされます。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ses#code-examples)での設定と実行の方法を確認してください。
```
import argparse
import json
import logging
from pprint import pprint
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
def get_identities(ses_client):
"""
Gets the identities for the current Region. The Region is specified in the
Boto3 Amazon SES client object.
:param ses_client: A Boto3 Amazon SES client.
:return: The list of email identities and the list of domain identities.
"""
email_identities = []
domain_identities = []
try:
identity_paginator = ses_client.get_paginator("list_identities")
identity_iterator = identity_paginator.paginate(
PaginationConfig={"PageSize": 20}
)
for identity_page in identity_iterator:
for identity in identity_page["Identities"]:
if "@" in identity:
email_identities.append(identity)
else:
domain_identities.append(identity)
logger.info(
"Found %s email and %s domain identities.",
len(email_identities),
len(domain_identities),
)
except ClientError:
logger.exception("Couldn't get identities.")
raise
else:
return email_identities, domain_identities
def verify_emails(email_list, ses_client):
"""
Starts verification of a list of email addresses. Verification causes an email
to be sent to each address. To complete verification, the recipient must follow
the instructions in the email.
:param email_list: The list of email addresses to verify.
:param ses_client: A Boto3 Amazon SES client.
:return: The list of emails that were successfully submitted for verification.
"""
verified_emails = []
for email in email_list:
try:
ses_client.verify_email_identity(EmailAddress=email)
verified_emails.append(email)
logger.info("Started verification of %s.", email)
except ClientError:
logger.warning("Couldn't start verification of %s.", email)
return verified_emails
def verify_domains(domain_list, ses_client):
"""
Starts verification for a list of domain identities. This returns a token for
each domain, which must be registered as a TXT record with the DNS provider for
the domain.
:param domain_list: The list of domains to verify.
:param ses_client: A Boto3 Amazon SES client.
:return: The generated domain tokens to use to completed verification.
"""
domain_tokens = {}
for domain in domain_list:
try:
response = ses_client.verify_domain_identity(Domain=domain)
token = response["VerificationToken"]
domain_tokens[domain] = token
logger.info("Got verification token %s for domain %s.", token, domain)
except ClientError:
logger.warning("Couldn't get verification token for domain %s.", domain)
return domain_tokens
def get_hosted_zones(route53_client):
"""
Gets the Amazon Route 53 hosted zones for the current account.
:param route53_client: A Boto3 Route 53 client.
:return: The list of hosted zones.
"""
zones = []
try:
zone_paginator = route53_client.get_paginator("list_hosted_zones")
zone_iterator = zone_paginator.paginate(PaginationConfig={"PageSize": 20})
zones = [
zone for zone_page in zone_iterator for zone in zone_page["HostedZones"]
]
logger.info("Found %s hosted zones.", len(zones))
except ClientError:
logger.warning("Couldn't get hosted zones.")
return zones
def find_domain_zone_matches(domains, zones):
"""
Finds matches between Amazon SES verified domains and Route 53 hosted zones.
Subdomain matches are taken when found, otherwise root domain matches are taken.
:param domains: The list of domains to match.
:param zones: The list of hosted zones to match.
:return: The set of matched domain-zone pairs. When a match is not found, the
domain is included in the set with a zone value of None.
"""
domain_zones = {}
for domain in domains:
domain_zones[domain] = None
# Start at the most specific sub-domain and walk up to the root domain until a
# zone match is found.
domain_split = domain.split(".")
for index in range(0, len(domain_split) - 1):
sub_domain = ".".join(domain_split[index:])
for zone in zones:
# Normalize the zone name from Route 53 by removing the trailing '.'.
zone_name = zone["Name"][:-1]
if sub_domain == zone_name:
domain_zones[domain] = zone
break
if domain_zones[domain] is not None:
break
return domain_zones
def add_route53_verification_record(domain, token, zone, route53_client):
"""
Adds a domain verification TXT record to the specified Route 53 hosted zone.
When a TXT record already exists in the hosted zone for the specified domain,
the existing values are preserved and the new token is added to the list.
:param domain: The domain to add.
:param token: The verification token for the domain.
:param zone: The hosted zone where the domain verification record is added.
:param route53_client: A Boto3 Route 53 client.
"""
domain_token_record_set_name = f"_amazonses.{domain}"
record_set_paginator = route53_client.get_paginator("list_resource_record_sets")
record_set_iterator = record_set_paginator.paginate(
HostedZoneId=zone["Id"], PaginationConfig={"PageSize": 20}
)
records = []
for record_set_page in record_set_iterator:
try:
txt_record_set = next(
record_set
for record_set in record_set_page["ResourceRecordSets"]
if record_set["Name"][:-1] == domain_token_record_set_name
and record_set["Type"] == "TXT"
)
records = txt_record_set["ResourceRecords"]
logger.info(
"Existing TXT record found in set %s for zone %s.",
domain_token_record_set_name,
zone["Name"],
)
break
except StopIteration:
pass
records.append({"Value": json.dumps(token)})
changes = [
{
"Action": "UPSERT",
"ResourceRecordSet": {
"Name": domain_token_record_set_name,
"Type": "TXT",
"TTL": 1800,
"ResourceRecords": records,
},
}
]
try:
route53_client.change_resource_record_sets(
HostedZoneId=zone["Id"], ChangeBatch={"Changes": changes}
)
logger.info(
"Created or updated the TXT record in set %s for zone %s.",
domain_token_record_set_name,
zone["Name"],
)
except ClientError as err:
logger.warning(
"Got error %s. Couldn't create or update the TXT record for zone %s.",
err.response["Error"]["Code"],
zone["Name"],
)
def generate_dkim_tokens(domain, ses_client):
"""
Generates DKIM tokens for a domain. These must be added as CNAME records to the
DNS provider for the domain.
:param domain: The domain to generate tokens for.
:param ses_client: A Boto3 Amazon SES client.
:return: The list of generated DKIM tokens.
"""
dkim_tokens = []
try:
dkim_tokens = ses_client.verify_domain_dkim(Domain=domain)["DkimTokens"]
logger.info("Generated %s DKIM tokens for domain %s.", len(dkim_tokens), domain)
except ClientError:
logger.warning("Couldn't generate DKIM tokens for domain %s.", domain)
return dkim_tokens
def add_dkim_domain_tokens(hosted_zone, domain, tokens, route53_client):
"""
Adds DKIM domain token CNAME records to a Route 53 hosted zone.
:param hosted_zone: The hosted zone where the records are added.
:param domain: The domain to add.
:param tokens: The DKIM tokens for the domain to add.
:param route53_client: A Boto3 Route 53 client.
"""
try:
changes = [
{
"Action": "UPSERT",
"ResourceRecordSet": {
"Name": f"{token}._domainkey.{domain}",
"Type": "CNAME",
"TTL": 1800,
"ResourceRecords": [{"Value": f"{token}.dkim.amazonses.com"}],
},
}
for token in tokens
]
route53_client.change_resource_record_sets(
HostedZoneId=hosted_zone["Id"], ChangeBatch={"Changes": changes}
)
logger.info(
"Added %s DKIM CNAME records to %s in zone %s.",
len(tokens),
domain,
hosted_zone["Name"],
)
except ClientError:
logger.warning(
"Couldn't add DKIM CNAME records for %s to zone %s.",
domain,
hosted_zone["Name"],
)
def configure_sns_topics(identity, topics, ses_client):
"""
Configures Amazon Simple Notification Service (Amazon SNS) notifications for
an identity. The Amazon SNS topics must already exist.
:param identity: The identity to configure.
:param topics: The list of topics to configure. The choices are Bounce, Delivery,
or Complaint.
:param ses_client: A Boto3 Amazon SES client.
"""
for topic in topics:
topic_arn = input(
f"Enter the Amazon Resource Name (ARN) of the {topic} topic or press "
f"Enter to skip: "
)
if topic_arn != "":
try:
ses_client.set_identity_notification_topic(
Identity=identity, NotificationType=topic, SnsTopic=topic_arn
)
logger.info("Configured %s for %s notifications.", identity, topic)
except ClientError:
logger.warning(
"Couldn't configure %s for %s notifications.", identity, topic
)
def replicate(source_client, destination_client, route53_client):
logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
print("-" * 88)
print(
f"Replicating Amazon SES identities and other configuration from "
f"{source_client.meta.region_name} to {destination_client.meta.region_name}."
)
print("-" * 88)
print(f"Retrieving identities from {source_client.meta.region_name}.")
source_emails, source_domains = get_identities(source_client)
print("Email addresses found:")
print(*source_emails)
print("Domains found:")
print(*source_domains)
print("Starting verification for email identities.")
dest_emails = verify_emails(source_emails, destination_client)
print("Getting domain tokens for domain identities.")
dest_domain_tokens = verify_domains(source_domains, destination_client)
# Get Route 53 hosted zones and match them with Amazon SES domains.
answer = input(
"Is the DNS configuration for your domains managed by Amazon Route 53 (y/n)? "
)
use_route53 = answer.lower() == "y"
hosted_zones = get_hosted_zones(route53_client) if use_route53 else []
if use_route53:
print("Adding or updating Route 53 TXT records for your domains.")
domain_zones = find_domain_zone_matches(dest_domain_tokens.keys(), hosted_zones)
for domain in domain_zones:
add_route53_verification_record(
domain, dest_domain_tokens[domain], domain_zones[domain], route53_client
)
else:
print(
"Use these verification tokens to create TXT records through your DNS "
"provider:"
)
pprint(dest_domain_tokens)
answer = input("Do you want to configure DKIM signing for your identities (y/n)? ")
if answer.lower() == "y":
# Build a set of unique domains from email and domain identities.
domains = {email.split("@")[1] for email in dest_emails}
domains.update(dest_domain_tokens)
domain_zones = find_domain_zone_matches(domains, hosted_zones)
for domain, zone in domain_zones.items():
answer = input(
f"Do you want to configure DKIM signing for {domain} (y/n)? "
)
if answer.lower() == "y":
dkim_tokens = generate_dkim_tokens(domain, destination_client)
if use_route53 and zone is not None:
add_dkim_domain_tokens(zone, domain, dkim_tokens, route53_client)
else:
print(
"Add the following DKIM tokens as CNAME records through your "
"DNS provider:"
)
print(*dkim_tokens, sep="\n")
answer = input(
"Do you want to configure Amazon SNS notifications for your identities (y/n)? "
)
if answer.lower() == "y":
for identity in dest_emails + list(dest_domain_tokens.keys()):
answer = input(
f"Do you want to configure Amazon SNS topics for {identity} (y/n)? "
)
if answer.lower() == "y":
configure_sns_topics(
identity, ["Bounce", "Delivery", "Complaint"], destination_client
)
print(f"Replication complete for {destination_client.meta.region_name}.")
print("-" * 88)
def main():
boto3_session = boto3.Session()
ses_regions = boto3_session.get_available_regions("ses")
parser = argparse.ArgumentParser(
description="Copies email address and domain identities from one AWS Region to "
"another. Optionally adds records for domain verification and DKIM "
"signing to domains that are managed by Amazon Route 53, "
"and sets up Amazon SNS notifications for events of interest."
)
parser.add_argument(
"source_region", choices=ses_regions, help="The region to copy from."
)
parser.add_argument(
"destination_region", choices=ses_regions, help="The region to copy to."
)
args = parser.parse_args()
source_client = boto3.client("ses", region_name=args.source_region)
destination_client = boto3.client("ses", region_name=args.destination_region)
route53_client = boto3.client("route53")
replicate(source_client, destination_client, route53_client)
if __name__ == "__main__":
main()
```
+ API の詳細については、「**AWS SDK for Python (Boto3) API リファレンス」の以下のトピックを参照してください。
+ [ListIdentities](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/ListIdentities)
+ [SetIdentityNotificationTopic](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/SetIdentityNotificationTopic)
+ [VerifyDomainDkim](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/VerifyDomainDkim)
+ [VerifyDomainIdentity](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/VerifyDomainIdentity)
+ [VerifyEmailIdentity](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/VerifyEmailIdentity)
### DynamoDB データを追跡するウェブアプリケーションを作成する
次のコード例は、Amazon DynamoDB テーブルの作業項目を追跡し、Amazon Simple Email Service (Amazon SES) を使用してレポートを送信するウェブアプリケーションを作成する方法を示しています。
**SDK for Python (Boto3)**
を使用して AWS SDK for Python (Boto3) Amazon DynamoDB の作業項目を追跡し、Amazon Simple Email Service (Amazon SES) を使用してレポートを E メールで送信する REST サービスを作成する方法を示します。この例では、Flask ウェブフレームワークを使用して HTTP ルーティングを処理し、React ウェブページと統合して完全に機能するウェブアプリケーションを提供しています。
+ と統合する Flask REST サービスを構築します AWS のサービス。
+ DynamoDB テーブルに保存されている作業項目の読み取り、書き込み、更新を行います。
+ Amazon SES を使用して作業項目のレポートを E メールで送信します。
完全なソースコードとセットアップおよび実行の手順については、GitHub の「[AWS コード例のレポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/dynamodb_item_tracker)」で完全な例を参照してください。
**この例で使用されているサービス**
+ DynamoDB
+ Amazon SES
### Aurora Serverless 作業項目トラッカーの作成
次のコード例は、Amazon Aurora Serverless データベースの作業項目を追跡し、Amazon Simple Email Service (Amazon SES) を使用してレポートを送信するウェブアプリケーションを作成する方法を示しています。
**SDK for Python (Boto3)**
を使用して Amazon Aurora Serverless データベース内の作業項目を追跡し、Amazon Simple Email Service (Amazon SES) を使用してレポートを E メールで送信する REST サービス AWS SDK for Python (Boto3) を作成する方法を示します。この例では、Flask ウェブフレームワークを使用して HTTP ルーティングを処理し、React ウェブページと統合して完全に機能するウェブアプリケーションを提供しています。
+ と統合する Flask REST サービスを構築します AWS のサービス。
+ Aurora Serverless データベースに保存されている作業項目の読み取り、書き込み、更新を行います。
+ データベース認証情報を含む AWS Secrets Manager シークレットを作成し、それを使用してデータベースへの呼び出しを認証します。
+ Amazon SES を使用して作業項目のレポートを E メールで送信します。
完全なソースコードとセットアップおよび実行の手順については、[GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/aurora_item_tracker) で完全な例を参照してください。
**この例で使用されているサービス**
+ Aurora
+ Amazon RDS
+ Amazon RDS データサービス
+ Amazon SES
### 画像内のオブジェクトを検出する
次のコード例は、Amazon Rekognition を使用して画像内でカテゴリ別にオブジェクトを検出するアプリケーションを構築する方法を示しています。
**SDK for Python (Boto3)**
を使用して AWS SDK for Python (Boto3) 、以下を可能にするウェブアプリケーションを作成する方法を示します。
+ Amazon Simple Storage Service (Amazon S3) バケットに、写真をアップロードします。
+ Amazon Rekognition を使用して、写真を分析およびラベル付けします。
+ Amazon Simple Email Service (Amazon SES) を使用して、イメージ分析の E メールレポートを送信します。
この例には、React で構築された JavaScript で記述されたウェブページと、Flask-RESTful で構築された Python で記述された REST サービスの 2 つの主要なコンポーネントが含まれています。
React ウェブページを使用すると、次のことができます。
+ S3 バケットに保存されているイメージのリストを表示します。
+ イメージを S3 バケットにアップロードします。
+ イメージ内で検出された項目を識別するイメージとラベルを表示します。
+ S3 バケット内のすべてのイメージのレポートを取得し、レポートの E メールを送信します。
ウェブページが REST サービスを呼び出します。サービスはリクエストを AWS に送信して、以下のアクションを実行します。
+ S3 バケット内のイメージのリストを取得し、フィルタリングします。
+ Amazon S3 バケットに写真をアップロードします。
+ Amazon Rekognition を使用して個々の写真を分析し、写真で検出された項目を識別するラベルのリストを取得します。
+ S3 バケット内のすべての写真を分析し、Amazon SES を使用してレポートを E メールで送信します。
完全なソースコードとセットアップおよび実行の手順については、[GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/photo_analyzer) で完全な例を参照してください。
**この例で使用されているサービス**
+ Amazon Rekognition
+ Amazon S3
+ Amazon SES
### 動画内の人物や物体を検出する
次のコード例は、Amazon Rekognition で動画内の人やオブジェクトを検出する方法を示します。
**SDK for Python (Boto3)**
Amazon Rekognition を使用して、非同期検出ジョブを開始して、動画内の顔、オブジェクト、人を検出します。この例では、ジョブが完了し、Amazon Simple Queue Service (Amazon SQS) キューをトピックにサブスクライブしたときに、Amazon Simple Notification Service (Amazon SNS) トピックに通知するように Amazon Rekognition を設定します。キューがジョブに関するメッセージを受信すると、ジョブが取得され、結果が出力されます。
この例は GitHub で最もよく見られます。完全なソースコードとセットアップおよび実行の手順については、[GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rekognition) で完全な例を参照してください。
**この例で使用されているサービス**
+ Amazon Rekognition
+ Amazon S3
+ Amazon SES
+ Amazon SNS
+ Amazon SQS
### SMTP エンドポイントに接続するための認証情報を生成する
次のコード例は、Amazon SES SMTP エンドポイントに接続するための認証情報を生成する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ses#code-examples)での設定と実行の方法を確認してください。
```
#!/usr/bin/env python3
import hmac
import hashlib
import base64
import argparse
SMTP_REGIONS = [
"us-east-2", # US East (Ohio)
"us-east-1", # US East (N. Virginia)
"us-west-2", # US West (Oregon)
"ap-south-1", # Asia Pacific (Mumbai)
"ap-northeast-2", # Asia Pacific (Seoul)
"ap-southeast-1", # Asia Pacific (Singapore)
"ap-southeast-2", # Asia Pacific (Sydney)
"ap-northeast-1", # Asia Pacific (Tokyo)
"ca-central-1", # Canada (Central)
"eu-central-1", # Europe (Frankfurt)
"eu-west-1", # Europe (Ireland)
"eu-west-2", # Europe (London)
"eu-south-1", # Europe (Milan)
"eu-north-1", # Europe (Stockholm)
"sa-east-1", # South America (Sao Paulo)
"us-gov-west-1", # AWS GovCloud (US)
"us-gov-east-1", # AWS GovCloud (US)
]
# These values are required to calculate the signature. Do not change them.
DATE = "11111111"
SERVICE = "ses"
MESSAGE = "SendRawEmail"
TERMINAL = "aws4_request"
VERSION = 0x04
def sign(key, msg):
return hmac.new(key, msg.encode("utf-8"), hashlib.sha256).digest()
def calculate_key(secret_access_key, region):
if region not in SMTP_REGIONS:
raise ValueError(f"The {region} Region doesn't have an SMTP endpoint.")
signature = sign(("AWS4" + secret_access_key).encode("utf-8"), DATE)
signature = sign(signature, region)
signature = sign(signature, SERVICE)
signature = sign(signature, TERMINAL)
signature = sign(signature, MESSAGE)
signature_and_version = bytes([VERSION]) + signature
smtp_password = base64.b64encode(signature_and_version)
return smtp_password.decode("utf-8")
def main():
parser = argparse.ArgumentParser(
description="Convert a Secret Access Key to an SMTP password."
)
parser.add_argument("secret", help="The Secret Access Key to convert.")
parser.add_argument(
"region",
help="The AWS Region where the SMTP password will be used.",
choices=SMTP_REGIONS,
)
args = parser.parse_args()
print(calculate_key(args.secret, args.region))
if __name__ == "__main__":
main()
```
### E メール ID を検証してメッセージを送信する
次のコード例は、以下の操作方法を示しています。
+ Amazon SES で E メールアドレスを追加し、検証します。
+ 標準の E メールメッセージを送信します。
+ テンプレートを作成し、テンプレート化された E メールメッセージを送信します。
+ Amazon SES SMTP サーバーを使用してメッセージを送信します。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ses#code-examples)での設定と実行の方法を確認してください。
Amazon SES で E メールアドレスを検証し、メッセージを送信します。
```
def usage_demo():
print("-" * 88)
print("Welcome to the Amazon Simple Email Service (Amazon SES) email demo!")
print("-" * 88)
logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
ses_client = boto3.client("ses")
ses_identity = SesIdentity(ses_client)
ses_mail_sender = SesMailSender(ses_client)
ses_template = SesTemplate(ses_client)
email = input("Enter an email address to send mail with Amazon SES: ")
status = ses_identity.get_identity_status(email)
verified = status == "Success"
if not verified:
answer = input(
f"The address '{email}' is not verified with Amazon SES. Unless your "
f"Amazon SES account is out of sandbox, you can send mail only from "
f"and to verified accounts. Do you want to verify this account for use "
f"with Amazon SES? If yes, the address will receive a verification "
f"email (y/n): "
)
if answer.lower() == "y":
ses_identity.verify_email_identity(email)
print(f"Follow the steps in the email to {email} to complete verification.")
print("Waiting for verification...")
try:
ses_identity.wait_until_identity_exists(email)
print(f"Identity verified for {email}.")
verified = True
except WaiterError:
print(
f"Verification timeout exceeded. You must complete the "
f"steps in the email sent to {email} to verify the address."
)
if verified:
test_message_text = "Hello from the Amazon SES mail demo!"
test_message_html = "Hello!
From the Amazon SES mail demo!
"
print(f"Sending mail from {email} to {email}.")
ses_mail_sender.send_email(
email,
SesDestination([email]),
"Amazon SES demo",
test_message_text,
test_message_html,
)
input("Mail sent. Check your inbox and press Enter to continue.")
template = {
"name": "doc-example-template",
"subject": "Example of an email template.",
"text": "This is what {{name}} will {{action}} if {{name}} can't display "
"HTML.",
"html": "This is what {{name}} will {{action}} if {{name}} "
"can display HTML.
",
}
print("Creating a template and sending a templated email.")
ses_template.create_template(**template)
template_data = {"name": email.split("@")[0], "action": "read"}
if ses_template.verify_tags(template_data):
ses_mail_sender.send_templated_email(
email, SesDestination([email]), ses_template.name(), template_data
)
input("Mail sent. Check your inbox and press Enter to continue.")
print("Sending mail through the Amazon SES SMTP server.")
boto3_session = boto3.Session()
region = boto3_session.region_name
credentials = boto3_session.get_credentials()
port = 587
smtp_server = f"email-smtp.{region}.amazonaws.com"
password = calculate_key(credentials.secret_key, region)
message = """
Subject: Hi there
This message is sent from the Amazon SES SMTP mail demo."""
context = ssl.create_default_context()
with smtplib.SMTP(smtp_server, port) as server:
server.starttls(context=context)
server.login(credentials.access_key, password)
server.sendmail(email, email, message)
print("Mail sent. Check your inbox!")
if ses_template.template is not None:
print("Deleting demo template.")
ses_template.delete_template()
if verified:
answer = input(f"Do you want to remove {email} from Amazon SES (y/n)? ")
if answer.lower() == "y":
ses_identity.delete_identity(email)
print("Thanks for watching!")
print("-" * 88)
```
Amazon SES の ID アクションをラップする関数を作成します。
```
class SesIdentity:
"""Encapsulates Amazon SES identity functions."""
def __init__(self, ses_client):
"""
:param ses_client: A Boto3 Amazon SES client.
"""
self.ses_client = ses_client
def verify_domain_identity(self, domain_name):
"""
Starts verification of a domain identity. To complete verification, you must
create a TXT record with a specific format through your DNS provider.
For more information, see *Verifying a domain with Amazon SES* in the
Amazon SES documentation:
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/verify-domain-procedure.html
:param domain_name: The name of the domain to verify.
:return: The token to include in the TXT record with your DNS provider.
"""
try:
response = self.ses_client.verify_domain_identity(Domain=domain_name)
token = response["VerificationToken"]
logger.info("Got domain verification token for %s.", domain_name)
except ClientError:
logger.exception("Couldn't verify domain %s.", domain_name)
raise
else:
return token
def verify_email_identity(self, email_address):
"""
Starts verification of an email identity. This function causes an email
to be sent to the specified email address from Amazon SES. To complete
verification, follow the instructions in the email.
:param email_address: The email address to verify.
"""
try:
self.ses_client.verify_email_identity(EmailAddress=email_address)
logger.info("Started verification of %s.", email_address)
except ClientError:
logger.exception("Couldn't start verification of %s.", email_address)
raise
def wait_until_identity_exists(self, identity):
"""
Waits until an identity exists. The waiter polls Amazon SES until the
identity has been successfully verified or until it exceeds its maximum time.
:param identity: The identity to wait for.
"""
try:
waiter = self.ses_client.get_waiter("identity_exists")
logger.info("Waiting until %s exists.", identity)
waiter.wait(Identities=[identity])
except WaiterError:
logger.error("Waiting for identity %s failed or timed out.", identity)
raise
def get_identity_status(self, identity):
"""
Gets the status of an identity. This can be used to discover whether
an identity has been successfully verified.
:param identity: The identity to query.
:return: The status of the identity.
"""
try:
response = self.ses_client.get_identity_verification_attributes(
Identities=[identity]
)
status = response["VerificationAttributes"].get(
identity, {"VerificationStatus": "NotFound"}
)["VerificationStatus"]
logger.info("Got status of %s for %s.", status, identity)
except ClientError:
logger.exception("Couldn't get status for %s.", identity)
raise
else:
return status
def delete_identity(self, identity):
"""
Deletes an identity.
:param identity: The identity to remove.
"""
try:
self.ses_client.delete_identity(Identity=identity)
logger.info("Deleted identity %s.", identity)
except ClientError:
logger.exception("Couldn't delete identity %s.", identity)
raise
def list_identities(self, identity_type, max_items):
"""
Gets the identities of the specified type for the current account.
:param identity_type: The type of identity to retrieve, such as EmailAddress.
:param max_items: The maximum number of identities to retrieve.
:return: The list of retrieved identities.
"""
try:
response = self.ses_client.list_identities(
IdentityType=identity_type, MaxItems=max_items
)
identities = response["Identities"]
logger.info("Got %s identities for the current account.", len(identities))
except ClientError:
logger.exception("Couldn't list identities for the current account.")
raise
else:
return identities
```
Amazon SES テンプレートのアクションをラップする関数を作成します。
```
class SesTemplate:
"""Encapsulates Amazon SES template functions."""
def __init__(self, ses_client):
"""
:param ses_client: A Boto3 Amazon SES client.
"""
self.ses_client = ses_client
self.template = None
self.template_tags = set()
def _extract_tags(self, subject, text, html):
"""
Extracts tags from a template as a set of unique values.
:param subject: The subject of the email.
:param text: The text version of the email.
:param html: The html version of the email.
"""
self.template_tags = set(re.findall(TEMPLATE_REGEX, subject + text + html))
logger.info("Extracted template tags: %s", self.template_tags)
def create_template(self, name, subject, text, html):
"""
Creates an email template.
:param name: The name of the template.
:param subject: The subject of the email.
:param text: The plain text version of the email.
:param html: The HTML version of the email.
"""
try:
template = {
"TemplateName": name,
"SubjectPart": subject,
"TextPart": text,
"HtmlPart": html,
}
self.ses_client.create_template(Template=template)
logger.info("Created template %s.", name)
self.template = template
self._extract_tags(subject, text, html)
except ClientError:
logger.exception("Couldn't create template %s.", name)
raise
def delete_template(self):
"""
Deletes an email template.
"""
try:
self.ses_client.delete_template(TemplateName=self.template["TemplateName"])
logger.info("Deleted template %s.", self.template["TemplateName"])
self.template = None
self.template_tags = None
except ClientError:
logger.exception(
"Couldn't delete template %s.", self.template["TemplateName"]
)
raise
def get_template(self, name):
"""
Gets a previously created email template.
:param name: The name of the template to retrieve.
:return: The retrieved email template.
"""
try:
response = self.ses_client.get_template(TemplateName=name)
self.template = response["Template"]
logger.info("Got template %s.", name)
self._extract_tags(
self.template["SubjectPart"],
self.template["TextPart"],
self.template["HtmlPart"],
)
except ClientError:
logger.exception("Couldn't get template %s.", name)
raise
else:
return self.template
def list_templates(self):
"""
Gets a list of all email templates for the current account.
:return: The list of retrieved email templates.
"""
try:
response = self.ses_client.list_templates()
templates = response["TemplatesMetadata"]
logger.info("Got %s templates.", len(templates))
except ClientError:
logger.exception("Couldn't get templates.")
raise
else:
return templates
def update_template(self, name, subject, text, html):
"""
Updates a previously created email template.
:param name: The name of the template.
:param subject: The subject of the email.
:param text: The plain text version of the email.
:param html: The HTML version of the email.
"""
try:
template = {
"TemplateName": name,
"SubjectPart": subject,
"TextPart": text,
"HtmlPart": html,
}
self.ses_client.update_template(Template=template)
logger.info("Updated template %s.", name)
self.template = template
self._extract_tags(subject, text, html)
except ClientError:
logger.exception("Couldn't update template %s.", name)
raise
```
Amazon SES の E メールアクションをラップする関数を作成します。
```
class SesDestination:
"""Contains data about an email destination."""
def __init__(self, tos, ccs=None, bccs=None):
"""
:param tos: The list of recipients on the 'To:' line.
:param ccs: The list of recipients on the 'CC:' line.
:param bccs: The list of recipients on the 'BCC:' line.
"""
self.tos = tos
self.ccs = ccs
self.bccs = bccs
def to_service_format(self):
"""
:return: The destination data in the format expected by Amazon SES.
"""
svc_format = {"ToAddresses": self.tos}
if self.ccs is not None:
svc_format["CcAddresses"] = self.ccs
if self.bccs is not None:
svc_format["BccAddresses"] = self.bccs
return svc_format
class SesMailSender:
"""Encapsulates functions to send emails with Amazon SES."""
def __init__(self, ses_client):
"""
:param ses_client: A Boto3 Amazon SES client.
"""
self.ses_client = ses_client
def send_email(self, source, destination, subject, text, html, reply_tos=None):
"""
Sends an email.
Note: If your account is in the Amazon SES sandbox, the source and
destination email accounts must both be verified.
:param source: The source email account.
:param destination: The destination email account.
:param subject: The subject of the email.
:param text: The plain text version of the body of the email.
:param html: The HTML version of the body of the email.
:param reply_tos: Email accounts that will receive a reply if the recipient
replies to the message.
:return: The ID of the message, assigned by Amazon SES.
"""
send_args = {
"Source": source,
"Destination": destination.to_service_format(),
"Message": {
"Subject": {"Data": subject},
"Body": {"Text": {"Data": text}, "Html": {"Data": html}},
},
}
if reply_tos is not None:
send_args["ReplyToAddresses"] = reply_tos
try:
response = self.ses_client.send_email(**send_args)
message_id = response["MessageId"]
logger.info(
"Sent mail %s from %s to %s.", message_id, source, destination.tos
)
except ClientError:
logger.exception(
"Couldn't send mail from %s to %s.", source, destination.tos
)
raise
else:
return message_id
def send_templated_email(
self, source, destination, template_name, template_data, reply_tos=None
):
"""
Sends an email based on a template. A template contains replaceable tags
each enclosed in two curly braces, such as {{name}}. The template data passed
in this function contains key-value pairs that define the values to insert
in place of the template tags.
Note: If your account is in the Amazon SES sandbox, the source and
destination email accounts must both be verified.
:param source: The source email account.
:param destination: The destination email account.
:param template_name: The name of a previously created template.
:param template_data: JSON-formatted key-value pairs of replacement values
that are inserted in the template before it is sent.
:return: The ID of the message, assigned by Amazon SES.
"""
send_args = {
"Source": source,
"Destination": destination.to_service_format(),
"Template": template_name,
"TemplateData": json.dumps(template_data),
}
if reply_tos is not None:
send_args["ReplyToAddresses"] = reply_tos
try:
response = self.ses_client.send_templated_email(**send_args)
message_id = response["MessageId"]
logger.info(
"Sent templated mail %s from %s to %s.",
message_id,
source,
destination.tos,
)
except ClientError:
logger.exception(
"Couldn't send templated mail from %s to %s.", source, destination.tos
)
raise
else:
return message_id
```
+ API の詳細については、「**AWS SDK for Python (Boto3) API リファレンス」の以下のトピックを参照してください。
+ [CreateTemplate](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/CreateTemplate)
+ [DeleteIdentity](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/DeleteIdentity)
+ [DeleteTemplate](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/DeleteTemplate)
+ [GetIdentityVerificationAttributes](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/GetIdentityVerificationAttributes)
+ [GetTemplate](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/GetTemplate)
+ [ListIdentities](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/ListIdentities)
+ [ListTemplates](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/ListTemplates)
+ [SendEmail](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/SendEmail)
+ [SendTemplatedEmail](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/SendTemplatedEmail)
+ [UpdateTemplate](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/UpdateTemplate)
+ [VerifyDomainIdentity](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/VerifyDomainIdentity)
+ [VerifyEmailIdentity](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/VerifyEmailIdentity)
# SDK for Python (Boto3) を使用する Amazon SES API v2 の例
次のコード例は、Amazon SES API v2 AWS SDK for Python (Boto3) で を使用してアクションを実行し、一般的なシナリオを実装する方法を示しています。
*アクション*はより大きなプログラムからのコードの抜粋であり、コンテキスト内で実行する必要があります。アクションは個々のサービス機能を呼び出す方法を示していますが、コンテキスト内のアクションは、関連するシナリオで確認できます。
*シナリオ*は、1 つのサービス内から、または他の AWS のサービスと組み合わせて複数の関数を呼び出し、特定のタスクを実行する方法を示すコード例です。
各例には完全なソースコードへのリンクが含まれており、コードの設定方法と実行方法に関する手順を確認できます。
**Topics**
+ [アクション](#actions)
+ [シナリオ](#scenarios)
## アクション
### `CreateContact`
次のコード例は、`CreateContact` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sesv2#code-examples)での設定と実行の方法を確認してください。
```
def main():
"""
The main function that orchestrates the execution of the workflow.
"""
print(INTRO)
ses_client = boto3.client("sesv2")
workflow = SESv2Workflow(ses_client)
try:
workflow.prepare_application()
workflow.gather_subscriber_email_addresses()
workflow.send_coupon_newsletter()
workflow.monitor_and_review()
except ClientError as e:
print_error(e)
workflow.clean_up()
class SESv2Workflow:
"""
A class to manage the SES v2 Coupon Newsletter Workflow.
"""
def __init__(self, ses_client, sleep=True):
self.ses_client = ses_client
self.sleep = sleep
try:
# Create a new contact
self.ses_client.create_contact(
ContactListName=CONTACT_LIST_NAME, EmailAddress=email
)
print(f"Contact with email '{email}' created successfully.")
# Send the welcome email
self.ses_client.send_email(
FromEmailAddress=self.verified_email,
Destination={"ToAddresses": [email]},
Content={
"Simple": {
"Subject": {
"Data": "Welcome to the Weekly Coupons Newsletter"
},
"Body": {
"Text": {"Data": welcome_text},
"Html": {"Data": welcome_html},
},
}
},
)
print(f"Welcome email sent to '{email}'.")
if self.sleep:
# 1 email per second in sandbox mode, remove in production.
sleep(1.1)
except ClientError as e:
# If the contact already exists, skip and proceed
if e.response["Error"]["Code"] == "AlreadyExistsException":
print(f"Contact with email '{email}' already exists. Skipping...")
else:
raise e
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[CreateContact](https://docs.aws.amazon.com/goto/boto3/sesv2-2019-09-27/CreateContact)」を参照してください。
### `CreateContactList`
次のコード例は、`CreateContactList` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sesv2#code-examples)での設定と実行の方法を確認してください。
```
def main():
"""
The main function that orchestrates the execution of the workflow.
"""
print(INTRO)
ses_client = boto3.client("sesv2")
workflow = SESv2Workflow(ses_client)
try:
workflow.prepare_application()
workflow.gather_subscriber_email_addresses()
workflow.send_coupon_newsletter()
workflow.monitor_and_review()
except ClientError as e:
print_error(e)
workflow.clean_up()
class SESv2Workflow:
"""
A class to manage the SES v2 Coupon Newsletter Workflow.
"""
def __init__(self, ses_client, sleep=True):
self.ses_client = ses_client
self.sleep = sleep
try:
self.ses_client.create_contact_list(ContactListName=CONTACT_LIST_NAME)
print(f"Contact list '{CONTACT_LIST_NAME}' created successfully.")
except ClientError as e:
# If the contact list already exists, skip and proceed
if e.response["Error"]["Code"] == "AlreadyExistsException":
print(f"Contact list '{CONTACT_LIST_NAME}' already exists.")
else:
raise e
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[CreateContactList](https://docs.aws.amazon.com/goto/boto3/sesv2-2019-09-27/CreateContactList)」を参照してください。
### `CreateEmailIdentity`
次のコード例は、`CreateEmailIdentity` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sesv2#code-examples)での設定と実行の方法を確認してください。
```
def main():
"""
The main function that orchestrates the execution of the workflow.
"""
print(INTRO)
ses_client = boto3.client("sesv2")
workflow = SESv2Workflow(ses_client)
try:
workflow.prepare_application()
workflow.gather_subscriber_email_addresses()
workflow.send_coupon_newsletter()
workflow.monitor_and_review()
except ClientError as e:
print_error(e)
workflow.clean_up()
class SESv2Workflow:
"""
A class to manage the SES v2 Coupon Newsletter Workflow.
"""
def __init__(self, ses_client, sleep=True):
self.ses_client = ses_client
self.sleep = sleep
try:
self.ses_client.create_email_identity(EmailIdentity=self.verified_email)
print(f"Email identity '{self.verified_email}' created successfully.")
except ClientError as e:
# If the email identity already exists, skip and proceed
if e.response["Error"]["Code"] == "AlreadyExistsException":
print(f"Email identity '{self.verified_email}' already exists.")
else:
raise e
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[CreateEmailIdentity](https://docs.aws.amazon.com/goto/boto3/sesv2-2019-09-27/CreateEmailIdentity)」を参照してください。
### `CreateEmailTemplate`
次のコード例は、`CreateEmailTemplate` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sesv2#code-examples)での設定と実行の方法を確認してください。
```
def main():
"""
The main function that orchestrates the execution of the workflow.
"""
print(INTRO)
ses_client = boto3.client("sesv2")
workflow = SESv2Workflow(ses_client)
try:
workflow.prepare_application()
workflow.gather_subscriber_email_addresses()
workflow.send_coupon_newsletter()
workflow.monitor_and_review()
except ClientError as e:
print_error(e)
workflow.clean_up()
class SESv2Workflow:
"""
A class to manage the SES v2 Coupon Newsletter Workflow.
"""
def __init__(self, ses_client, sleep=True):
self.ses_client = ses_client
self.sleep = sleep
try:
template_content = {
"Subject": "Weekly Coupons Newsletter",
"Html": load_file_content("coupon-newsletter.html"),
"Text": load_file_content("coupon-newsletter.txt"),
}
self.ses_client.create_email_template(
TemplateName=TEMPLATE_NAME, TemplateContent=template_content
)
print(f"Email template '{TEMPLATE_NAME}' created successfully.")
except ClientError as e:
# If the template already exists, skip and proceed
if e.response["Error"]["Code"] == "AlreadyExistsException":
print(f"Email template '{TEMPLATE_NAME}' already exists.")
else:
raise e
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[CreateEmailTemplate](https://docs.aws.amazon.com/goto/boto3/sesv2-2019-09-27/CreateEmailTemplate)」を参照してください。
### `DeleteContactList`
次のコード例は、`DeleteContactList` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sesv2#code-examples)での設定と実行の方法を確認してください。
```
def main():
"""
The main function that orchestrates the execution of the workflow.
"""
print(INTRO)
ses_client = boto3.client("sesv2")
workflow = SESv2Workflow(ses_client)
try:
workflow.prepare_application()
workflow.gather_subscriber_email_addresses()
workflow.send_coupon_newsletter()
workflow.monitor_and_review()
except ClientError as e:
print_error(e)
workflow.clean_up()
class SESv2Workflow:
"""
A class to manage the SES v2 Coupon Newsletter Workflow.
"""
def __init__(self, ses_client, sleep=True):
self.ses_client = ses_client
self.sleep = sleep
try:
self.ses_client.delete_contact_list(ContactListName=CONTACT_LIST_NAME)
print(f"Contact list '{CONTACT_LIST_NAME}' deleted successfully.")
except ClientError as e:
# If the contact list doesn't exist, skip and proceed
if e.response["Error"]["Code"] == "NotFoundException":
print(f"Contact list '{CONTACT_LIST_NAME}' does not exist.")
else:
print(e)
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[DeleteContactList](https://docs.aws.amazon.com/goto/boto3/sesv2-2019-09-27/DeleteContactList)」を参照してください。
### `DeleteEmailIdentity`
次のコード例は、`DeleteEmailIdentity` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sesv2#code-examples)での設定と実行の方法を確認してください。
```
def main():
"""
The main function that orchestrates the execution of the workflow.
"""
print(INTRO)
ses_client = boto3.client("sesv2")
workflow = SESv2Workflow(ses_client)
try:
workflow.prepare_application()
workflow.gather_subscriber_email_addresses()
workflow.send_coupon_newsletter()
workflow.monitor_and_review()
except ClientError as e:
print_error(e)
workflow.clean_up()
class SESv2Workflow:
"""
A class to manage the SES v2 Coupon Newsletter Workflow.
"""
def __init__(self, ses_client, sleep=True):
self.ses_client = ses_client
self.sleep = sleep
try:
self.ses_client.delete_email_identity(EmailIdentity=self.verified_email)
print(f"Email identity '{self.verified_email}' deleted successfully.")
except ClientError as e:
# If the email identity doesn't exist, skip and proceed
if e.response["Error"]["Code"] == "NotFoundException":
print(f"Email identity '{self.verified_email}' does not exist.")
else:
print(e)
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[DeleteEmailIdentity](https://docs.aws.amazon.com/goto/boto3/sesv2-2019-09-27/DeleteEmailIdentity)」を参照してください。
### `DeleteEmailTemplate`
次のコード例は、`DeleteEmailTemplate` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sesv2#code-examples)での設定と実行の方法を確認してください。
```
def main():
"""
The main function that orchestrates the execution of the workflow.
"""
print(INTRO)
ses_client = boto3.client("sesv2")
workflow = SESv2Workflow(ses_client)
try:
workflow.prepare_application()
workflow.gather_subscriber_email_addresses()
workflow.send_coupon_newsletter()
workflow.monitor_and_review()
except ClientError as e:
print_error(e)
workflow.clean_up()
class SESv2Workflow:
"""
A class to manage the SES v2 Coupon Newsletter Workflow.
"""
def __init__(self, ses_client, sleep=True):
self.ses_client = ses_client
self.sleep = sleep
try:
self.ses_client.delete_email_template(TemplateName=TEMPLATE_NAME)
print(f"Email template '{TEMPLATE_NAME}' deleted successfully.")
except ClientError as e:
# If the email template doesn't exist, skip and proceed
if e.response["Error"]["Code"] == "NotFoundException":
print(f"Email template '{TEMPLATE_NAME}' does not exist.")
else:
print(e)
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[DeleteEmailTemplate](https://docs.aws.amazon.com/goto/boto3/sesv2-2019-09-27/DeleteEmailTemplate)」を参照してください。
### `ListContacts`
次のコード例は、`ListContacts` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sesv2#code-examples)での設定と実行の方法を確認してください。
```
def main():
"""
The main function that orchestrates the execution of the workflow.
"""
print(INTRO)
ses_client = boto3.client("sesv2")
workflow = SESv2Workflow(ses_client)
try:
workflow.prepare_application()
workflow.gather_subscriber_email_addresses()
workflow.send_coupon_newsletter()
workflow.monitor_and_review()
except ClientError as e:
print_error(e)
workflow.clean_up()
class SESv2Workflow:
"""
A class to manage the SES v2 Coupon Newsletter Workflow.
"""
def __init__(self, ses_client, sleep=True):
self.ses_client = ses_client
self.sleep = sleep
try:
contacts_response = self.ses_client.list_contacts(
ContactListName=CONTACT_LIST_NAME
)
except ClientError as e:
if e.response["Error"]["Code"] == "NotFoundException":
print(f"Contact list '{CONTACT_LIST_NAME}' does not exist.")
return
else:
raise e
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[ListContacts](https://docs.aws.amazon.com/goto/boto3/sesv2-2019-09-27/ListContacts)」を参照してください。
### `SendEmail`
次のコード例は、`SendEmail` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sesv2#code-examples)での設定と実行の方法を確認してください。
連絡先リストのすべてのメンバーにメッセージを送信します。
```
def main():
"""
The main function that orchestrates the execution of the workflow.
"""
print(INTRO)
ses_client = boto3.client("sesv2")
workflow = SESv2Workflow(ses_client)
try:
workflow.prepare_application()
workflow.gather_subscriber_email_addresses()
workflow.send_coupon_newsletter()
workflow.monitor_and_review()
except ClientError as e:
print_error(e)
workflow.clean_up()
class SESv2Workflow:
"""
A class to manage the SES v2 Coupon Newsletter Workflow.
"""
def __init__(self, ses_client, sleep=True):
self.ses_client = ses_client
self.sleep = sleep
self.ses_client.send_email(
FromEmailAddress=self.verified_email,
Destination={"ToAddresses": [email]},
Content={
"Simple": {
"Subject": {
"Data": "Welcome to the Weekly Coupons Newsletter"
},
"Body": {
"Text": {"Data": welcome_text},
"Html": {"Data": welcome_html},
},
}
},
)
print(f"Welcome email sent to '{email}'.")
```
テンプレートを使用して、連絡先リストのメンバー全員にメッセージを送信します。
```
def main():
"""
The main function that orchestrates the execution of the workflow.
"""
print(INTRO)
ses_client = boto3.client("sesv2")
workflow = SESv2Workflow(ses_client)
try:
workflow.prepare_application()
workflow.gather_subscriber_email_addresses()
workflow.send_coupon_newsletter()
workflow.monitor_and_review()
except ClientError as e:
print_error(e)
workflow.clean_up()
class SESv2Workflow:
"""
A class to manage the SES v2 Coupon Newsletter Workflow.
"""
def __init__(self, ses_client, sleep=True):
self.ses_client = ses_client
self.sleep = sleep
self.ses_client.send_email(
FromEmailAddress=self.verified_email,
Destination={"ToAddresses": [email_address]},
Content={
"Template": {
"TemplateName": TEMPLATE_NAME,
"TemplateData": coupon_items,
}
},
ListManagementOptions={"ContactListName": CONTACT_LIST_NAME},
)
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[SendEmail](https://docs.aws.amazon.com/goto/boto3/sesv2-2019-09-27/SendEmail)」を参照してください。
## シナリオ
### ニュースレターのシナリオ
以下のコード例は、Amazon SES API v2 のニュースレターのシナリオを実行する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sesv2#code-examples)での設定と実行の方法を確認してください。
```
def main():
"""
The main function that orchestrates the execution of the workflow.
"""
print(INTRO)
ses_client = boto3.client("sesv2")
workflow = SESv2Workflow(ses_client)
try:
workflow.prepare_application()
workflow.gather_subscriber_email_addresses()
workflow.send_coupon_newsletter()
workflow.monitor_and_review()
except ClientError as e:
print_error(e)
workflow.clean_up()
class SESv2Workflow:
"""
A class to manage the SES v2 Coupon Newsletter Workflow.
"""
def __init__(self, ses_client, sleep=True):
self.ses_client = ses_client
self.sleep = sleep
try:
self.ses_client.create_contact_list(ContactListName=CONTACT_LIST_NAME)
print(f"Contact list '{CONTACT_LIST_NAME}' created successfully.")
except ClientError as e:
# If the contact list already exists, skip and proceed
if e.response["Error"]["Code"] == "AlreadyExistsException":
print(f"Contact list '{CONTACT_LIST_NAME}' already exists.")
else:
raise e
try:
# Create a new contact
self.ses_client.create_contact(
ContactListName=CONTACT_LIST_NAME, EmailAddress=email
)
print(f"Contact with email '{email}' created successfully.")
# Send the welcome email
self.ses_client.send_email(
FromEmailAddress=self.verified_email,
Destination={"ToAddresses": [email]},
Content={
"Simple": {
"Subject": {
"Data": "Welcome to the Weekly Coupons Newsletter"
},
"Body": {
"Text": {"Data": welcome_text},
"Html": {"Data": welcome_html},
},
}
},
)
print(f"Welcome email sent to '{email}'.")
if self.sleep:
# 1 email per second in sandbox mode, remove in production.
sleep(1.1)
except ClientError as e:
# If the contact already exists, skip and proceed
if e.response["Error"]["Code"] == "AlreadyExistsException":
print(f"Contact with email '{email}' already exists. Skipping...")
else:
raise e
try:
contacts_response = self.ses_client.list_contacts(
ContactListName=CONTACT_LIST_NAME
)
except ClientError as e:
if e.response["Error"]["Code"] == "NotFoundException":
print(f"Contact list '{CONTACT_LIST_NAME}' does not exist.")
return
else:
raise e
self.ses_client.send_email(
FromEmailAddress=self.verified_email,
Destination={"ToAddresses": [email]},
Content={
"Simple": {
"Subject": {
"Data": "Welcome to the Weekly Coupons Newsletter"
},
"Body": {
"Text": {"Data": welcome_text},
"Html": {"Data": welcome_html},
},
}
},
)
print(f"Welcome email sent to '{email}'.")
self.ses_client.send_email(
FromEmailAddress=self.verified_email,
Destination={"ToAddresses": [email_address]},
Content={
"Template": {
"TemplateName": TEMPLATE_NAME,
"TemplateData": coupon_items,
}
},
ListManagementOptions={"ContactListName": CONTACT_LIST_NAME},
)
try:
self.ses_client.create_email_identity(EmailIdentity=self.verified_email)
print(f"Email identity '{self.verified_email}' created successfully.")
except ClientError as e:
# If the email identity already exists, skip and proceed
if e.response["Error"]["Code"] == "AlreadyExistsException":
print(f"Email identity '{self.verified_email}' already exists.")
else:
raise e
try:
template_content = {
"Subject": "Weekly Coupons Newsletter",
"Html": load_file_content("coupon-newsletter.html"),
"Text": load_file_content("coupon-newsletter.txt"),
}
self.ses_client.create_email_template(
TemplateName=TEMPLATE_NAME, TemplateContent=template_content
)
print(f"Email template '{TEMPLATE_NAME}' created successfully.")
except ClientError as e:
# If the template already exists, skip and proceed
if e.response["Error"]["Code"] == "AlreadyExistsException":
print(f"Email template '{TEMPLATE_NAME}' already exists.")
else:
raise e
try:
self.ses_client.delete_contact_list(ContactListName=CONTACT_LIST_NAME)
print(f"Contact list '{CONTACT_LIST_NAME}' deleted successfully.")
except ClientError as e:
# If the contact list doesn't exist, skip and proceed
if e.response["Error"]["Code"] == "NotFoundException":
print(f"Contact list '{CONTACT_LIST_NAME}' does not exist.")
else:
print(e)
try:
self.ses_client.delete_email_identity(EmailIdentity=self.verified_email)
print(f"Email identity '{self.verified_email}' deleted successfully.")
except ClientError as e:
# If the email identity doesn't exist, skip and proceed
if e.response["Error"]["Code"] == "NotFoundException":
print(f"Email identity '{self.verified_email}' does not exist.")
else:
print(e)
try:
self.ses_client.delete_email_template(TemplateName=TEMPLATE_NAME)
print(f"Email template '{TEMPLATE_NAME}' deleted successfully.")
except ClientError as e:
# If the email template doesn't exist, skip and proceed
if e.response["Error"]["Code"] == "NotFoundException":
print(f"Email template '{TEMPLATE_NAME}' does not exist.")
else:
print(e)
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の以下のトピックを参照してください。
+ [CreateContact](https://docs.aws.amazon.com/goto/boto3/sesv2-2019-09-27/CreateContact)
+ [CreateContactList](https://docs.aws.amazon.com/goto/boto3/sesv2-2019-09-27/CreateContactList)
+ [CreateEmailIdentity](https://docs.aws.amazon.com/goto/boto3/sesv2-2019-09-27/CreateEmailIdentity)
+ [CreateEmailTemplate](https://docs.aws.amazon.com/goto/boto3/sesv2-2019-09-27/CreateEmailTemplate)
+ [DeleteContactList](https://docs.aws.amazon.com/goto/boto3/sesv2-2019-09-27/DeleteContactList)
+ [DeleteEmailIdentity](https://docs.aws.amazon.com/goto/boto3/sesv2-2019-09-27/DeleteEmailIdentity)
+ [DeleteEmailTemplate](https://docs.aws.amazon.com/goto/boto3/sesv2-2019-09-27/DeleteEmailTemplate)
+ [ListContacts](https://docs.aws.amazon.com/goto/boto3/sesv2-2019-09-27/ListContacts)
+ [SendEmail.simple](https://docs.aws.amazon.com/goto/boto3/sesv2-2019-09-27/SendEmail.simple)
+ [SendEmail.template](https://docs.aws.amazon.com/goto/boto3/sesv2-2019-09-27/SendEmail.template)
# SDK for Python (Boto3) を使用する Amazon SNS の例
次のコード例は、Amazon SNS AWS SDK for Python (Boto3) で を使用してアクションを実行し、一般的なシナリオを実装する方法を示しています。
*アクション*はより大きなプログラムからのコードの抜粋であり、コンテキスト内で実行する必要があります。アクションは個々のサービス機能を呼び出す方法を示していますが、コンテキスト内のアクションは、関連するシナリオで確認できます。
*シナリオ*は、1 つのサービス内から、または他の AWS のサービスと組み合わせて複数の関数を呼び出し、特定のタスクを実行する方法を示すコード例です。
各例には完全なソースコードへのリンクが含まれており、コードの設定方法と実行方法に関する手順を確認できます。
**Topics**
+ [アクション](#actions)
+ [シナリオ](#scenarios)
+ [サーバーレスサンプル](#serverless_examples)
## アクション
### `CreateTopic`
次のコード例は、`CreateTopic` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sns#code-examples)での設定と実行の方法を確認してください。
```
class SnsWrapper:
"""Encapsulates Amazon SNS topic and subscription functions."""
def __init__(self, sns_resource):
"""
:param sns_resource: A Boto3 Amazon SNS resource.
"""
self.sns_resource = sns_resource
def create_topic(self, name):
"""
Creates a notification topic.
:param name: The name of the topic to create.
:return: The newly created topic.
"""
try:
topic = self.sns_resource.create_topic(Name=name)
logger.info("Created topic %s with ARN %s.", name, topic.arn)
except ClientError:
logger.exception("Couldn't create topic %s.", name)
raise
else:
return topic
```
```
class SnsWrapper:
"""Wrapper class for managing Amazon SNS operations."""
def __init__(self, sns_client: Any) -> None:
"""
Initialize the SnsWrapper.
:param sns_client: A Boto3 Amazon SNS client.
"""
self.sns_client = sns_client
@classmethod
def from_client(cls) -> 'SnsWrapper':
"""
Create an SnsWrapper instance using a default boto3 client.
:return: An instance of this class.
"""
sns_client = boto3.client('sns')
return cls(sns_client)
def create_topic(
self,
topic_name: str,
is_fifo: bool = False,
content_based_deduplication: bool = False
) -> str:
"""
Create an SNS topic.
:param topic_name: The name of the topic to create.
:param is_fifo: Whether to create a FIFO topic.
:param content_based_deduplication: Whether to use content-based deduplication for FIFO topics.
:return: The ARN of the created topic.
:raises ClientError: If the topic creation fails.
"""
try:
# Add .fifo suffix for FIFO topics
if is_fifo and not topic_name.endswith('.fifo'):
topic_name += '.fifo'
attributes = {}
if is_fifo:
attributes['FifoTopic'] = 'true'
if content_based_deduplication:
attributes['ContentBasedDeduplication'] = 'true'
response = self.sns_client.create_topic(
Name=topic_name,
Attributes=attributes
)
topic_arn = response['TopicArn']
logger.info(f"Created topic: {topic_name} with ARN: {topic_arn}")
return topic_arn
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
logger.error(f"Error creating topic {topic_name}: {error_code} - {e}")
raise
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[CreateTopic](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/CreateTopic)」を参照してください。
### `DeleteTopic`
次のコード例は、`DeleteTopic` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sns#code-examples)での設定と実行の方法を確認してください。
```
class SnsWrapper:
"""Encapsulates Amazon SNS topic and subscription functions."""
def __init__(self, sns_resource):
"""
:param sns_resource: A Boto3 Amazon SNS resource.
"""
self.sns_resource = sns_resource
@staticmethod
def delete_topic(topic):
"""
Deletes a topic. All subscriptions to the topic are also deleted.
"""
try:
topic.delete()
logger.info("Deleted topic %s.", topic.arn)
except ClientError:
logger.exception("Couldn't delete topic %s.", topic.arn)
raise
```
```
class SnsWrapper:
"""Wrapper class for managing Amazon SNS operations."""
def __init__(self, sns_client: Any) -> None:
"""
Initialize the SnsWrapper.
:param sns_client: A Boto3 Amazon SNS client.
"""
self.sns_client = sns_client
@classmethod
def from_client(cls) -> 'SnsWrapper':
"""
Create an SnsWrapper instance using a default boto3 client.
:return: An instance of this class.
"""
sns_client = boto3.client('sns')
return cls(sns_client)
def delete_topic(self, topic_arn: str) -> bool:
"""
Delete an SNS topic.
:param topic_arn: The ARN of the topic to delete.
:return: True if successful.
:raises ClientError: If the topic deletion fails.
"""
try:
self.sns_client.delete_topic(TopicArn=topic_arn)
logger.info(f"Deleted topic: {topic_arn}")
return True
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
if error_code == 'NotFound':
logger.warning(f"Topic not found: {topic_arn}")
return True # Already deleted
else:
logger.error(f"Error deleting topic: {error_code} - {e}")
raise
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[DeleteTopic](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/DeleteTopic)」を参照してください。
### `ListSubscriptions`
次のコード例は、`ListSubscriptions` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sns#code-examples)での設定と実行の方法を確認してください。
```
class SnsWrapper:
"""Encapsulates Amazon SNS topic and subscription functions."""
def __init__(self, sns_resource):
"""
:param sns_resource: A Boto3 Amazon SNS resource.
"""
self.sns_resource = sns_resource
def list_subscriptions(self, topic=None):
"""
Lists subscriptions for the current account, optionally limited to a
specific topic.
:param topic: When specified, only subscriptions to this topic are returned.
:return: An iterator that yields the subscriptions.
"""
try:
if topic is None:
subs_iter = self.sns_resource.subscriptions.all()
else:
subs_iter = topic.subscriptions.all()
logger.info("Got subscriptions.")
except ClientError:
logger.exception("Couldn't get subscriptions.")
raise
else:
return subs_iter
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[ListSubscriptions](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/ListSubscriptions)」を参照してください。
### `ListTopics`
次のコード例は、`ListTopics` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sns#code-examples)での設定と実行の方法を確認してください。
```
class SnsWrapper:
"""Encapsulates Amazon SNS topic and subscription functions."""
def __init__(self, sns_resource):
"""
:param sns_resource: A Boto3 Amazon SNS resource.
"""
self.sns_resource = sns_resource
def list_topics(self):
"""
Lists topics for the current account.
:return: An iterator that yields the topics.
"""
try:
topics_iter = self.sns_resource.topics.all()
logger.info("Got topics.")
except ClientError:
logger.exception("Couldn't get topics.")
raise
else:
return topics_iter
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[ListTopics](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/ListTopics)」を参照してください。
### `Publish`
次のコード例は、`Publish` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sns#code-examples)での設定と実行の方法を確認してください。
サブスクリプションが属性に基づいてフィルター処理できるように、属性を含むメッセージを発行します。
```
class SnsWrapper:
"""Encapsulates Amazon SNS topic and subscription functions."""
def __init__(self, sns_resource):
"""
:param sns_resource: A Boto3 Amazon SNS resource.
"""
self.sns_resource = sns_resource
@staticmethod
def publish_message(topic, message, attributes):
"""
Publishes a message, with attributes, to a topic. Subscriptions can be filtered
based on message attributes so that a subscription receives messages only
when specified attributes are present.
:param topic: The topic to publish to.
:param message: The message to publish.
:param attributes: The key-value attributes to attach to the message. Values
must be either `str` or `bytes`.
:return: The ID of the message.
"""
try:
att_dict = {}
for key, value in attributes.items():
if isinstance(value, str):
att_dict[key] = {"DataType": "String", "StringValue": value}
elif isinstance(value, bytes):
att_dict[key] = {"DataType": "Binary", "BinaryValue": value}
response = topic.publish(Message=message, MessageAttributes=att_dict)
message_id = response["MessageId"]
logger.info(
"Published message with attributes %s to topic %s.",
attributes,
topic.arn,
)
except ClientError:
logger.exception("Couldn't publish message to topic %s.", topic.arn)
raise
else:
return message_id
```
サブスクライバーのプロトコルに基づいて異なる形式のメッセージを発行します。
```
class SnsWrapper:
"""Encapsulates Amazon SNS topic and subscription functions."""
def __init__(self, sns_resource):
"""
:param sns_resource: A Boto3 Amazon SNS resource.
"""
self.sns_resource = sns_resource
@staticmethod
def publish_multi_message(
topic, subject, default_message, sms_message, email_message
):
"""
Publishes a multi-format message to a topic. A multi-format message takes
different forms based on the protocol of the subscriber. For example,
an SMS subscriber might receive a short version of the message
while an email subscriber could receive a longer version.
:param topic: The topic to publish to.
:param subject: The subject of the message.
:param default_message: The default version of the message. This version is
sent to subscribers that have protocols that are not
otherwise specified in the structured message.
:param sms_message: The version of the message sent to SMS subscribers.
:param email_message: The version of the message sent to email subscribers.
:return: The ID of the message.
"""
try:
message = {
"default": default_message,
"sms": sms_message,
"email": email_message,
}
response = topic.publish(
Message=json.dumps(message), Subject=subject, MessageStructure="json"
)
message_id = response["MessageId"]
logger.info("Published multi-format message to topic %s.", topic.arn)
except ClientError:
logger.exception("Couldn't publish message to topic %s.", topic.arn)
raise
else:
return message_id
```
```
class SnsWrapper:
"""Wrapper class for managing Amazon SNS operations."""
def __init__(self, sns_client: Any) -> None:
"""
Initialize the SnsWrapper.
:param sns_client: A Boto3 Amazon SNS client.
"""
self.sns_client = sns_client
@classmethod
def from_client(cls) -> 'SnsWrapper':
"""
Create an SnsWrapper instance using a default boto3 client.
:return: An instance of this class.
"""
sns_client = boto3.client('sns')
return cls(sns_client)
def publish_message(
self,
topic_arn: str,
message: str,
tone_attribute: Optional[str] = None,
deduplication_id: Optional[str] = None,
message_group_id: Optional[str] = None
) -> str:
"""
Publish a message to an SNS topic.
:param topic_arn: The ARN of the SNS topic.
:param message: The message content to publish.
:param tone_attribute: Optional tone attribute for message filtering.
:param deduplication_id: Optional deduplication ID for FIFO topics.
:param message_group_id: Optional message group ID for FIFO topics.
:return: The message ID of the published message.
:raises ClientError: If the message publication fails.
"""
try:
publish_args = {
'TopicArn': topic_arn,
'Message': message
}
# Add message attributes if tone is specified
if tone_attribute:
publish_args['MessageAttributes'] = {
'tone': {
'DataType': 'String',
'StringValue': tone_attribute
}
}
# Add FIFO-specific parameters
if message_group_id:
publish_args['MessageGroupId'] = message_group_id
if deduplication_id:
publish_args['MessageDeduplicationId'] = deduplication_id
response = self.sns_client.publish(**publish_args)
message_id = response['MessageId']
logger.info(f"Published message to topic {topic_arn} with ID: {message_id}")
return message_id
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
logger.error(f"Error publishing message to topic: {error_code} - {e}")
raise
```
+ API の詳細については、**「AWS SDK for Python (Boto3) API リファレンス」の「[Publish](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/Publish)」を参照してください。
### `SetSubscriptionAttributes`
次のコード例は、`SetSubscriptionAttributes` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sns#code-examples)での設定と実行の方法を確認してください。
```
class SnsWrapper:
"""Encapsulates Amazon SNS topic and subscription functions."""
def __init__(self, sns_resource):
"""
:param sns_resource: A Boto3 Amazon SNS resource.
"""
self.sns_resource = sns_resource
@staticmethod
def add_subscription_filter(subscription, attributes):
"""
Adds a filter policy to a subscription. A filter policy is a key and a
list of values that are allowed. When a message is published, it must have an
attribute that passes the filter or it will not be sent to the subscription.
:param subscription: The subscription the filter policy is attached to.
:param attributes: A dictionary of key-value pairs that define the filter.
"""
try:
att_policy = {key: [value] for key, value in attributes.items()}
subscription.set_attributes(
AttributeName="FilterPolicy", AttributeValue=json.dumps(att_policy)
)
logger.info("Added filter to subscription %s.", subscription.arn)
except ClientError:
logger.exception(
"Couldn't add filter to subscription %s.", subscription.arn
)
raise
```
+ API の詳細については、**「AWS SDK for Python (Boto3) API リファレンス」の「[SetSubscriptionAttributes](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/SetSubscriptionAttributes)」を参照してください。
### `Subscribe`
次のコード例は、`Subscribe` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sns#code-examples)での設定と実行の方法を確認してください。
E メールアドレスをトピックにサブスクライブします。
```
class SnsWrapper:
"""Encapsulates Amazon SNS topic and subscription functions."""
def __init__(self, sns_resource):
"""
:param sns_resource: A Boto3 Amazon SNS resource.
"""
self.sns_resource = sns_resource
@staticmethod
def subscribe(topic, protocol, endpoint):
"""
Subscribes an endpoint to the topic. Some endpoint types, such as email,
must be confirmed before their subscriptions are active. When a subscription
is not confirmed, its Amazon Resource Number (ARN) is set to
'PendingConfirmation'.
:param topic: The topic to subscribe to.
:param protocol: The protocol of the endpoint, such as 'sms' or 'email'.
:param endpoint: The endpoint that receives messages, such as a phone number
(in E.164 format) for SMS messages, or an email address for
email messages.
:return: The newly added subscription.
"""
try:
subscription = topic.subscribe(
Protocol=protocol, Endpoint=endpoint, ReturnSubscriptionArn=True
)
logger.info("Subscribed %s %s to topic %s.", protocol, endpoint, topic.arn)
except ClientError:
logger.exception(
"Couldn't subscribe %s %s to topic %s.", protocol, endpoint, topic.arn
)
raise
else:
return subscription
```
オプションのフィルターでトピックにキューをサブスクライブします。
```
class SnsWrapper:
"""Wrapper class for managing Amazon SNS operations."""
def __init__(self, sns_client: Any) -> None:
"""
Initialize the SnsWrapper.
:param sns_client: A Boto3 Amazon SNS client.
"""
self.sns_client = sns_client
@classmethod
def from_client(cls) -> 'SnsWrapper':
"""
Create an SnsWrapper instance using a default boto3 client.
:return: An instance of this class.
"""
sns_client = boto3.client('sns')
return cls(sns_client)
def subscribe_queue_to_topic(
self,
topic_arn: str,
queue_arn: str,
filter_policy: Optional[str] = None
) -> str:
"""
Subscribe an SQS queue to an SNS topic.
:param topic_arn: The ARN of the SNS topic.
:param queue_arn: The ARN of the SQS queue.
:param filter_policy: Optional JSON filter policy for message filtering.
:return: The ARN of the subscription.
:raises ClientError: If the subscription fails.
"""
try:
attributes = {}
if filter_policy:
attributes['FilterPolicy'] = filter_policy
response = self.sns_client.subscribe(
TopicArn=topic_arn,
Protocol='sqs',
Endpoint=queue_arn,
Attributes=attributes
)
subscription_arn = response['SubscriptionArn']
logger.info(f"Subscribed queue {queue_arn} to topic {topic_arn}")
return subscription_arn
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
logger.error(f"Error subscribing queue to topic: {error_code} - {e}")
raise
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[Subscribe](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/Subscribe)」を参照してください。
### `Unsubscribe`
次のコード例は、`Unsubscribe` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sns#code-examples)での設定と実行の方法を確認してください。
```
class SnsWrapper:
"""Encapsulates Amazon SNS topic and subscription functions."""
def __init__(self, sns_resource):
"""
:param sns_resource: A Boto3 Amazon SNS resource.
"""
self.sns_resource = sns_resource
@staticmethod
def delete_subscription(subscription):
"""
Unsubscribes and deletes a subscription.
"""
try:
subscription.delete()
logger.info("Deleted subscription %s.", subscription.arn)
except ClientError:
logger.exception("Couldn't delete subscription %s.", subscription.arn)
raise
```
```
class SnsWrapper:
"""Wrapper class for managing Amazon SNS operations."""
def __init__(self, sns_client: Any) -> None:
"""
Initialize the SnsWrapper.
:param sns_client: A Boto3 Amazon SNS client.
"""
self.sns_client = sns_client
@classmethod
def from_client(cls) -> 'SnsWrapper':
"""
Create an SnsWrapper instance using a default boto3 client.
:return: An instance of this class.
"""
sns_client = boto3.client('sns')
return cls(sns_client)
def unsubscribe(self, subscription_arn: str) -> bool:
"""
Unsubscribe from an SNS topic.
:param subscription_arn: The ARN of the subscription to remove.
:return: True if successful.
:raises ClientError: If the unsubscribe operation fails.
"""
try:
self.sns_client.unsubscribe(SubscriptionArn=subscription_arn)
logger.info(f"Unsubscribed: {subscription_arn}")
return True
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
if error_code == 'NotFound':
logger.warning(f"Subscription not found: {subscription_arn}")
return True # Already unsubscribed
else:
logger.error(f"Error unsubscribing: {error_code} - {e}")
raise
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[Unsubscribe](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/Unsubscribe)」を参照してください。
## シナリオ
### Amazon Textract エクスプローラーアプリケーションを作成する
次のコード例は、インタラクティブアプリケーションで Amazon Textract の出力を調べる方法を示しています。
**SDK for Python (Boto3)**
Amazon Textract AWS SDK for Python (Boto3) で を使用して、ドキュメントイメージ内のテキスト、フォーム、テーブル要素を検出する方法を示します。入力イメージと Amazon Textract 出力は、検出された要素を探索できる Tkinter アプリケーションに表示されます。
+ Amazon Textract にドキュメントイメージを送信し、検出された要素の出力を調べます。
+ Amazon Textract に直接イメージを送信するか、Amazon Simple Storage Service (Amazon S3) バケットを通じてイメージを送信します。
+ 非同期 API を使用して、ジョブの完了時に Amazon Simple Notification Service (Amazon SNS) トピックに通知を発行するジョブを開始します。
+ Amazon Simple Queue Service (Amazon SQS) キューにジョブ完了メッセージについてポーリングし、結果を表示します。
完全なソースコードとセットアップおよび実行の手順については、[GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/textract_explorer) で完全な例を参照してください。
**この例で使用されているサービス**
+ Amazon Cognito ID
+ Amazon S3
+ Amazon SNS
+ Amazon SQS
+ Amazon Textract
### FIFO トピックを作成して発行する
次のコード例は、FIFO Amazon SNS トピックを作成、発行する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sns#code-examples)での設定と実行の方法を確認してください。
FIFO トピックを作成し、そのトピックに Amazon SQS FIFO キューと標準キューをサブスクライブして、メッセージを Amazon SNS トピックに発行します。
```
def usage_demo():
"""Shows how to subscribe queues to a FIFO topic."""
print("-" * 88)
print("Welcome to the `Subscribe queues to a FIFO topic` demo!")
print("-" * 88)
sns = boto3.resource("sns")
sqs = boto3.resource("sqs")
fifo_topic_wrapper = FifoTopicWrapper(sns)
sns_wrapper = SnsWrapper(sns)
prefix = "sqs-subscribe-demo-"
queues = set()
subscriptions = set()
wholesale_queue = sqs.create_queue(
QueueName=prefix + "wholesale.fifo",
Attributes={
"MaximumMessageSize": str(4096),
"ReceiveMessageWaitTimeSeconds": str(10),
"VisibilityTimeout": str(300),
"FifoQueue": str(True),
"ContentBasedDeduplication": str(True),
},
)
queues.add(wholesale_queue)
print(f"Created FIFO queue with URL: {wholesale_queue.url}.")
retail_queue = sqs.create_queue(
QueueName=prefix + "retail.fifo",
Attributes={
"MaximumMessageSize": str(4096),
"ReceiveMessageWaitTimeSeconds": str(10),
"VisibilityTimeout": str(300),
"FifoQueue": str(True),
"ContentBasedDeduplication": str(True),
},
)
queues.add(retail_queue)
print(f"Created FIFO queue with URL: {retail_queue.url}.")
analytics_queue = sqs.create_queue(QueueName=prefix + "analytics", Attributes={})
queues.add(analytics_queue)
print(f"Created standard queue with URL: {analytics_queue.url}.")
topic = fifo_topic_wrapper.create_fifo_topic("price-updates-topic.fifo")
print(f"Created FIFO topic: {topic.attributes['TopicArn']}.")
for q in queues:
fifo_topic_wrapper.add_access_policy(q, topic.attributes["TopicArn"])
print(f"Added access policies for topic: {topic.attributes['TopicArn']}.")
for q in queues:
sub = fifo_topic_wrapper.subscribe_queue_to_topic(
topic, q.attributes["QueueArn"]
)
subscriptions.add(sub)
print(f"Subscribed queues to topic: {topic.attributes['TopicArn']}.")
input("Press Enter to publish a message to the topic.")
message_id = fifo_topic_wrapper.publish_price_update(
topic, '{"product": 214, "price": 79.99}', "Consumables"
)
print(f"Published price update with message ID: {message_id}.")
# Clean up the subscriptions, queues, and topic.
input("Press Enter to clean up resources.")
for s in subscriptions:
sns_wrapper.delete_subscription(s)
sns_wrapper.delete_topic(topic)
for q in queues:
fifo_topic_wrapper.delete_queue(q)
print(f"Deleted subscriptions, queues, and topic.")
print("Thanks for watching!")
print("-" * 88)
class FifoTopicWrapper:
"""Encapsulates Amazon SNS FIFO topic and subscription functions."""
def __init__(self, sns_resource):
"""
:param sns_resource: A Boto3 Amazon SNS resource.
"""
self.sns_resource = sns_resource
def create_fifo_topic(self, topic_name):
"""
Create a FIFO topic.
Topic names must be made up of only uppercase and lowercase ASCII letters,
numbers, underscores, and hyphens, and must be between 1 and 256 characters long.
For a FIFO topic, the name must end with the .fifo suffix.
:param topic_name: The name for the topic.
:return: The new topic.
"""
try:
topic = self.sns_resource.create_topic(
Name=topic_name,
Attributes={
"FifoTopic": str(True),
"ContentBasedDeduplication": str(False),
"FifoThroughputScope": "MessageGroup",
},
)
logger.info("Created FIFO topic with name=%s.", topic_name)
return topic
except ClientError as error:
logger.exception("Couldn't create topic with name=%s!", topic_name)
raise error
@staticmethod
def add_access_policy(queue, topic_arn):
"""
Add the necessary access policy to a queue, so
it can receive messages from a topic.
:param queue: The queue resource.
:param topic_arn: The ARN of the topic.
:return: None.
"""
try:
queue.set_attributes(
Attributes={
"Policy": json.dumps(
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "test-sid",
"Effect": "Allow",
"Principal": {"AWS": "*"},
"Action": "SQS:SendMessage",
"Resource": queue.attributes["QueueArn"],
"Condition": {
"ArnLike": {"aws:SourceArn": topic_arn}
},
}
],
}
)
}
)
logger.info("Added trust policy to the queue.")
except ClientError as error:
logger.exception("Couldn't add trust policy to the queue!")
raise error
@staticmethod
def subscribe_queue_to_topic(topic, queue_arn):
"""
Subscribe a queue to a topic.
:param topic: The topic resource.
:param queue_arn: The ARN of the queue.
:return: The subscription resource.
"""
try:
subscription = topic.subscribe(
Protocol="sqs",
Endpoint=queue_arn,
)
logger.info("The queue is subscribed to the topic.")
return subscription
except ClientError as error:
logger.exception("Couldn't subscribe queue to topic!")
raise error
@staticmethod
def publish_price_update(topic, payload, group_id):
"""
Compose and publish a message that updates the wholesale price.
:param topic: The topic to publish to.
:param payload: The message to publish.
:param group_id: The group ID for the message.
:return: The ID of the message.
"""
try:
att_dict = {"business": {"DataType": "String", "StringValue": "wholesale"}}
dedup_id = uuid.uuid4()
response = topic.publish(
Subject="Price Update",
Message=payload,
MessageAttributes=att_dict,
MessageGroupId=group_id,
MessageDeduplicationId=str(dedup_id),
)
message_id = response["MessageId"]
logger.info("Published message to topic %s.", topic.arn)
except ClientError as error:
logger.exception("Couldn't publish message to topic %s.", topic.arn)
raise error
return message_id
@staticmethod
def delete_queue(queue):
"""
Removes an SQS queue. When run against an AWS account, it can take up to
60 seconds before the queue is actually deleted.
:param queue: The queue to delete.
:return: None
"""
try:
queue.delete()
logger.info("Deleted queue with URL=%s.", queue.url)
except ClientError as error:
logger.exception("Couldn't delete queue with URL=%s!", queue.url)
raise error
```
+ API の詳細については、「**AWS SDK for Python (Boto3) API リファレンス」の以下のトピックを参照してください。
+ [CreateTopic](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/CreateTopic)
+ [Publish](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/Publish)
+ [Subscribe](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/Subscribe)
### 動画内の人物や物体を検出する
次のコード例は、Amazon Rekognition で動画内の人やオブジェクトを検出する方法を示します。
**SDK for Python (Boto3)**
Amazon Rekognition を使用して、非同期検出ジョブを開始して、動画内の顔、オブジェクト、人を検出します。この例では、ジョブが完了し、Amazon Simple Queue Service (Amazon SQS) キューをトピックにサブスクライブしたときに、Amazon Simple Notification Service (Amazon SNS) トピックに通知するように Amazon Rekognition を設定します。キューがジョブに関するメッセージを受信すると、ジョブが取得され、結果が出力されます。
この例は GitHub で最もよく見られます。完全なソースコードとセットアップおよび実行の手順については、[GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rekognition) で完全な例を参照してください。
**この例で使用されているサービス**
+ Amazon Rekognition
+ Amazon S3
+ Amazon SES
+ Amazon SNS
+ Amazon SQS
### SMS テキストメッセージを発行する
次のコードサンプルは、Amazon SNS を使用して SMS メッセージを発行する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sns#code-examples)での設定と実行の方法を確認してください。
```
class SnsWrapper:
"""Encapsulates Amazon SNS topic and subscription functions."""
def __init__(self, sns_resource):
"""
:param sns_resource: A Boto3 Amazon SNS resource.
"""
self.sns_resource = sns_resource
def publish_text_message(self, phone_number, message):
"""
Publishes a text message directly to a phone number without need for a
subscription.
:param phone_number: The phone number that receives the message. This must be
in E.164 format. For example, a United States phone
number might be +12065550101.
:param message: The message to send.
:return: The ID of the message.
"""
try:
response = self.sns_resource.meta.client.publish(
PhoneNumber=phone_number, Message=message
)
message_id = response["MessageId"]
logger.info("Published message to %s.", phone_number)
except ClientError:
logger.exception("Couldn't publish message to %s.", phone_number)
raise
else:
return message_id
```
+ API の詳細については、**「AWS SDK for Python (Boto3) API リファレンス」の「[Publish](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/Publish)」を参照してください。
### メッセージをキューに発行する
次のコード例は、以下の操作方法を示しています。
+ トピック (FIFO または非 FIFO) を作成します。
+ フィルターを適用するオプションを使用して、複数のキューをトピックにサブスクライブします。
+ メッセージをトピックに発行します。
+ 受信したメッセージのキューをポーリングします。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/topics_and_queues#code-examples)での設定と実行の方法を確認してください。
コマンドプロンプトからインタラクティブなシナリオを実行します。
```
class TopicsAndQueuesScenario:
"""Manages the Topics and Queues feature scenario."""
DASHES = "-" * 80
def __init__(self, sns_wrapper: SnsWrapper, sqs_wrapper: SqsWrapper) -> None:
"""
Initialize the Topics and Queues scenario.
:param sns_wrapper: SnsWrapper instance for SNS operations.
:param sqs_wrapper: SqsWrapper instance for SQS operations.
"""
self.sns_wrapper = sns_wrapper
self.sqs_wrapper = sqs_wrapper
# Scenario state
self.use_fifo_topic = False
self.use_content_based_deduplication = False
self.topic_name = None
self.topic_arn = None
self.queue_count = 2
self.queue_urls = []
self.subscription_arns = []
self.tones = ["cheerful", "funny", "serious", "sincere"]
def run_scenario(self) -> None:
"""Run the Topics and Queues feature scenario."""
print(self.DASHES)
print("Welcome to messaging with topics and queues.")
print(self.DASHES)
print(f"""
In this scenario, you will create an SNS topic and subscribe {self.queue_count} SQS queues to the topic.
You can select from several options for configuring the topic and the subscriptions for the queues.
You can then post to the topic and see the results in the queues.
""")
try:
# Setup Phase
print(self.DASHES)
self._setup_topic()
print(self.DASHES)
self._setup_queues()
print(self.DASHES)
# Demonstration Phase
self._publish_messages()
print(self.DASHES)
# Examination Phase
self._poll_queues_for_messages()
print(self.DASHES)
# Cleanup Phase
self._cleanup_resources()
print(self.DASHES)
except Exception as e:
logger.error(f"Scenario failed: {e}")
print(f"There was a problem with the scenario: {e}")
print("\nInitiating cleanup...")
try:
self._cleanup_resources()
except Exception as cleanup_error:
logger.error(f"Error during cleanup: {cleanup_error}")
print("Messaging with topics and queues scenario is complete.")
print(self.DASHES)
def _setup_topic(self) -> None:
"""Set up the SNS topic to be used with the queues."""
print("SNS topics can be configured as FIFO (First-In-First-Out).")
print("FIFO topics deliver messages in order and support deduplication and message filtering.")
print()
self.use_fifo_topic = q.ask("Would you like to work with FIFO topics? (y/n): ", q.is_yesno)
if self.use_fifo_topic:
print(self.DASHES)
self.topic_name = q.ask("Enter a name for your SNS topic: ", q.non_empty)
print("Because you have selected a FIFO topic, '.fifo' must be appended to the topic name.")
print()
print(self.DASHES)
print("""
Because you have chosen a FIFO topic, deduplication is supported.
Deduplication IDs are either set in the message or automatically generated
from content using a hash function.
If a message is successfully published to an SNS FIFO topic, any message
published and determined to have the same deduplication ID,
within the five-minute deduplication interval, is accepted but not delivered.
For more information about deduplication,
see https://docs.aws.amazon.com/sns/latest/dg/fifo-message-dedup.html.
""")
self.use_content_based_deduplication = q.ask(
"Use content-based deduplication instead of entering a deduplication ID? (y/n): ",
q.is_yesno
)
else:
self.topic_name = q.ask("Enter a name for your SNS topic: ", q.non_empty)
print(self.DASHES)
# Create the topic
self.topic_arn = self.sns_wrapper.create_topic(
self.topic_name,
self.use_fifo_topic,
self.use_content_based_deduplication
)
print(f"Your new topic with the name {self.topic_name}")
print(f" and Amazon Resource Name (ARN) {self.topic_arn}")
print(f" has been created.")
print()
def _setup_queues(self) -> None:
"""Set up the SQS queues and subscribe them to the topic."""
print(f"Now you will create {self.queue_count} Amazon Simple Queue Service (Amazon SQS) queues to subscribe to the topic.")
for i in range(self.queue_count):
queue_name = q.ask(f"Enter a name for SQS queue #{i+1}: ", q.non_empty)
if self.use_fifo_topic and i == 0:
print("Because you have selected a FIFO topic, '.fifo' must be appended to the queue name.")
# Create the queue
queue_url = self.sqs_wrapper.create_queue(queue_name, self.use_fifo_topic)
self.queue_urls.append(queue_url)
print(f"Your new queue with the name {queue_name}")
print(f" and queue URL {queue_url}")
print(f" has been created.")
print()
if i == 0:
print("The queue URL is used to retrieve the queue ARN,")
print("which is used to create a subscription.")
print(self.DASHES)
# Get queue ARN
queue_arn = self.sqs_wrapper.get_queue_arn(queue_url)
if i == 0:
print("An AWS Identity and Access Management (IAM) policy must be attached to an SQS queue,")
print("enabling it to receive messages from an SNS topic.")
# Set queue policy to allow SNS to send messages
self.sqs_wrapper.set_queue_policy_for_topic(queue_arn, self.topic_arn, queue_url)
# Set up message filtering if using FIFO
subscription_arn = self._setup_subscription_with_filter(i, queue_arn, queue_name)
self.subscription_arns.append(subscription_arn)
def _setup_subscription_with_filter(self, queue_index: int, queue_arn: str, queue_name: str) -> str:
"""Set up subscription with optional message filtering."""
filter_policy = None
if self.use_fifo_topic:
print(self.DASHES)
if queue_index == 0:
print("Subscriptions to a FIFO topic can have filters.")
print("If you add a filter to this subscription, then only the filtered messages")
print("will be received in the queue.")
print()
print("For information about message filtering,")
print("see https://docs.aws.amazon.com/sns/latest/dg/sns-message-filtering.html")
print()
print("For this example, you can filter messages by a TONE attribute.")
use_filter = q.ask(f"Filter messages for {queue_name}'s subscription to the topic? (y/n): ", q.is_yesno)
if use_filter:
filter_policy = self._create_filter_policy()
subscription_arn = self.sns_wrapper.subscribe_queue_to_topic(
self.topic_arn, queue_arn, filter_policy
)
print(f"The queue {queue_name} has been subscribed to the topic {self.topic_name}")
print(f" with the subscription ARN {subscription_arn}")
return subscription_arn
def _create_filter_policy(self) -> str:
"""Create a message filter policy based on user selections."""
print(self.DASHES)
print("You can filter messages by one or more of the following TONE attributes.")
filter_selections = []
selection_number = 0
while True:
print("Enter a number to add a TONE filter, or enter 0 to stop adding filters.")
for i, tone in enumerate(self.tones, 1):
print(f" {i}. {tone}")
selection = q.ask("Your choice: ", q.is_int, q.in_range(0, len(self.tones)))
if selection == 0:
break
elif selection > 0 and self.tones[selection - 1] not in filter_selections:
filter_selections.append(self.tones[selection - 1])
print(f"Added '{self.tones[selection - 1]}' to filter list.")
if filter_selections:
filters = {"tone": filter_selections}
return json.dumps(filters)
return None
def _publish_messages(self) -> None:
"""Publish messages to the topic with various options."""
print("Now we can publish messages.")
keep_sending = True
while keep_sending:
print()
message = q.ask("Enter a message to publish: ", q.non_empty)
message_group_id = None
deduplication_id = None
tone_attribute = None
if self.use_fifo_topic:
print("Because you are using a FIFO topic, you must set a message group ID.")
print("All messages within the same group will be received in the order they were published.")
print()
message_group_id = q.ask("Enter a message group ID for this message: ", q.non_empty)
if not self.use_content_based_deduplication:
print("Because you are not using content-based deduplication,")
print("you must enter a deduplication ID.")
deduplication_id = q.ask("Enter a deduplication ID for this message: ", q.non_empty)
# Ask about tone attribute
add_attribute = q.ask("Add an attribute to this message? (y/n): ", q.is_yesno)
if add_attribute:
print("Enter a number for an attribute:")
for i, tone in enumerate(self.tones, 1):
print(f" {i}. {tone}")
selection = q.ask("Your choice: ", q.is_int, q.in_range(1, len(self.tones)))
if 1 <= selection <= len(self.tones):
tone_attribute = self.tones[selection - 1]
# Publish the message
message_id = self.sns_wrapper.publish_message(
self.topic_arn,
message,
tone_attribute,
deduplication_id,
message_group_id
)
print(f"Message published with ID: {message_id}")
keep_sending = q.ask("Send another message? (y/n): ", q.is_yesno)
def _poll_queues_for_messages(self) -> None:
"""Poll all queues for messages and display results."""
for i, queue_url in enumerate(self.queue_urls):
print(f"Polling queue #{i+1} at {queue_url} for messages...")
q.ask("Press Enter to continue...")
messages = self._poll_queue_for_messages(queue_url)
if messages:
print(f"{len(messages)} message(s) were received by queue #{i+1}")
for j, message in enumerate(messages, 1):
print(f" Message {j}:")
# Parse the SNS message body to get the actual message
try:
sns_message = json.loads(message['Body'])
actual_message = sns_message.get('Message', message['Body'])
print(f" {actual_message}")
except (json.JSONDecodeError, KeyError):
print(f" {message['Body']}")
# Delete the messages
self.sqs_wrapper.delete_messages(queue_url, messages)
print(f"Messages deleted from queue #{i+1}")
else:
print(f"No messages received by queue #{i+1}")
print(self.DASHES)
def _poll_queue_for_messages(self, queue_url: str) -> List[Dict[str, Any]]:
"""Poll a single queue for messages."""
all_messages = []
max_polls = 3 # Limit polling to avoid infinite loops
for poll_count in range(max_polls):
messages = self.sqs_wrapper.receive_messages(queue_url, 10)
if messages:
all_messages.extend(messages)
print(f" Received {len(messages)} messages in poll {poll_count + 1}")
# Small delay between polls
time.sleep(1)
else:
print(f" No messages in poll {poll_count + 1}")
break
return all_messages
def _cleanup_resources(self) -> None:
"""Clean up all resources created during the scenario."""
print("Cleaning up resources...")
# Delete queues
for i, queue_url in enumerate(self.queue_urls):
if queue_url:
delete_queue = q.ask(f"Delete queue #{i+1} with URL {queue_url}? (y/n): ", q.is_yesno)
if delete_queue:
try:
self.sqs_wrapper.delete_queue(queue_url)
print(f"Deleted queue #{i+1}")
except Exception as e:
print(f"Error deleting queue #{i+1}: {e}")
# Unsubscribe from topic
for i, subscription_arn in enumerate(self.subscription_arns):
if subscription_arn:
try:
self.sns_wrapper.unsubscribe(subscription_arn)
print(f"Unsubscribed subscription #{i+1}")
except Exception as e:
print(f"Error unsubscribing #{i+1}: {e}")
# Delete topic
if self.topic_arn:
delete_topic = q.ask(f"Delete topic {self.topic_name}? (y/n): ", q.is_yesno)
if delete_topic:
try:
self.sns_wrapper.delete_topic(self.topic_arn)
print(f"Deleted topic {self.topic_name}")
except Exception as e:
print(f"Error deleting topic: {e}")
print("Resource cleanup complete.")
```
シナリオで使用する Amazon SNS および Amazon SQS オペレーションをラップするクラスを作成します。
```
class SnsWrapper:
"""Wrapper class for managing Amazon SNS operations."""
def __init__(self, sns_client: Any) -> None:
"""
Initialize the SnsWrapper.
:param sns_client: A Boto3 Amazon SNS client.
"""
self.sns_client = sns_client
@classmethod
def from_client(cls) -> 'SnsWrapper':
"""
Create an SnsWrapper instance using a default boto3 client.
:return: An instance of this class.
"""
sns_client = boto3.client('sns')
return cls(sns_client)
def create_topic(
self,
topic_name: str,
is_fifo: bool = False,
content_based_deduplication: bool = False
) -> str:
"""
Create an SNS topic.
:param topic_name: The name of the topic to create.
:param is_fifo: Whether to create a FIFO topic.
:param content_based_deduplication: Whether to use content-based deduplication for FIFO topics.
:return: The ARN of the created topic.
:raises ClientError: If the topic creation fails.
"""
try:
# Add .fifo suffix for FIFO topics
if is_fifo and not topic_name.endswith('.fifo'):
topic_name += '.fifo'
attributes = {}
if is_fifo:
attributes['FifoTopic'] = 'true'
if content_based_deduplication:
attributes['ContentBasedDeduplication'] = 'true'
response = self.sns_client.create_topic(
Name=topic_name,
Attributes=attributes
)
topic_arn = response['TopicArn']
logger.info(f"Created topic: {topic_name} with ARN: {topic_arn}")
return topic_arn
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
logger.error(f"Error creating topic {topic_name}: {error_code} - {e}")
raise
def subscribe_queue_to_topic(
self,
topic_arn: str,
queue_arn: str,
filter_policy: Optional[str] = None
) -> str:
"""
Subscribe an SQS queue to an SNS topic.
:param topic_arn: The ARN of the SNS topic.
:param queue_arn: The ARN of the SQS queue.
:param filter_policy: Optional JSON filter policy for message filtering.
:return: The ARN of the subscription.
:raises ClientError: If the subscription fails.
"""
try:
attributes = {}
if filter_policy:
attributes['FilterPolicy'] = filter_policy
response = self.sns_client.subscribe(
TopicArn=topic_arn,
Protocol='sqs',
Endpoint=queue_arn,
Attributes=attributes
)
subscription_arn = response['SubscriptionArn']
logger.info(f"Subscribed queue {queue_arn} to topic {topic_arn}")
return subscription_arn
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
logger.error(f"Error subscribing queue to topic: {error_code} - {e}")
raise
def publish_message(
self,
topic_arn: str,
message: str,
tone_attribute: Optional[str] = None,
deduplication_id: Optional[str] = None,
message_group_id: Optional[str] = None
) -> str:
"""
Publish a message to an SNS topic.
:param topic_arn: The ARN of the SNS topic.
:param message: The message content to publish.
:param tone_attribute: Optional tone attribute for message filtering.
:param deduplication_id: Optional deduplication ID for FIFO topics.
:param message_group_id: Optional message group ID for FIFO topics.
:return: The message ID of the published message.
:raises ClientError: If the message publication fails.
"""
try:
publish_args = {
'TopicArn': topic_arn,
'Message': message
}
# Add message attributes if tone is specified
if tone_attribute:
publish_args['MessageAttributes'] = {
'tone': {
'DataType': 'String',
'StringValue': tone_attribute
}
}
# Add FIFO-specific parameters
if message_group_id:
publish_args['MessageGroupId'] = message_group_id
if deduplication_id:
publish_args['MessageDeduplicationId'] = deduplication_id
response = self.sns_client.publish(**publish_args)
message_id = response['MessageId']
logger.info(f"Published message to topic {topic_arn} with ID: {message_id}")
return message_id
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
logger.error(f"Error publishing message to topic: {error_code} - {e}")
raise
def unsubscribe(self, subscription_arn: str) -> bool:
"""
Unsubscribe from an SNS topic.
:param subscription_arn: The ARN of the subscription to remove.
:return: True if successful.
:raises ClientError: If the unsubscribe operation fails.
"""
try:
self.sns_client.unsubscribe(SubscriptionArn=subscription_arn)
logger.info(f"Unsubscribed: {subscription_arn}")
return True
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
if error_code == 'NotFound':
logger.warning(f"Subscription not found: {subscription_arn}")
return True # Already unsubscribed
else:
logger.error(f"Error unsubscribing: {error_code} - {e}")
raise
def delete_topic(self, topic_arn: str) -> bool:
"""
Delete an SNS topic.
:param topic_arn: The ARN of the topic to delete.
:return: True if successful.
:raises ClientError: If the topic deletion fails.
"""
try:
self.sns_client.delete_topic(TopicArn=topic_arn)
logger.info(f"Deleted topic: {topic_arn}")
return True
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
if error_code == 'NotFound':
logger.warning(f"Topic not found: {topic_arn}")
return True # Already deleted
else:
logger.error(f"Error deleting topic: {error_code} - {e}")
raise
def list_topics(self) -> list:
"""
List all SNS topics in the account using pagination.
:return: List of topic ARNs.
:raises ClientError: If listing topics fails.
"""
try:
topics = []
paginator = self.sns_client.get_paginator('list_topics')
for page in paginator.paginate():
topics.extend([topic['TopicArn'] for topic in page.get('Topics', [])])
logger.info(f"Found {len(topics)} topics")
return topics
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
if error_code == 'AuthorizationError':
logger.error("Authorization error listing topics - check IAM permissions")
else:
logger.error(f"Error listing topics: {error_code} - {e}")
raise
class SqsWrapper:
"""Wrapper class for managing Amazon SQS operations."""
def __init__(self, sqs_client: Any) -> None:
"""
Initialize the SqsWrapper.
:param sqs_client: A Boto3 Amazon SQS client.
"""
self.sqs_client = sqs_client
@classmethod
def from_client(cls) -> 'SqsWrapper':
"""
Create an SqsWrapper instance using a default boto3 client.
:return: An instance of this class.
"""
sqs_client = boto3.client('sqs')
return cls(sqs_client)
def create_queue(self, queue_name: str, is_fifo: bool = False) -> str:
"""
Create an SQS queue.
:param queue_name: The name of the queue to create.
:param is_fifo: Whether to create a FIFO queue.
:return: The URL of the created queue.
:raises ClientError: If the queue creation fails.
"""
try:
# Add .fifo suffix for FIFO queues
if is_fifo and not queue_name.endswith('.fifo'):
queue_name += '.fifo'
attributes = {}
if is_fifo:
attributes['FifoQueue'] = 'true'
response = self.sqs_client.create_queue(
QueueName=queue_name,
Attributes=attributes
)
queue_url = response['QueueUrl']
logger.info(f"Created queue: {queue_name} with URL: {queue_url}")
return queue_url
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
logger.error(f"Error creating queue {queue_name}: {error_code} - {e}")
raise
def get_queue_arn(self, queue_url: str) -> str:
"""
Get the ARN of an SQS queue.
:param queue_url: The URL of the queue.
:return: The ARN of the queue.
:raises ClientError: If getting queue attributes fails.
"""
try:
response = self.sqs_client.get_queue_attributes(
QueueUrl=queue_url,
AttributeNames=['QueueArn']
)
queue_arn = response['Attributes']['QueueArn']
logger.info(f"Queue ARN for {queue_url}: {queue_arn}")
return queue_arn
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
logger.error(f"Error getting queue ARN: {error_code} - {e}")
raise
def set_queue_policy_for_topic(self, queue_arn: str, topic_arn: str, queue_url: str) -> bool:
"""
Set the queue policy to allow SNS to send messages to the queue.
:param queue_arn: The ARN of the SQS queue.
:param topic_arn: The ARN of the SNS topic.
:param queue_url: The URL of the SQS queue.
:return: True if successful.
:raises ClientError: If setting the queue policy fails.
"""
try:
# Create policy that allows SNS to send messages to the queue
policy = {
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "sns.amazonaws.com"
},
"Action": "sqs:SendMessage",
"Resource": queue_arn,
"Condition": {
"ArnEquals": {
"aws:SourceArn": topic_arn
}
}
}
]
}
self.sqs_client.set_queue_attributes(
QueueUrl=queue_url,
Attributes={
'Policy': json.dumps(policy)
}
)
logger.info(f"Set queue policy for {queue_url} to allow messages from {topic_arn}")
return True
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
logger.error(f"Error setting queue policy: {error_code} - {e}")
raise
def receive_messages(self, queue_url: str, max_messages: int = 10) -> List[Dict[str, Any]]:
"""
Receive messages from an SQS queue.
:param queue_url: The URL of the queue to receive messages from.
:param max_messages: Maximum number of messages to receive (1-10).
:return: List of received messages.
:raises ClientError: If receiving messages fails.
"""
try:
# Ensure max_messages is within valid range
max_messages = max(1, min(10, max_messages))
response = self.sqs_client.receive_message(
QueueUrl=queue_url,
MaxNumberOfMessages=max_messages,
WaitTimeSeconds=2, # Short polling
MessageAttributeNames=['All']
)
messages = response.get('Messages', [])
logger.info(f"Received {len(messages)} messages from {queue_url}")
return messages
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
logger.error(f"Error receiving messages: {error_code} - {e}")
raise
def delete_messages(self, queue_url: str, messages: List[Dict[str, Any]]) -> bool:
"""
Delete messages from an SQS queue in batches.
:param queue_url: The URL of the queue.
:param messages: List of messages to delete.
:return: True if successful.
:raises ClientError: If deleting messages fails.
"""
try:
if not messages:
return True
# Build delete entries for batch delete
delete_entries = []
for i, message in enumerate(messages):
delete_entries.append({
'Id': str(i),
'ReceiptHandle': message['ReceiptHandle']
})
# Delete messages in batches of 10 (SQS limit)
batch_size = 10
for i in range(0, len(delete_entries), batch_size):
batch = delete_entries[i:i + batch_size]
response = self.sqs_client.delete_message_batch(
QueueUrl=queue_url,
Entries=batch
)
# Check for failures
if 'Failed' in response and response['Failed']:
for failed in response['Failed']:
logger.warning(f"Failed to delete message: {failed}")
logger.info(f"Deleted {len(messages)} messages from {queue_url}")
return True
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
logger.error(f"Error deleting messages: {error_code} - {e}")
raise
def delete_queue(self, queue_url: str) -> bool:
"""
Delete an SQS queue.
:param queue_url: The URL of the queue to delete.
:return: True if successful.
:raises ClientError: If the queue deletion fails.
"""
try:
self.sqs_client.delete_queue(QueueUrl=queue_url)
logger.info(f"Deleted queue: {queue_url}")
return True
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
if error_code == 'AWS.SimpleQueueService.NonExistentQueue':
logger.warning(f"Queue not found: {queue_url}")
return True # Already deleted
else:
logger.error(f"Error deleting queue: {error_code} - {e}")
raise
def list_queues(self, queue_name_prefix: Optional[str] = None) -> List[str]:
"""
List all SQS queues in the account using pagination.
:param queue_name_prefix: Optional prefix to filter queue names.
:return: List of queue URLs.
:raises ClientError: If listing queues fails.
"""
try:
queue_urls = []
paginator = self.sqs_client.get_paginator('list_queues')
page_params = {}
if queue_name_prefix:
page_params['QueueNamePrefix'] = queue_name_prefix
for page in paginator.paginate(**page_params):
queue_urls.extend(page.get('QueueUrls', []))
logger.info(f"Found {len(queue_urls)} queues")
return queue_urls
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
if error_code == 'AccessDenied':
logger.error("Access denied listing queues - check IAM permissions")
else:
logger.error(f"Error listing queues: {error_code} - {e}")
raise
def send_message(self, queue_url: str, message_body: str, **kwargs) -> str:
"""
Send a message to an SQS queue.
:param queue_url: The URL of the queue.
:param message_body: The message content.
:param kwargs: Additional message parameters (DelaySeconds, MessageAttributes, etc.).
:return: The message ID.
:raises ClientError: If sending the message fails.
"""
try:
send_params = {
'QueueUrl': queue_url,
'MessageBody': message_body,
**kwargs
}
response = self.sqs_client.send_message(**send_params)
message_id = response['MessageId']
logger.info(f"Sent message to {queue_url} with ID: {message_id}")
return message_id
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
logger.error(f"Error sending message: {error_code} - {e}")
raise
```
+ API の詳細については、「**AWS SDK for Python (Boto3) API リファレンス」の以下のトピックを参照してください。
+ [CreateQueue](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/CreateQueue)
+ [CreateTopic](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/CreateTopic)
+ [DeleteMessageBatch](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/DeleteMessageBatch)
+ [DeleteQueue](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/DeleteQueue)
+ [DeleteTopic](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/DeleteTopic)
+ [GetQueueAttributes](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/GetQueueAttributes)
+ [Publish](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/Publish)
+ [ReceiveMessage](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/ReceiveMessage)
+ [SetQueueAttributes](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/SetQueueAttributes)
+ [Subscribe](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/Subscribe)
+ [Unsubscribe](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/Unsubscribe)
### API Gateway を使用して Lambda 関数を呼び出す
次のコード例は、Amazon API Gateway によって呼び出される AWS Lambda 関数を作成する方法を示しています。
**SDK for Python (Boto3)**
この例は、 AWS Lambda 関数を対象とする Amazon API Gateway REST API を作成して使用する方法を示しています。Lambda ハンドラーは、HTTP メソッドに基づいてルーティングする方法を示します。クエリ文字列、ヘッダー、および本文からデータを取得する方法。そして、JSON 応答を返す方法。
+ Lambda 関数をデプロイします。
+ API ゲートウェイ REST API を作成します。
+ Lambda 関数をターゲットとする REST リソースを作成します。
+ API Gateway に Lambda 関数を呼び出す権限を付与します。
+ リクエストパッケージを使用して、REST API にリクエストを送信します。
+ デモ中に作成されたすべてのリソースをクリーンアップします。
この例は GitHub で最もよく確認できます。完全なソースコードとセットアップおよび実行の手順については、[GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/lambda#readme) で完全な例を参照してください。
**この例で使用されているサービス**
+ API ゲートウェイ
+ DynamoDB
+ Lambda
+ Amazon SNS
### スケジュールされたイベントを使用した Lambda 関数の呼び出し
次のコード例は、Amazon EventBridge スケジュールされたイベントによって呼び出される AWS Lambda 関数を作成する方法を示しています。
**SDK for Python (Boto3)**
この例では、スケジュールされた Amazon EventBridge イベントのターゲットとして AWS Lambda 関数を登録する方法を示します。Lambda ハンドラーは、後で取得するために Amazon CloudWatch Logs にわかりやすいメッセージと完全なイベントデータを書き込みます。
+ Lambda 関数をデプロイします。
+ EventBridge スケジュールイベントを作成し、Lambda 関数をターゲットにします。
+ EventBridge に Lambda 関数を呼び出す許可を付与します
+ CloudWatch Logs から最新のデータを出力して、スケジュールされた呼び出しの結果を表示しています。
+ デモ中に作成されたすべてのリソースをクリーンアップします。
この例は GitHub で最もよく確認できます。完全なソースコードとセットアップおよび実行の手順については、[GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/lambda#readme) で完全な例を参照してください。
**この例で使用されているサービス**
+ CloudWatch Logs
+ DynamoDB
+ EventBridge
+ Lambda
+ Amazon SNS
## サーバーレスサンプル
### Amazon SNS トリガーから Lambda 関数を呼び出す
次のコード例は、SNS トピックからメッセージを受信することによってトリガーされるイベントを受け取る Lambda 関数を実装する方法を示しています。この関数はイベントパラメータからメッセージを取得し、各メッセージの内容を記録します。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。[サーバーレスサンプル](https://github.com/aws-samples/serverless-snippets/tree/main/integration-sns-to-lambda)リポジトリで完全な例を見つけて、設定と実行の方法を確認してください。
Python を使用して Lambda で SNS イベントを消費します。
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
def lambda_handler(event, context):
for record in event['Records']:
process_message(record)
print("done")
def process_message(record):
try:
message = record['Sns']['Message']
print(f"Processed message {message}")
# TODO; Process your record here
except Exception as e:
print("An error occurred")
raise e
```
# SDK for Python (Boto3) を使用する Amazon SQS の例
次のコード例は、Amazon SQS AWS SDK for Python (Boto3) で を使用してアクションを実行し、一般的なシナリオを実装する方法を示しています。
*アクション*はより大きなプログラムからのコードの抜粋であり、コンテキスト内で実行する必要があります。アクションは個々のサービス機能を呼び出す方法を示していますが、コンテキスト内のアクションは、関連するシナリオで確認できます。
*シナリオ*は、1 つのサービス内から、または他の AWS のサービスと組み合わせて複数の関数を呼び出し、特定のタスクを実行する方法を示すコード例です。
各例には完全なソースコードへのリンクが含まれており、コードの設定方法と実行方法に関する手順を確認できます。
**Topics**
+ [アクション](#actions)
+ [シナリオ](#scenarios)
+ [サーバーレスサンプル](#serverless_examples)
## アクション
### `CreateQueue`
次のコード例は、`CreateQueue` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sqs#code-examples)での設定と実行の方法を確認してください。
```
def create_queue(name, attributes=None):
"""
Creates an Amazon SQS queue.
:param name: The name of the queue. This is part of the URL assigned to the queue.
:param attributes: The attributes of the queue, such as maximum message size or
whether it's a FIFO queue.
:return: A Queue object that contains metadata about the queue and that can be used
to perform queue operations like sending and receiving messages.
"""
if not attributes:
attributes = {}
try:
queue = sqs.create_queue(QueueName=name, Attributes=attributes)
logger.info("Created queue '%s' with URL=%s", name, queue.url)
except ClientError as error:
logger.exception("Couldn't create queue named '%s'.", name)
raise error
else:
return queue
```
```
class SqsWrapper:
"""Wrapper class for managing Amazon SQS operations."""
def __init__(self, sqs_client: Any) -> None:
"""
Initialize the SqsWrapper.
:param sqs_client: A Boto3 Amazon SQS client.
"""
self.sqs_client = sqs_client
@classmethod
def from_client(cls) -> 'SqsWrapper':
"""
Create an SqsWrapper instance using a default boto3 client.
:return: An instance of this class.
"""
sqs_client = boto3.client('sqs')
return cls(sqs_client)
def create_queue(self, queue_name: str, is_fifo: bool = False) -> str:
"""
Create an SQS queue.
:param queue_name: The name of the queue to create.
:param is_fifo: Whether to create a FIFO queue.
:return: The URL of the created queue.
:raises ClientError: If the queue creation fails.
"""
try:
# Add .fifo suffix for FIFO queues
if is_fifo and not queue_name.endswith('.fifo'):
queue_name += '.fifo'
attributes = {}
if is_fifo:
attributes['FifoQueue'] = 'true'
response = self.sqs_client.create_queue(
QueueName=queue_name,
Attributes=attributes
)
queue_url = response['QueueUrl']
logger.info(f"Created queue: {queue_name} with URL: {queue_url}")
return queue_url
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
logger.error(f"Error creating queue {queue_name}: {error_code} - {e}")
raise
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[CreateQueue](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/CreateQueue)」を参照してください。
### `DeleteMessage`
次のコード例は、`DeleteMessage` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sqs#code-examples)での設定と実行の方法を確認してください。
```
def delete_message(message):
"""
Delete a message from a queue. Clients must delete messages after they
are received and processed to remove them from the queue.
:param message: The message to delete. The message's queue URL is contained in
the message's metadata.
:return: None
"""
try:
message.delete()
logger.info("Deleted message: %s", message.message_id)
except ClientError as error:
logger.exception("Couldn't delete message: %s", message.message_id)
raise error
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[DeleteMessage](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/DeleteMessage)」を参照してください。
### `DeleteMessageBatch`
次のコード例は、`DeleteMessageBatch` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sqs#code-examples)での設定と実行の方法を確認してください。
```
def delete_messages(queue, messages):
"""
Delete a batch of messages from a queue in a single request.
:param queue: The queue from which to delete the messages.
:param messages: The list of messages to delete.
:return: The response from SQS that contains the list of successful and failed
message deletions.
"""
try:
entries = [
{"Id": str(ind), "ReceiptHandle": msg.receipt_handle}
for ind, msg in enumerate(messages)
]
response = queue.delete_messages(Entries=entries)
if "Successful" in response:
for msg_meta in response["Successful"]:
logger.info("Deleted %s", messages[int(msg_meta["Id"])].receipt_handle)
if "Failed" in response:
for msg_meta in response["Failed"]:
logger.warning(
"Could not delete %s", messages[int(msg_meta["Id"])].receipt_handle
)
except ClientError:
logger.exception("Couldn't delete messages from queue %s", queue)
else:
return response
```
```
class SqsWrapper:
"""Wrapper class for managing Amazon SQS operations."""
def __init__(self, sqs_client: Any) -> None:
"""
Initialize the SqsWrapper.
:param sqs_client: A Boto3 Amazon SQS client.
"""
self.sqs_client = sqs_client
@classmethod
def from_client(cls) -> 'SqsWrapper':
"""
Create an SqsWrapper instance using a default boto3 client.
:return: An instance of this class.
"""
sqs_client = boto3.client('sqs')
return cls(sqs_client)
def delete_messages(self, queue_url: str, messages: List[Dict[str, Any]]) -> bool:
"""
Delete messages from an SQS queue in batches.
:param queue_url: The URL of the queue.
:param messages: List of messages to delete.
:return: True if successful.
:raises ClientError: If deleting messages fails.
"""
try:
if not messages:
return True
# Build delete entries for batch delete
delete_entries = []
for i, message in enumerate(messages):
delete_entries.append({
'Id': str(i),
'ReceiptHandle': message['ReceiptHandle']
})
# Delete messages in batches of 10 (SQS limit)
batch_size = 10
for i in range(0, len(delete_entries), batch_size):
batch = delete_entries[i:i + batch_size]
response = self.sqs_client.delete_message_batch(
QueueUrl=queue_url,
Entries=batch
)
# Check for failures
if 'Failed' in response and response['Failed']:
for failed in response['Failed']:
logger.warning(f"Failed to delete message: {failed}")
logger.info(f"Deleted {len(messages)} messages from {queue_url}")
return True
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
logger.error(f"Error deleting messages: {error_code} - {e}")
raise
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[DeleteMessageBatch](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/DeleteMessageBatch)」を参照してください。
### `DeleteQueue`
次のコード例は、`DeleteQueue` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sqs#code-examples)での設定と実行の方法を確認してください。
```
def remove_queue(queue):
"""
Removes an SQS queue. When run against an AWS account, it can take up to
60 seconds before the queue is actually deleted.
:param queue: The queue to delete.
:return: None
"""
try:
queue.delete()
logger.info("Deleted queue with URL=%s.", queue.url)
except ClientError as error:
logger.exception("Couldn't delete queue with URL=%s!", queue.url)
raise error
```
```
class SqsWrapper:
"""Wrapper class for managing Amazon SQS operations."""
def __init__(self, sqs_client: Any) -> None:
"""
Initialize the SqsWrapper.
:param sqs_client: A Boto3 Amazon SQS client.
"""
self.sqs_client = sqs_client
@classmethod
def from_client(cls) -> 'SqsWrapper':
"""
Create an SqsWrapper instance using a default boto3 client.
:return: An instance of this class.
"""
sqs_client = boto3.client('sqs')
return cls(sqs_client)
def delete_queue(self, queue_url: str) -> bool:
"""
Delete an SQS queue.
:param queue_url: The URL of the queue to delete.
:return: True if successful.
:raises ClientError: If the queue deletion fails.
"""
try:
self.sqs_client.delete_queue(QueueUrl=queue_url)
logger.info(f"Deleted queue: {queue_url}")
return True
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
if error_code == 'AWS.SimpleQueueService.NonExistentQueue':
logger.warning(f"Queue not found: {queue_url}")
return True # Already deleted
else:
logger.error(f"Error deleting queue: {error_code} - {e}")
raise
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[DeleteQueue](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/DeleteQueue)」を参照してください。
### `GetQueueAttributes`
次の例は、`GetQueueAttributes` を使用する方法を説明しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/topics_and_queues#code-examples)での設定と実行の方法を確認してください。
```
class SqsWrapper:
"""Wrapper class for managing Amazon SQS operations."""
def __init__(self, sqs_client: Any) -> None:
"""
Initialize the SqsWrapper.
:param sqs_client: A Boto3 Amazon SQS client.
"""
self.sqs_client = sqs_client
@classmethod
def from_client(cls) -> 'SqsWrapper':
"""
Create an SqsWrapper instance using a default boto3 client.
:return: An instance of this class.
"""
sqs_client = boto3.client('sqs')
return cls(sqs_client)
def get_queue_arn(self, queue_url: str) -> str:
"""
Get the ARN of an SQS queue.
:param queue_url: The URL of the queue.
:return: The ARN of the queue.
:raises ClientError: If getting queue attributes fails.
"""
try:
response = self.sqs_client.get_queue_attributes(
QueueUrl=queue_url,
AttributeNames=['QueueArn']
)
queue_arn = response['Attributes']['QueueArn']
logger.info(f"Queue ARN for {queue_url}: {queue_arn}")
return queue_arn
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
logger.error(f"Error getting queue ARN: {error_code} - {e}")
raise
```
+ API の詳細については、 *AWS SDK for Python (Boto3) API リファレンス*の[GetQueueAttributes](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/GetQueueAttributes)」を参照してください。
### `GetQueueUrl`
次の例は、`GetQueueUrl` を使用する方法を説明しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sqs#code-examples)での設定と実行の方法を確認してください。
```
def get_queue(name):
"""
Gets an SQS queue by name.
:param name: The name that was used to create the queue.
:return: A Queue object.
"""
try:
queue = sqs.get_queue_by_name(QueueName=name)
logger.info("Got queue '%s' with URL=%s", name, queue.url)
except ClientError as error:
logger.exception("Couldn't get queue named %s.", name)
raise error
else:
return queue
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[GetQueueUrl](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/GetQueueUrl)」を参照してください。
### `ListQueues`
次のコード例は、`ListQueues` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sqs#code-examples)での設定と実行の方法を確認してください。
```
def get_queues(prefix=None):
"""
Gets a list of SQS queues. When a prefix is specified, only queues with names
that start with the prefix are returned.
:param prefix: The prefix used to restrict the list of returned queues.
:return: A list of Queue objects.
"""
if prefix:
queue_iter = sqs.queues.filter(QueueNamePrefix=prefix)
else:
queue_iter = sqs.queues.all()
queues = list(queue_iter)
if queues:
logger.info("Got queues: %s", ", ".join([q.url for q in queues]))
else:
logger.warning("No queues found.")
return queues
```
+ API の詳細については、* SDK for Python (Boto3) API リファレンス*の「[ListQueues](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/ListQueues)」を参照してください。
### `ReceiveMessage`
次のコード例は、`ReceiveMessage` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sqs#code-examples)での設定と実行の方法を確認してください。
```
def receive_messages(queue, max_number, wait_time):
"""
Receive a batch of messages in a single request from an SQS queue.
:param queue: The queue from which to receive messages.
:param max_number: The maximum number of messages to receive. The actual number
of messages received might be less.
:param wait_time: The maximum time to wait (in seconds) before returning. When
this number is greater than zero, long polling is used. This
can result in reduced costs and fewer false empty responses.
:return: The list of Message objects received. These each contain the body
of the message and metadata and custom attributes.
"""
try:
messages = queue.receive_messages(
MessageAttributeNames=["All"],
MaxNumberOfMessages=max_number,
WaitTimeSeconds=wait_time,
)
for msg in messages:
logger.info("Received message: %s: %s", msg.message_id, msg.body)
except ClientError as error:
logger.exception("Couldn't receive messages from queue: %s", queue)
raise error
else:
return messages
```
```
class SqsWrapper:
"""Wrapper class for managing Amazon SQS operations."""
def __init__(self, sqs_client: Any) -> None:
"""
Initialize the SqsWrapper.
:param sqs_client: A Boto3 Amazon SQS client.
"""
self.sqs_client = sqs_client
@classmethod
def from_client(cls) -> 'SqsWrapper':
"""
Create an SqsWrapper instance using a default boto3 client.
:return: An instance of this class.
"""
sqs_client = boto3.client('sqs')
return cls(sqs_client)
def receive_messages(self, queue_url: str, max_messages: int = 10) -> List[Dict[str, Any]]:
"""
Receive messages from an SQS queue.
:param queue_url: The URL of the queue to receive messages from.
:param max_messages: Maximum number of messages to receive (1-10).
:return: List of received messages.
:raises ClientError: If receiving messages fails.
"""
try:
# Ensure max_messages is within valid range
max_messages = max(1, min(10, max_messages))
response = self.sqs_client.receive_message(
QueueUrl=queue_url,
MaxNumberOfMessages=max_messages,
WaitTimeSeconds=2, # Short polling
MessageAttributeNames=['All']
)
messages = response.get('Messages', [])
logger.info(f"Received {len(messages)} messages from {queue_url}")
return messages
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
logger.error(f"Error receiving messages: {error_code} - {e}")
raise
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[ReceiveMessage](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/ReceiveMessage)」を参照してください。
### `SendMessage`
次のコード例は、`SendMessage` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sqs#code-examples)での設定と実行の方法を確認してください。
```
def send_message(queue, message_body, message_attributes=None):
"""
Send a message to an Amazon SQS queue.
:param queue: The queue that receives the message.
:param message_body: The body text of the message.
:param message_attributes: Custom attributes of the message. These are key-value
pairs that can be whatever you want.
:return: The response from SQS that contains the assigned message ID.
"""
if not message_attributes:
message_attributes = {}
try:
response = queue.send_message(
MessageBody=message_body, MessageAttributes=message_attributes
)
except ClientError as error:
logger.exception("Send message failed: %s", message_body)
raise error
else:
return response
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[SendMessage](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/SendMessage)」を参照してください。
### `SendMessageBatch`
次のコード例は、`SendMessageBatch` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sqs#code-examples)での設定と実行の方法を確認してください。
```
def send_messages(queue, messages):
"""
Send a batch of messages in a single request to an SQS queue.
This request may return overall success even when some messages were not sent.
The caller must inspect the Successful and Failed lists in the response and
resend any failed messages.
:param queue: The queue to receive the messages.
:param messages: The messages to send to the queue. These are simplified to
contain only the message body and attributes.
:return: The response from SQS that contains the list of successful and failed
messages.
"""
try:
entries = [
{
"Id": str(ind),
"MessageBody": msg["body"],
"MessageAttributes": msg["attributes"],
}
for ind, msg in enumerate(messages)
]
response = queue.send_messages(Entries=entries)
if "Successful" in response:
for msg_meta in response["Successful"]:
logger.info(
"Message sent: %s: %s",
msg_meta["MessageId"],
messages[int(msg_meta["Id"])]["body"],
)
if "Failed" in response:
for msg_meta in response["Failed"]:
logger.warning(
"Failed to send: %s: %s",
msg_meta["MessageId"],
messages[int(msg_meta["Id"])]["body"],
)
except ClientError as error:
logger.exception("Send messages failed to queue: %s", queue)
raise error
else:
return response
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[SendMessageBatch](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/SendMessageBatch)」を参照してください。
### `SetQueueAttributes`
次の例は、`SetQueueAttributes` を使用する方法を説明しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/topics_and_queues#code-examples)での設定と実行の方法を確認してください。
トピックのキューのポリシー属性を設定します。
```
class SqsWrapper:
"""Wrapper class for managing Amazon SQS operations."""
def __init__(self, sqs_client: Any) -> None:
"""
Initialize the SqsWrapper.
:param sqs_client: A Boto3 Amazon SQS client.
"""
self.sqs_client = sqs_client
@classmethod
def from_client(cls) -> 'SqsWrapper':
"""
Create an SqsWrapper instance using a default boto3 client.
:return: An instance of this class.
"""
sqs_client = boto3.client('sqs')
return cls(sqs_client)
def set_queue_policy_for_topic(self, queue_arn: str, topic_arn: str, queue_url: str) -> bool:
"""
Set the queue policy to allow SNS to send messages to the queue.
:param queue_arn: The ARN of the SQS queue.
:param topic_arn: The ARN of the SNS topic.
:param queue_url: The URL of the SQS queue.
:return: True if successful.
:raises ClientError: If setting the queue policy fails.
"""
try:
# Create policy that allows SNS to send messages to the queue
policy = {
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "sns.amazonaws.com"
},
"Action": "sqs:SendMessage",
"Resource": queue_arn,
"Condition": {
"ArnEquals": {
"aws:SourceArn": topic_arn
}
}
}
]
}
self.sqs_client.set_queue_attributes(
QueueUrl=queue_url,
Attributes={
'Policy': json.dumps(policy)
}
)
logger.info(f"Set queue policy for {queue_url} to allow messages from {topic_arn}")
return True
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
logger.error(f"Error setting queue policy: {error_code} - {e}")
raise
```
+ API の詳細については、 *AWS SDK for Python (Boto3) API リファレンスの*「[SetQueueAttributes](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/SetQueueAttributes)」を参照してください。
## シナリオ
### メッセンジャーアプリケーションを作成する
次のコード例は、データベーステーブルからメッセージレコードを取得する AWS Step Functions メッセンジャーアプリケーションを作成する方法を示しています。
**SDK for Python (Boto3)**
AWS SDK for Python (Boto3) で を使用して AWS Step Functions 、Amazon DynamoDB テーブルからメッセージレコードを取得し、Amazon Simple Queue Service (Amazon SQS) で送信するメッセンジャーアプリケーションを作成する方法を示します。ステートマシンは AWS Lambda 関数と統合して、未送信メッセージがないかデータベースをスキャンします。
+ Amazon DynamoDB テーブルからメッセージレコードを取得および更新するステートマシンを作成します。
+ ステートマシンの定義を更新して、Amazon Simple Queue Service (Amazon SQS) にもメッセージを送信します。
+ ステートマシンの実行を開始および停止します。
+ サービス統合を使用して、ステートマシンから Lambda、DynamoDB、および Amazon SQS に接続します。
完全なソースコードとセットアップおよび実行の手順については、[GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/stepfunctions_messenger) で完全な例を参照してください。
**この例で使用されているサービス**
+ DynamoDB
+ Lambda
+ Amazon SQS
+ ステップ関数
### Amazon Textract エクスプローラーアプリケーションを作成する
次のコード例は、インタラクティブアプリケーションで Amazon Textract の出力を調べる方法を示しています。
**SDK for Python (Boto3)**
Amazon Textract AWS SDK for Python (Boto3) で を使用して、ドキュメントイメージ内のテキスト、フォーム、テーブル要素を検出する方法を示します。入力イメージと Amazon Textract 出力は、検出された要素を探索できる Tkinter アプリケーションに表示されます。
+ Amazon Textract にドキュメントイメージを送信し、検出された要素の出力を調べます。
+ Amazon Textract に直接イメージを送信するか、Amazon Simple Storage Service (Amazon S3) バケットを通じてイメージを送信します。
+ 非同期 API を使用して、ジョブの完了時に Amazon Simple Notification Service (Amazon SNS) トピックに通知を発行するジョブを開始します。
+ Amazon Simple Queue Service (Amazon SQS) キューにジョブ完了メッセージについてポーリングし、結果を表示します。
完全なソースコードとセットアップおよび実行の手順については、[GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/textract_explorer) で完全な例を参照してください。
**この例で使用されているサービス**
+ Amazon Cognito ID
+ Amazon S3
+ Amazon SNS
+ Amazon SQS
+ Amazon Textract
### FIFO トピックを作成して発行する
次のコード例は、FIFO Amazon SNS トピックを作成、発行する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sns#code-examples)での設定と実行の方法を確認してください。
FIFO トピックを作成し、そのトピックに Amazon SQS FIFO キューと標準キューをサブスクライブして、メッセージを Amazon SNS トピックに発行します。
```
def usage_demo():
"""Shows how to subscribe queues to a FIFO topic."""
print("-" * 88)
print("Welcome to the `Subscribe queues to a FIFO topic` demo!")
print("-" * 88)
sns = boto3.resource("sns")
sqs = boto3.resource("sqs")
fifo_topic_wrapper = FifoTopicWrapper(sns)
sns_wrapper = SnsWrapper(sns)
prefix = "sqs-subscribe-demo-"
queues = set()
subscriptions = set()
wholesale_queue = sqs.create_queue(
QueueName=prefix + "wholesale.fifo",
Attributes={
"MaximumMessageSize": str(4096),
"ReceiveMessageWaitTimeSeconds": str(10),
"VisibilityTimeout": str(300),
"FifoQueue": str(True),
"ContentBasedDeduplication": str(True),
},
)
queues.add(wholesale_queue)
print(f"Created FIFO queue with URL: {wholesale_queue.url}.")
retail_queue = sqs.create_queue(
QueueName=prefix + "retail.fifo",
Attributes={
"MaximumMessageSize": str(4096),
"ReceiveMessageWaitTimeSeconds": str(10),
"VisibilityTimeout": str(300),
"FifoQueue": str(True),
"ContentBasedDeduplication": str(True),
},
)
queues.add(retail_queue)
print(f"Created FIFO queue with URL: {retail_queue.url}.")
analytics_queue = sqs.create_queue(QueueName=prefix + "analytics", Attributes={})
queues.add(analytics_queue)
print(f"Created standard queue with URL: {analytics_queue.url}.")
topic = fifo_topic_wrapper.create_fifo_topic("price-updates-topic.fifo")
print(f"Created FIFO topic: {topic.attributes['TopicArn']}.")
for q in queues:
fifo_topic_wrapper.add_access_policy(q, topic.attributes["TopicArn"])
print(f"Added access policies for topic: {topic.attributes['TopicArn']}.")
for q in queues:
sub = fifo_topic_wrapper.subscribe_queue_to_topic(
topic, q.attributes["QueueArn"]
)
subscriptions.add(sub)
print(f"Subscribed queues to topic: {topic.attributes['TopicArn']}.")
input("Press Enter to publish a message to the topic.")
message_id = fifo_topic_wrapper.publish_price_update(
topic, '{"product": 214, "price": 79.99}', "Consumables"
)
print(f"Published price update with message ID: {message_id}.")
# Clean up the subscriptions, queues, and topic.
input("Press Enter to clean up resources.")
for s in subscriptions:
sns_wrapper.delete_subscription(s)
sns_wrapper.delete_topic(topic)
for q in queues:
fifo_topic_wrapper.delete_queue(q)
print(f"Deleted subscriptions, queues, and topic.")
print("Thanks for watching!")
print("-" * 88)
class FifoTopicWrapper:
"""Encapsulates Amazon SNS FIFO topic and subscription functions."""
def __init__(self, sns_resource):
"""
:param sns_resource: A Boto3 Amazon SNS resource.
"""
self.sns_resource = sns_resource
def create_fifo_topic(self, topic_name):
"""
Create a FIFO topic.
Topic names must be made up of only uppercase and lowercase ASCII letters,
numbers, underscores, and hyphens, and must be between 1 and 256 characters long.
For a FIFO topic, the name must end with the .fifo suffix.
:param topic_name: The name for the topic.
:return: The new topic.
"""
try:
topic = self.sns_resource.create_topic(
Name=topic_name,
Attributes={
"FifoTopic": str(True),
"ContentBasedDeduplication": str(False),
"FifoThroughputScope": "MessageGroup",
},
)
logger.info("Created FIFO topic with name=%s.", topic_name)
return topic
except ClientError as error:
logger.exception("Couldn't create topic with name=%s!", topic_name)
raise error
@staticmethod
def add_access_policy(queue, topic_arn):
"""
Add the necessary access policy to a queue, so
it can receive messages from a topic.
:param queue: The queue resource.
:param topic_arn: The ARN of the topic.
:return: None.
"""
try:
queue.set_attributes(
Attributes={
"Policy": json.dumps(
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "test-sid",
"Effect": "Allow",
"Principal": {"AWS": "*"},
"Action": "SQS:SendMessage",
"Resource": queue.attributes["QueueArn"],
"Condition": {
"ArnLike": {"aws:SourceArn": topic_arn}
},
}
],
}
)
}
)
logger.info("Added trust policy to the queue.")
except ClientError as error:
logger.exception("Couldn't add trust policy to the queue!")
raise error
@staticmethod
def subscribe_queue_to_topic(topic, queue_arn):
"""
Subscribe a queue to a topic.
:param topic: The topic resource.
:param queue_arn: The ARN of the queue.
:return: The subscription resource.
"""
try:
subscription = topic.subscribe(
Protocol="sqs",
Endpoint=queue_arn,
)
logger.info("The queue is subscribed to the topic.")
return subscription
except ClientError as error:
logger.exception("Couldn't subscribe queue to topic!")
raise error
@staticmethod
def publish_price_update(topic, payload, group_id):
"""
Compose and publish a message that updates the wholesale price.
:param topic: The topic to publish to.
:param payload: The message to publish.
:param group_id: The group ID for the message.
:return: The ID of the message.
"""
try:
att_dict = {"business": {"DataType": "String", "StringValue": "wholesale"}}
dedup_id = uuid.uuid4()
response = topic.publish(
Subject="Price Update",
Message=payload,
MessageAttributes=att_dict,
MessageGroupId=group_id,
MessageDeduplicationId=str(dedup_id),
)
message_id = response["MessageId"]
logger.info("Published message to topic %s.", topic.arn)
except ClientError as error:
logger.exception("Couldn't publish message to topic %s.", topic.arn)
raise error
return message_id
@staticmethod
def delete_queue(queue):
"""
Removes an SQS queue. When run against an AWS account, it can take up to
60 seconds before the queue is actually deleted.
:param queue: The queue to delete.
:return: None
"""
try:
queue.delete()
logger.info("Deleted queue with URL=%s.", queue.url)
except ClientError as error:
logger.exception("Couldn't delete queue with URL=%s!", queue.url)
raise error
```
+ API の詳細については、「**AWS SDK for Python (Boto3) API リファレンス」の以下のトピックを参照してください。
+ [CreateTopic](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/CreateTopic)
+ [Publish](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/Publish)
+ [Subscribe](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/Subscribe)
### 動画内の人物や物体を検出する
次のコード例は、Amazon Rekognition で動画内の人やオブジェクトを検出する方法を示します。
**SDK for Python (Boto3)**
Amazon Rekognition を使用して、非同期検出ジョブを開始して、動画内の顔、オブジェクト、人を検出します。この例では、ジョブが完了し、Amazon Simple Queue Service (Amazon SQS) キューをトピックにサブスクライブしたときに、Amazon Simple Notification Service (Amazon SNS) トピックに通知するように Amazon Rekognition を設定します。キューがジョブに関するメッセージを受信すると、ジョブが取得され、結果が出力されます。
この例は GitHub で最もよく見られます。完全なソースコードとセットアップおよび実行の手順については、[GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rekognition) で完全な例を参照してください。
**この例で使用されているサービス**
+ Amazon Rekognition
+ Amazon S3
+ Amazon SES
+ Amazon SNS
+ Amazon SQS
### メッセージをキューに発行する
次のコード例は、以下の操作方法を示しています。
+ トピック (FIFO または非 FIFO) を作成します。
+ フィルターを適用するオプションを使用して、複数のキューをトピックにサブスクライブします。
+ メッセージをトピックに発行します。
+ 受信したメッセージのキューをポーリングします。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/topics_and_queues#code-examples)での設定と実行の方法を確認してください。
コマンドプロンプトからインタラクティブなシナリオを実行します。
```
class TopicsAndQueuesScenario:
"""Manages the Topics and Queues feature scenario."""
DASHES = "-" * 80
def __init__(self, sns_wrapper: SnsWrapper, sqs_wrapper: SqsWrapper) -> None:
"""
Initialize the Topics and Queues scenario.
:param sns_wrapper: SnsWrapper instance for SNS operations.
:param sqs_wrapper: SqsWrapper instance for SQS operations.
"""
self.sns_wrapper = sns_wrapper
self.sqs_wrapper = sqs_wrapper
# Scenario state
self.use_fifo_topic = False
self.use_content_based_deduplication = False
self.topic_name = None
self.topic_arn = None
self.queue_count = 2
self.queue_urls = []
self.subscription_arns = []
self.tones = ["cheerful", "funny", "serious", "sincere"]
def run_scenario(self) -> None:
"""Run the Topics and Queues feature scenario."""
print(self.DASHES)
print("Welcome to messaging with topics and queues.")
print(self.DASHES)
print(f"""
In this scenario, you will create an SNS topic and subscribe {self.queue_count} SQS queues to the topic.
You can select from several options for configuring the topic and the subscriptions for the queues.
You can then post to the topic and see the results in the queues.
""")
try:
# Setup Phase
print(self.DASHES)
self._setup_topic()
print(self.DASHES)
self._setup_queues()
print(self.DASHES)
# Demonstration Phase
self._publish_messages()
print(self.DASHES)
# Examination Phase
self._poll_queues_for_messages()
print(self.DASHES)
# Cleanup Phase
self._cleanup_resources()
print(self.DASHES)
except Exception as e:
logger.error(f"Scenario failed: {e}")
print(f"There was a problem with the scenario: {e}")
print("\nInitiating cleanup...")
try:
self._cleanup_resources()
except Exception as cleanup_error:
logger.error(f"Error during cleanup: {cleanup_error}")
print("Messaging with topics and queues scenario is complete.")
print(self.DASHES)
def _setup_topic(self) -> None:
"""Set up the SNS topic to be used with the queues."""
print("SNS topics can be configured as FIFO (First-In-First-Out).")
print("FIFO topics deliver messages in order and support deduplication and message filtering.")
print()
self.use_fifo_topic = q.ask("Would you like to work with FIFO topics? (y/n): ", q.is_yesno)
if self.use_fifo_topic:
print(self.DASHES)
self.topic_name = q.ask("Enter a name for your SNS topic: ", q.non_empty)
print("Because you have selected a FIFO topic, '.fifo' must be appended to the topic name.")
print()
print(self.DASHES)
print("""
Because you have chosen a FIFO topic, deduplication is supported.
Deduplication IDs are either set in the message or automatically generated
from content using a hash function.
If a message is successfully published to an SNS FIFO topic, any message
published and determined to have the same deduplication ID,
within the five-minute deduplication interval, is accepted but not delivered.
For more information about deduplication,
see https://docs.aws.amazon.com/sns/latest/dg/fifo-message-dedup.html.
""")
self.use_content_based_deduplication = q.ask(
"Use content-based deduplication instead of entering a deduplication ID? (y/n): ",
q.is_yesno
)
else:
self.topic_name = q.ask("Enter a name for your SNS topic: ", q.non_empty)
print(self.DASHES)
# Create the topic
self.topic_arn = self.sns_wrapper.create_topic(
self.topic_name,
self.use_fifo_topic,
self.use_content_based_deduplication
)
print(f"Your new topic with the name {self.topic_name}")
print(f" and Amazon Resource Name (ARN) {self.topic_arn}")
print(f" has been created.")
print()
def _setup_queues(self) -> None:
"""Set up the SQS queues and subscribe them to the topic."""
print(f"Now you will create {self.queue_count} Amazon Simple Queue Service (Amazon SQS) queues to subscribe to the topic.")
for i in range(self.queue_count):
queue_name = q.ask(f"Enter a name for SQS queue #{i+1}: ", q.non_empty)
if self.use_fifo_topic and i == 0:
print("Because you have selected a FIFO topic, '.fifo' must be appended to the queue name.")
# Create the queue
queue_url = self.sqs_wrapper.create_queue(queue_name, self.use_fifo_topic)
self.queue_urls.append(queue_url)
print(f"Your new queue with the name {queue_name}")
print(f" and queue URL {queue_url}")
print(f" has been created.")
print()
if i == 0:
print("The queue URL is used to retrieve the queue ARN,")
print("which is used to create a subscription.")
print(self.DASHES)
# Get queue ARN
queue_arn = self.sqs_wrapper.get_queue_arn(queue_url)
if i == 0:
print("An AWS Identity and Access Management (IAM) policy must be attached to an SQS queue,")
print("enabling it to receive messages from an SNS topic.")
# Set queue policy to allow SNS to send messages
self.sqs_wrapper.set_queue_policy_for_topic(queue_arn, self.topic_arn, queue_url)
# Set up message filtering if using FIFO
subscription_arn = self._setup_subscription_with_filter(i, queue_arn, queue_name)
self.subscription_arns.append(subscription_arn)
def _setup_subscription_with_filter(self, queue_index: int, queue_arn: str, queue_name: str) -> str:
"""Set up subscription with optional message filtering."""
filter_policy = None
if self.use_fifo_topic:
print(self.DASHES)
if queue_index == 0:
print("Subscriptions to a FIFO topic can have filters.")
print("If you add a filter to this subscription, then only the filtered messages")
print("will be received in the queue.")
print()
print("For information about message filtering,")
print("see https://docs.aws.amazon.com/sns/latest/dg/sns-message-filtering.html")
print()
print("For this example, you can filter messages by a TONE attribute.")
use_filter = q.ask(f"Filter messages for {queue_name}'s subscription to the topic? (y/n): ", q.is_yesno)
if use_filter:
filter_policy = self._create_filter_policy()
subscription_arn = self.sns_wrapper.subscribe_queue_to_topic(
self.topic_arn, queue_arn, filter_policy
)
print(f"The queue {queue_name} has been subscribed to the topic {self.topic_name}")
print(f" with the subscription ARN {subscription_arn}")
return subscription_arn
def _create_filter_policy(self) -> str:
"""Create a message filter policy based on user selections."""
print(self.DASHES)
print("You can filter messages by one or more of the following TONE attributes.")
filter_selections = []
selection_number = 0
while True:
print("Enter a number to add a TONE filter, or enter 0 to stop adding filters.")
for i, tone in enumerate(self.tones, 1):
print(f" {i}. {tone}")
selection = q.ask("Your choice: ", q.is_int, q.in_range(0, len(self.tones)))
if selection == 0:
break
elif selection > 0 and self.tones[selection - 1] not in filter_selections:
filter_selections.append(self.tones[selection - 1])
print(f"Added '{self.tones[selection - 1]}' to filter list.")
if filter_selections:
filters = {"tone": filter_selections}
return json.dumps(filters)
return None
def _publish_messages(self) -> None:
"""Publish messages to the topic with various options."""
print("Now we can publish messages.")
keep_sending = True
while keep_sending:
print()
message = q.ask("Enter a message to publish: ", q.non_empty)
message_group_id = None
deduplication_id = None
tone_attribute = None
if self.use_fifo_topic:
print("Because you are using a FIFO topic, you must set a message group ID.")
print("All messages within the same group will be received in the order they were published.")
print()
message_group_id = q.ask("Enter a message group ID for this message: ", q.non_empty)
if not self.use_content_based_deduplication:
print("Because you are not using content-based deduplication,")
print("you must enter a deduplication ID.")
deduplication_id = q.ask("Enter a deduplication ID for this message: ", q.non_empty)
# Ask about tone attribute
add_attribute = q.ask("Add an attribute to this message? (y/n): ", q.is_yesno)
if add_attribute:
print("Enter a number for an attribute:")
for i, tone in enumerate(self.tones, 1):
print(f" {i}. {tone}")
selection = q.ask("Your choice: ", q.is_int, q.in_range(1, len(self.tones)))
if 1 <= selection <= len(self.tones):
tone_attribute = self.tones[selection - 1]
# Publish the message
message_id = self.sns_wrapper.publish_message(
self.topic_arn,
message,
tone_attribute,
deduplication_id,
message_group_id
)
print(f"Message published with ID: {message_id}")
keep_sending = q.ask("Send another message? (y/n): ", q.is_yesno)
def _poll_queues_for_messages(self) -> None:
"""Poll all queues for messages and display results."""
for i, queue_url in enumerate(self.queue_urls):
print(f"Polling queue #{i+1} at {queue_url} for messages...")
q.ask("Press Enter to continue...")
messages = self._poll_queue_for_messages(queue_url)
if messages:
print(f"{len(messages)} message(s) were received by queue #{i+1}")
for j, message in enumerate(messages, 1):
print(f" Message {j}:")
# Parse the SNS message body to get the actual message
try:
sns_message = json.loads(message['Body'])
actual_message = sns_message.get('Message', message['Body'])
print(f" {actual_message}")
except (json.JSONDecodeError, KeyError):
print(f" {message['Body']}")
# Delete the messages
self.sqs_wrapper.delete_messages(queue_url, messages)
print(f"Messages deleted from queue #{i+1}")
else:
print(f"No messages received by queue #{i+1}")
print(self.DASHES)
def _poll_queue_for_messages(self, queue_url: str) -> List[Dict[str, Any]]:
"""Poll a single queue for messages."""
all_messages = []
max_polls = 3 # Limit polling to avoid infinite loops
for poll_count in range(max_polls):
messages = self.sqs_wrapper.receive_messages(queue_url, 10)
if messages:
all_messages.extend(messages)
print(f" Received {len(messages)} messages in poll {poll_count + 1}")
# Small delay between polls
time.sleep(1)
else:
print(f" No messages in poll {poll_count + 1}")
break
return all_messages
def _cleanup_resources(self) -> None:
"""Clean up all resources created during the scenario."""
print("Cleaning up resources...")
# Delete queues
for i, queue_url in enumerate(self.queue_urls):
if queue_url:
delete_queue = q.ask(f"Delete queue #{i+1} with URL {queue_url}? (y/n): ", q.is_yesno)
if delete_queue:
try:
self.sqs_wrapper.delete_queue(queue_url)
print(f"Deleted queue #{i+1}")
except Exception as e:
print(f"Error deleting queue #{i+1}: {e}")
# Unsubscribe from topic
for i, subscription_arn in enumerate(self.subscription_arns):
if subscription_arn:
try:
self.sns_wrapper.unsubscribe(subscription_arn)
print(f"Unsubscribed subscription #{i+1}")
except Exception as e:
print(f"Error unsubscribing #{i+1}: {e}")
# Delete topic
if self.topic_arn:
delete_topic = q.ask(f"Delete topic {self.topic_name}? (y/n): ", q.is_yesno)
if delete_topic:
try:
self.sns_wrapper.delete_topic(self.topic_arn)
print(f"Deleted topic {self.topic_name}")
except Exception as e:
print(f"Error deleting topic: {e}")
print("Resource cleanup complete.")
```
シナリオで使用する Amazon SNS および Amazon SQS オペレーションをラップするクラスを作成します。
```
class SnsWrapper:
"""Wrapper class for managing Amazon SNS operations."""
def __init__(self, sns_client: Any) -> None:
"""
Initialize the SnsWrapper.
:param sns_client: A Boto3 Amazon SNS client.
"""
self.sns_client = sns_client
@classmethod
def from_client(cls) -> 'SnsWrapper':
"""
Create an SnsWrapper instance using a default boto3 client.
:return: An instance of this class.
"""
sns_client = boto3.client('sns')
return cls(sns_client)
def create_topic(
self,
topic_name: str,
is_fifo: bool = False,
content_based_deduplication: bool = False
) -> str:
"""
Create an SNS topic.
:param topic_name: The name of the topic to create.
:param is_fifo: Whether to create a FIFO topic.
:param content_based_deduplication: Whether to use content-based deduplication for FIFO topics.
:return: The ARN of the created topic.
:raises ClientError: If the topic creation fails.
"""
try:
# Add .fifo suffix for FIFO topics
if is_fifo and not topic_name.endswith('.fifo'):
topic_name += '.fifo'
attributes = {}
if is_fifo:
attributes['FifoTopic'] = 'true'
if content_based_deduplication:
attributes['ContentBasedDeduplication'] = 'true'
response = self.sns_client.create_topic(
Name=topic_name,
Attributes=attributes
)
topic_arn = response['TopicArn']
logger.info(f"Created topic: {topic_name} with ARN: {topic_arn}")
return topic_arn
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
logger.error(f"Error creating topic {topic_name}: {error_code} - {e}")
raise
def subscribe_queue_to_topic(
self,
topic_arn: str,
queue_arn: str,
filter_policy: Optional[str] = None
) -> str:
"""
Subscribe an SQS queue to an SNS topic.
:param topic_arn: The ARN of the SNS topic.
:param queue_arn: The ARN of the SQS queue.
:param filter_policy: Optional JSON filter policy for message filtering.
:return: The ARN of the subscription.
:raises ClientError: If the subscription fails.
"""
try:
attributes = {}
if filter_policy:
attributes['FilterPolicy'] = filter_policy
response = self.sns_client.subscribe(
TopicArn=topic_arn,
Protocol='sqs',
Endpoint=queue_arn,
Attributes=attributes
)
subscription_arn = response['SubscriptionArn']
logger.info(f"Subscribed queue {queue_arn} to topic {topic_arn}")
return subscription_arn
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
logger.error(f"Error subscribing queue to topic: {error_code} - {e}")
raise
def publish_message(
self,
topic_arn: str,
message: str,
tone_attribute: Optional[str] = None,
deduplication_id: Optional[str] = None,
message_group_id: Optional[str] = None
) -> str:
"""
Publish a message to an SNS topic.
:param topic_arn: The ARN of the SNS topic.
:param message: The message content to publish.
:param tone_attribute: Optional tone attribute for message filtering.
:param deduplication_id: Optional deduplication ID for FIFO topics.
:param message_group_id: Optional message group ID for FIFO topics.
:return: The message ID of the published message.
:raises ClientError: If the message publication fails.
"""
try:
publish_args = {
'TopicArn': topic_arn,
'Message': message
}
# Add message attributes if tone is specified
if tone_attribute:
publish_args['MessageAttributes'] = {
'tone': {
'DataType': 'String',
'StringValue': tone_attribute
}
}
# Add FIFO-specific parameters
if message_group_id:
publish_args['MessageGroupId'] = message_group_id
if deduplication_id:
publish_args['MessageDeduplicationId'] = deduplication_id
response = self.sns_client.publish(**publish_args)
message_id = response['MessageId']
logger.info(f"Published message to topic {topic_arn} with ID: {message_id}")
return message_id
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
logger.error(f"Error publishing message to topic: {error_code} - {e}")
raise
def unsubscribe(self, subscription_arn: str) -> bool:
"""
Unsubscribe from an SNS topic.
:param subscription_arn: The ARN of the subscription to remove.
:return: True if successful.
:raises ClientError: If the unsubscribe operation fails.
"""
try:
self.sns_client.unsubscribe(SubscriptionArn=subscription_arn)
logger.info(f"Unsubscribed: {subscription_arn}")
return True
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
if error_code == 'NotFound':
logger.warning(f"Subscription not found: {subscription_arn}")
return True # Already unsubscribed
else:
logger.error(f"Error unsubscribing: {error_code} - {e}")
raise
def delete_topic(self, topic_arn: str) -> bool:
"""
Delete an SNS topic.
:param topic_arn: The ARN of the topic to delete.
:return: True if successful.
:raises ClientError: If the topic deletion fails.
"""
try:
self.sns_client.delete_topic(TopicArn=topic_arn)
logger.info(f"Deleted topic: {topic_arn}")
return True
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
if error_code == 'NotFound':
logger.warning(f"Topic not found: {topic_arn}")
return True # Already deleted
else:
logger.error(f"Error deleting topic: {error_code} - {e}")
raise
def list_topics(self) -> list:
"""
List all SNS topics in the account using pagination.
:return: List of topic ARNs.
:raises ClientError: If listing topics fails.
"""
try:
topics = []
paginator = self.sns_client.get_paginator('list_topics')
for page in paginator.paginate():
topics.extend([topic['TopicArn'] for topic in page.get('Topics', [])])
logger.info(f"Found {len(topics)} topics")
return topics
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
if error_code == 'AuthorizationError':
logger.error("Authorization error listing topics - check IAM permissions")
else:
logger.error(f"Error listing topics: {error_code} - {e}")
raise
class SqsWrapper:
"""Wrapper class for managing Amazon SQS operations."""
def __init__(self, sqs_client: Any) -> None:
"""
Initialize the SqsWrapper.
:param sqs_client: A Boto3 Amazon SQS client.
"""
self.sqs_client = sqs_client
@classmethod
def from_client(cls) -> 'SqsWrapper':
"""
Create an SqsWrapper instance using a default boto3 client.
:return: An instance of this class.
"""
sqs_client = boto3.client('sqs')
return cls(sqs_client)
def create_queue(self, queue_name: str, is_fifo: bool = False) -> str:
"""
Create an SQS queue.
:param queue_name: The name of the queue to create.
:param is_fifo: Whether to create a FIFO queue.
:return: The URL of the created queue.
:raises ClientError: If the queue creation fails.
"""
try:
# Add .fifo suffix for FIFO queues
if is_fifo and not queue_name.endswith('.fifo'):
queue_name += '.fifo'
attributes = {}
if is_fifo:
attributes['FifoQueue'] = 'true'
response = self.sqs_client.create_queue(
QueueName=queue_name,
Attributes=attributes
)
queue_url = response['QueueUrl']
logger.info(f"Created queue: {queue_name} with URL: {queue_url}")
return queue_url
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
logger.error(f"Error creating queue {queue_name}: {error_code} - {e}")
raise
def get_queue_arn(self, queue_url: str) -> str:
"""
Get the ARN of an SQS queue.
:param queue_url: The URL of the queue.
:return: The ARN of the queue.
:raises ClientError: If getting queue attributes fails.
"""
try:
response = self.sqs_client.get_queue_attributes(
QueueUrl=queue_url,
AttributeNames=['QueueArn']
)
queue_arn = response['Attributes']['QueueArn']
logger.info(f"Queue ARN for {queue_url}: {queue_arn}")
return queue_arn
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
logger.error(f"Error getting queue ARN: {error_code} - {e}")
raise
def set_queue_policy_for_topic(self, queue_arn: str, topic_arn: str, queue_url: str) -> bool:
"""
Set the queue policy to allow SNS to send messages to the queue.
:param queue_arn: The ARN of the SQS queue.
:param topic_arn: The ARN of the SNS topic.
:param queue_url: The URL of the SQS queue.
:return: True if successful.
:raises ClientError: If setting the queue policy fails.
"""
try:
# Create policy that allows SNS to send messages to the queue
policy = {
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "sns.amazonaws.com"
},
"Action": "sqs:SendMessage",
"Resource": queue_arn,
"Condition": {
"ArnEquals": {
"aws:SourceArn": topic_arn
}
}
}
]
}
self.sqs_client.set_queue_attributes(
QueueUrl=queue_url,
Attributes={
'Policy': json.dumps(policy)
}
)
logger.info(f"Set queue policy for {queue_url} to allow messages from {topic_arn}")
return True
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
logger.error(f"Error setting queue policy: {error_code} - {e}")
raise
def receive_messages(self, queue_url: str, max_messages: int = 10) -> List[Dict[str, Any]]:
"""
Receive messages from an SQS queue.
:param queue_url: The URL of the queue to receive messages from.
:param max_messages: Maximum number of messages to receive (1-10).
:return: List of received messages.
:raises ClientError: If receiving messages fails.
"""
try:
# Ensure max_messages is within valid range
max_messages = max(1, min(10, max_messages))
response = self.sqs_client.receive_message(
QueueUrl=queue_url,
MaxNumberOfMessages=max_messages,
WaitTimeSeconds=2, # Short polling
MessageAttributeNames=['All']
)
messages = response.get('Messages', [])
logger.info(f"Received {len(messages)} messages from {queue_url}")
return messages
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
logger.error(f"Error receiving messages: {error_code} - {e}")
raise
def delete_messages(self, queue_url: str, messages: List[Dict[str, Any]]) -> bool:
"""
Delete messages from an SQS queue in batches.
:param queue_url: The URL of the queue.
:param messages: List of messages to delete.
:return: True if successful.
:raises ClientError: If deleting messages fails.
"""
try:
if not messages:
return True
# Build delete entries for batch delete
delete_entries = []
for i, message in enumerate(messages):
delete_entries.append({
'Id': str(i),
'ReceiptHandle': message['ReceiptHandle']
})
# Delete messages in batches of 10 (SQS limit)
batch_size = 10
for i in range(0, len(delete_entries), batch_size):
batch = delete_entries[i:i + batch_size]
response = self.sqs_client.delete_message_batch(
QueueUrl=queue_url,
Entries=batch
)
# Check for failures
if 'Failed' in response and response['Failed']:
for failed in response['Failed']:
logger.warning(f"Failed to delete message: {failed}")
logger.info(f"Deleted {len(messages)} messages from {queue_url}")
return True
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
logger.error(f"Error deleting messages: {error_code} - {e}")
raise
def delete_queue(self, queue_url: str) -> bool:
"""
Delete an SQS queue.
:param queue_url: The URL of the queue to delete.
:return: True if successful.
:raises ClientError: If the queue deletion fails.
"""
try:
self.sqs_client.delete_queue(QueueUrl=queue_url)
logger.info(f"Deleted queue: {queue_url}")
return True
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
if error_code == 'AWS.SimpleQueueService.NonExistentQueue':
logger.warning(f"Queue not found: {queue_url}")
return True # Already deleted
else:
logger.error(f"Error deleting queue: {error_code} - {e}")
raise
def list_queues(self, queue_name_prefix: Optional[str] = None) -> List[str]:
"""
List all SQS queues in the account using pagination.
:param queue_name_prefix: Optional prefix to filter queue names.
:return: List of queue URLs.
:raises ClientError: If listing queues fails.
"""
try:
queue_urls = []
paginator = self.sqs_client.get_paginator('list_queues')
page_params = {}
if queue_name_prefix:
page_params['QueueNamePrefix'] = queue_name_prefix
for page in paginator.paginate(**page_params):
queue_urls.extend(page.get('QueueUrls', []))
logger.info(f"Found {len(queue_urls)} queues")
return queue_urls
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
if error_code == 'AccessDenied':
logger.error("Access denied listing queues - check IAM permissions")
else:
logger.error(f"Error listing queues: {error_code} - {e}")
raise
def send_message(self, queue_url: str, message_body: str, **kwargs) -> str:
"""
Send a message to an SQS queue.
:param queue_url: The URL of the queue.
:param message_body: The message content.
:param kwargs: Additional message parameters (DelaySeconds, MessageAttributes, etc.).
:return: The message ID.
:raises ClientError: If sending the message fails.
"""
try:
send_params = {
'QueueUrl': queue_url,
'MessageBody': message_body,
**kwargs
}
response = self.sqs_client.send_message(**send_params)
message_id = response['MessageId']
logger.info(f"Sent message to {queue_url} with ID: {message_id}")
return message_id
except ClientError as e:
error_code = e.response.get('Error', {}).get('Code', 'Unknown')
logger.error(f"Error sending message: {error_code} - {e}")
raise
```
+ API の詳細については、「**AWS SDK for Python (Boto3) API リファレンス」の以下のトピックを参照してください。
+ [CreateQueue](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/CreateQueue)
+ [CreateTopic](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/CreateTopic)
+ [DeleteMessageBatch](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/DeleteMessageBatch)
+ [DeleteQueue](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/DeleteQueue)
+ [DeleteTopic](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/DeleteTopic)
+ [GetQueueAttributes](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/GetQueueAttributes)
+ [Publish](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/Publish)
+ [ReceiveMessage](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/ReceiveMessage)
+ [SetQueueAttributes](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/SetQueueAttributes)
+ [Subscribe](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/Subscribe)
+ [Unsubscribe](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/Unsubscribe)
### バッチメッセージを送受信する
次のコード例は、以下の操作方法を示しています。
+ Amazon SQS キューを作成します。
+ キューにバッチメッセージを送信します。
+ キューからバッチメッセージを受信します。
+ キューからバッチメッセージを受信します。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sqs#code-examples)での設定と実行の方法を確認してください。
Amazon SQS メッセージ関数をラップする関数を作成します。
```
import logging
import sys
import boto3
from botocore.exceptions import ClientError
import queue_wrapper
logger = logging.getLogger(__name__)
sqs = boto3.resource("sqs")
def send_messages(queue, messages):
"""
Send a batch of messages in a single request to an SQS queue.
This request may return overall success even when some messages were not sent.
The caller must inspect the Successful and Failed lists in the response and
resend any failed messages.
:param queue: The queue to receive the messages.
:param messages: The messages to send to the queue. These are simplified to
contain only the message body and attributes.
:return: The response from SQS that contains the list of successful and failed
messages.
"""
try:
entries = [
{
"Id": str(ind),
"MessageBody": msg["body"],
"MessageAttributes": msg["attributes"],
}
for ind, msg in enumerate(messages)
]
response = queue.send_messages(Entries=entries)
if "Successful" in response:
for msg_meta in response["Successful"]:
logger.info(
"Message sent: %s: %s",
msg_meta["MessageId"],
messages[int(msg_meta["Id"])]["body"],
)
if "Failed" in response:
for msg_meta in response["Failed"]:
logger.warning(
"Failed to send: %s: %s",
msg_meta["MessageId"],
messages[int(msg_meta["Id"])]["body"],
)
except ClientError as error:
logger.exception("Send messages failed to queue: %s", queue)
raise error
else:
return response
def receive_messages(queue, max_number, wait_time):
"""
Receive a batch of messages in a single request from an SQS queue.
:param queue: The queue from which to receive messages.
:param max_number: The maximum number of messages to receive. The actual number
of messages received might be less.
:param wait_time: The maximum time to wait (in seconds) before returning. When
this number is greater than zero, long polling is used. This
can result in reduced costs and fewer false empty responses.
:return: The list of Message objects received. These each contain the body
of the message and metadata and custom attributes.
"""
try:
messages = queue.receive_messages(
MessageAttributeNames=["All"],
MaxNumberOfMessages=max_number,
WaitTimeSeconds=wait_time,
)
for msg in messages:
logger.info("Received message: %s: %s", msg.message_id, msg.body)
except ClientError as error:
logger.exception("Couldn't receive messages from queue: %s", queue)
raise error
else:
return messages
def delete_messages(queue, messages):
"""
Delete a batch of messages from a queue in a single request.
:param queue: The queue from which to delete the messages.
:param messages: The list of messages to delete.
:return: The response from SQS that contains the list of successful and failed
message deletions.
"""
try:
entries = [
{"Id": str(ind), "ReceiptHandle": msg.receipt_handle}
for ind, msg in enumerate(messages)
]
response = queue.delete_messages(Entries=entries)
if "Successful" in response:
for msg_meta in response["Successful"]:
logger.info("Deleted %s", messages[int(msg_meta["Id"])].receipt_handle)
if "Failed" in response:
for msg_meta in response["Failed"]:
logger.warning(
"Could not delete %s", messages[int(msg_meta["Id"])].receipt_handle
)
except ClientError:
logger.exception("Couldn't delete messages from queue %s", queue)
else:
return response
```
ラッパー関数を使用してメッセージをバッチで送受信します。
```
def usage_demo():
"""
Shows how to:
* Read the lines from this Python file and send the lines in
batches of 10 as messages to a queue.
* Receive the messages in batches until the queue is empty.
* Reassemble the lines of the file and verify they match the original file.
"""
def pack_message(msg_path, msg_body, msg_line):
return {
"body": msg_body,
"attributes": {
"path": {"StringValue": msg_path, "DataType": "String"},
"line": {"StringValue": str(msg_line), "DataType": "String"},
},
}
def unpack_message(msg):
return (
msg.message_attributes["path"]["StringValue"],
msg.body,
int(msg.message_attributes["line"]["StringValue"]),
)
print("-" * 88)
print("Welcome to the Amazon Simple Queue Service (Amazon SQS) demo!")
print("-" * 88)
queue = queue_wrapper.create_queue("sqs-usage-demo-message-wrapper")
with open(__file__) as file:
lines = file.readlines()
line = 0
batch_size = 10
received_lines = [None] * len(lines)
print(f"Sending file lines in batches of {batch_size} as messages.")
while line < len(lines):
messages = [
pack_message(__file__, lines[index], index)
for index in range(line, min(line + batch_size, len(lines)))
]
line = line + batch_size
send_messages(queue, messages)
print(".", end="")
sys.stdout.flush()
print(f"Done. Sent {len(lines) - 1} messages.")
print(f"Receiving, handling, and deleting messages in batches of {batch_size}.")
more_messages = True
while more_messages:
received_messages = receive_messages(queue, batch_size, 2)
print(".", end="")
sys.stdout.flush()
for message in received_messages:
path, body, line = unpack_message(message)
received_lines[line] = body
if received_messages:
delete_messages(queue, received_messages)
else:
more_messages = False
print("Done.")
if all([lines[index] == received_lines[index] for index in range(len(lines))]):
print(f"Successfully reassembled all file lines!")
else:
print(f"Uh oh, some lines were missed!")
queue.delete()
print("Thanks for watching!")
print("-" * 88)
```
+ API の詳細については、「**AWS SDK for Python (Boto3) API リファレンス」の以下のトピックを参照してください。
+ [CreateQueue](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/CreateQueue)
+ [DeleteMessage](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/DeleteMessage)
+ [DeleteMessageBatch](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/DeleteMessageBatch)
+ [DeleteQueue](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/DeleteQueue)
+ [ReceiveMessage](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/ReceiveMessage)
+ [SendMessage](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/SendMessage)
+ [SendMessageBatch](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/SendMessageBatch)
## サーバーレスサンプル
### Amazon SQS トリガーから Lambda 関数を呼び出す
次のコード例では、SQS キューからメッセージを受信することによってトリガーされるイベントを受け取る、Lambda 関数の実装方法を示しています。この関数はイベントパラメータからメッセージを取得し、各メッセージの内容を記録します。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。[サーバーレスサンプル](https://github.com/aws-samples/serverless-snippets/tree/main/integration-sqs-to-lambda)リポジトリで完全な例を見つけて、設定と実行の方法を確認してください。
Python を使用した Lambda での SQS イベントの消費。
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
def lambda_handler(event, context):
for message in event['Records']:
process_message(message)
print("done")
def process_message(message):
try:
print(f"Processed message {message['body']}")
# TODO: Do interesting work based on the new message
except Exception as err:
print("An error occurred")
raise err
```
### Amazon SQS トリガーを使用した Lambda 関数でのバッチアイテム失敗のレポート
以下のコード例では、SQS キューからイベントを受け取る Lambda 関数のための、部分的なバッチレスポンスの実装方法を示しています。この関数は、レスポンスとしてバッチアイテムの失敗を報告し、対象のメッセージを後で再試行するよう Lambda に伝えます。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。[サーバーレスサンプル](https://github.com/aws-samples/serverless-snippets/tree/main/lambda-function-sqs-report-batch-item-failures)リポジトリで完全な例を見つけて、設定と実行の方法を確認してください。
Python を使用した Lambda での SQS バッチアイテム失敗のレポート。
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
def lambda_handler(event, context):
if event:
batch_item_failures = []
sqs_batch_response = {}
for record in event["Records"]:
try:
print(f"Processed message: {record['body']}")
except Exception as e:
batch_item_failures.append({"itemIdentifier": record['messageId']})
sqs_batch_response["batchItemFailures"] = batch_item_failures
return sqs_batch_response
```
# SDK for Python (Boto3) を使用した Step Functions の例
次のコード例は、Step Functions AWS SDK for Python (Boto3) で を使用してアクションを実行し、一般的なシナリオを実装する方法を示しています。
*基本* は、重要なオペレーションをサービス内で実行する方法を示すコード例です。
*アクション*はより大きなプログラムからのコードの抜粋であり、コンテキスト内で実行する必要があります。アクションは個々のサービス機能を呼び出す方法を示していますが、コンテキスト内のアクションは、関連するシナリオで確認できます。
*シナリオ*は、1 つのサービス内から、または他の AWS のサービスと組み合わせて複数の関数を呼び出し、特定のタスクを実行する方法を示すコード例です。
各例には完全なソースコードへのリンクが含まれており、コンテキスト内でコードを設定および実行する方法の手順を確認できます。
**Topics**
+ [はじめに](#get_started)
+ [基本](#basics)
+ [アクション](#actions)
+ [シナリオ](#scenarios)
## はじめに
### Hello Step Functions
次のコード例は、Step Functions の使用を開始する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/stepfunctions#code-examples)での設定と実行の方法を確認してください。
```
import boto3
def hello_stepfunctions(stepfunctions_client):
"""
Use the AWS SDK for Python (Boto3) to create an AWS Step Functions client and list
the state machines in your account. This list might be empty if you haven't created
any state machines.
This example uses the default settings specified in your shared credentials
and config files.
:param stepfunctions_client: A Boto3 Step Functions Client object.
"""
print("Hello, Step Functions! Let's list up to 10 of your state machines:")
state_machines = stepfunctions_client.list_state_machines(maxResults=10)
for sm in state_machines["stateMachines"]:
print(f"\t{sm['name']}: {sm['stateMachineArn']}")
if __name__ == "__main__":
hello_stepfunctions(boto3.client("stepfunctions"))
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[ListStateMachines](https://docs.aws.amazon.com/goto/boto3/states-2016-11-23/ListStateMachines)」を参照してください。
## 基本
### 基本を学ぶ
次のコード例は、以下の操作方法を示しています。
+ アクティビティを作成します。
+ 以前に作成したアクティビティをステップとして含む Amazon States Language 定義からステートマシンを作成します。
+ ステートマシンを実行し、ユーザー入力でアクティビティに応答します。
+ 実行が完了したら最終ステータスと出力を取得して、リソースをクリーンアップします。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/stepfunctions#code-examples)での設定と実行の方法を確認してください。
コマンドプロンプトからインタラクティブなシナリオを実行します。
```
class StateMachineScenario:
"""Runs an interactive scenario that shows how to get started using Step Functions."""
def __init__(self, activity, state_machine, iam_client):
"""
:param activity: An object that wraps activity actions.
:param state_machine: An object that wraps state machine actions.
:param iam_client: A Boto3 AWS Identity and Access Management (IAM) client.
"""
self.activity = activity
self.state_machine = state_machine
self.iam_client = iam_client
self.state_machine_role = None
def prerequisites(self, state_machine_role_name):
"""
Finds or creates an IAM role that can be assumed by Step Functions.
A role of this kind is required to create a state machine.
The state machine used in this example does not call any additional services,
so it needs no additional permissions.
:param state_machine_role_name: The name of the role.
:return: Data about the role.
"""
trust_policy = {
"Version":"2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {"Service": "states.amazonaws.com"},
"Action": "sts:AssumeRole",
}
],
}
try:
role = self.iam_client.get_role(RoleName=state_machine_role_name)
print(f"Prerequisite IAM role {state_machine_role_name} already exists.")
except ClientError as err:
if err.response["Error"]["Code"] == "NoSuchEntity":
role = None
else:
logger.error(
"Couldn't get prerequisite IAM role %s. Here's why: %s: %s",
state_machine_role_name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
if role is None:
try:
role = self.iam_client.create_role(
RoleName=state_machine_role_name,
AssumeRolePolicyDocument=json.dumps(trust_policy),
)
except ClientError as err:
logger.error(
"Couldn't create prerequisite IAM role %s. Here's why: %s: %s",
state_machine_role_name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
self.state_machine_role = role["Role"]
def find_or_create_activity(self, activity_name):
"""
Finds or creates a Step Functions activity.
:param activity_name: The name of the activity.
:return: The Amazon Resource Name (ARN) of the activity.
"""
print("First, let's set up an activity and state machine.")
activity_arn = self.activity.find(activity_name)
if activity_arn is None:
activity_arn = self.activity.create(activity_name)
print(
f"Activity {activity_name} created. Its Amazon Resource Name (ARN) is "
f"{activity_arn}."
)
else:
print(f"Activity {activity_name} already exists.")
return activity_arn
def find_or_create_state_machine(
self, state_machine_name, activity_arn, state_machine_file
):
"""
Finds or creates a Step Functions state machine.
:param state_machine_name: The name of the state machine.
:param activity_arn: The ARN of an activity that is used as a step in the state
machine. This ARN is injected into the state machine
definition that's used to create the state machine.
:param state_machine_file: The path to a file containing the state machine
definition.
:return: The ARN of the state machine.
"""
state_machine_arn = self.state_machine.find(state_machine_name)
if state_machine_arn is None:
with open(state_machine_file) as state_machine_file:
state_machine_def = state_machine_file.read().replace(
"{{DOC_EXAMPLE_ACTIVITY_ARN}}", activity_arn
)
state_machine_arn = self.state_machine.create(
state_machine_name,
state_machine_def,
self.state_machine_role["Arn"],
)
print(f"State machine {state_machine_name} created.")
else:
print(f"State machine {state_machine_name} already exists.")
print("-" * 88)
print(f"Here's some information about state machine {state_machine_name}:")
state_machine_info = self.state_machine.describe(state_machine_arn)
for field in ["name", "status", "stateMachineArn", "roleArn"]:
print(f"\t{field}: {state_machine_info[field]}")
return state_machine_arn
def run_state_machine(self, state_machine_arn, activity_arn):
"""
Run the state machine. The state machine used in this example is a simple
chat simulation. It contains an activity step in a loop that is used for user
interaction. When the state machine gets to the activity step, it waits for
an external application to get task data and submit a response. This function
acts as the activity application by getting task input and responding with
user input.
:param state_machine_arn: The ARN of the state machine.
:param activity_arn: The ARN of the activity used as a step in the state machine.
:return: The ARN of the run.
"""
print(
f"Let's run the state machine. It's a simplistic, non-AI chat simulator "
f"we'll call ChatSFN."
)
user_name = q.ask("What should ChatSFN call you? ", q.non_empty)
run_input = {"name": user_name}
print("Starting state machine...")
run_arn = self.state_machine.start(state_machine_arn, json.dumps(run_input))
action = None
while action != "done":
activity_task = self.activity.get_task(activity_arn)
task_input = json.loads(activity_task["input"])
print(f"ChatSFN: {task_input['message']}")
action = task_input["actions"][
q.choose("What now? ", task_input["actions"])
]
task_response = {"action": action}
self.activity.send_task_success(
activity_task["taskToken"], json.dumps(task_response)
)
return run_arn
def finish_state_machine_run(self, run_arn):
"""
Wait for the state machine run to finish, then print final status and output.
:param run_arn: The ARN of the run to retrieve.
"""
print(f"Let's get the final output from the state machine:")
status = "RUNNING"
while status == "RUNNING":
run_output = self.state_machine.describe_run(run_arn)
status = run_output["status"]
if status == "RUNNING":
print(
"The state machine is still running, let's wait for it to finish."
)
wait(1)
elif status == "SUCCEEDED":
print(f"ChatSFN: {json.loads(run_output['output'])['message']}")
else:
print(f"Run status: {status}.")
def cleanup(
self,
state_machine_name,
state_machine_arn,
activity_name,
activity_arn,
state_machine_role_name,
):
"""
Clean up resources created by this example.
:param state_machine_name: The name of the state machine.
:param state_machine_arn: The ARN of the state machine.
:param activity_name: The name of the activity.
:param activity_arn: The ARN of the activity.
:param state_machine_role_name: The name of the role used by the state machine.
"""
if q.ask(
"Do you want to delete the state machine, activity, and role created for this "
"example? (y/n) ",
q.is_yesno,
):
self.state_machine.delete(state_machine_arn)
print(f"Deleted state machine {state_machine_name}.")
self.activity.delete(activity_arn)
print(f"Deleted activity {activity_name}.")
self.iam_client.delete_role(RoleName=state_machine_role_name)
print(f"Deleted role {state_machine_role_name}.")
def run_scenario(self, activity_name, state_machine_name):
print("-" * 88)
print("Welcome to the AWS Step Functions state machines demo.")
print("-" * 88)
activity_arn = self.find_or_create_activity(activity_name)
state_machine_arn = self.find_or_create_state_machine(
state_machine_name,
activity_arn,
"../../../resources/sample_files/chat_sfn_state_machine.json",
)
print("-" * 88)
run_arn = self.run_state_machine(state_machine_arn, activity_arn)
print("-" * 88)
self.finish_state_machine_run(run_arn)
print("-" * 88)
self.cleanup(
state_machine_name,
state_machine_arn,
activity_name,
activity_arn,
self.state_machine_role["RoleName"],
)
print("-" * 88)
print("\nThanks for watching!")
print("-" * 88)
if __name__ == "__main__":
logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
try:
stepfunctions_client = boto3.client("stepfunctions")
iam_client = boto3.client("iam")
scenario = StateMachineScenario(
Activity(stepfunctions_client),
StateMachine(stepfunctions_client),
iam_client,
)
scenario.prerequisites("doc-example-state-machine-chat")
scenario.run_scenario("doc-example-activity", "doc-example-state-machine")
except Exception:
logging.exception("Something went wrong with the demo.")
```
ステートマシンアクションをラップするクラスを定義します。
```
class StateMachine:
"""Encapsulates Step Functions state machine actions."""
def __init__(self, stepfunctions_client):
"""
:param stepfunctions_client: A Boto3 Step Functions client.
"""
self.stepfunctions_client = stepfunctions_client
def create(self, name, definition, role_arn):
"""
Creates a state machine with the specific definition. The state machine assumes
the provided role before it starts a run.
:param name: The name to give the state machine.
:param definition: The Amazon States Language definition of the steps in the
the state machine.
:param role_arn: The Amazon Resource Name (ARN) of the role that is assumed by
Step Functions when the state machine is run.
:return: The ARN of the newly created state machine.
"""
try:
response = self.stepfunctions_client.create_state_machine(
name=name, definition=definition, roleArn=role_arn
)
except ClientError as err:
logger.error(
"Couldn't create state machine %s. Here's why: %s: %s",
name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return response["stateMachineArn"]
def find(self, name):
"""
Find a state machine by name. This requires listing the state machines until
one is found with a matching name.
:param name: The name of the state machine to search for.
:return: The ARN of the state machine if found; otherwise, None.
"""
try:
paginator = self.stepfunctions_client.get_paginator("list_state_machines")
for page in paginator.paginate():
for state_machine in page.get("stateMachines", []):
if state_machine["name"] == name:
return state_machine["stateMachineArn"]
except ClientError as err:
logger.error(
"Couldn't list state machines. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
def describe(self, state_machine_arn):
"""
Get data about a state machine.
:param state_machine_arn: The ARN of the state machine to look up.
:return: The retrieved state machine data.
"""
try:
response = self.stepfunctions_client.describe_state_machine(
stateMachineArn=state_machine_arn
)
except ClientError as err:
logger.error(
"Couldn't describe state machine %s. Here's why: %s: %s",
state_machine_arn,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return response
def start(self, state_machine_arn, run_input):
"""
Start a run of a state machine with a specified input. A run is also known
as an "execution" in Step Functions.
:param state_machine_arn: The ARN of the state machine to run.
:param run_input: The input to the state machine, in JSON format.
:return: The ARN of the run. This can be used to get information about the run,
including its current status and final output.
"""
try:
response = self.stepfunctions_client.start_execution(
stateMachineArn=state_machine_arn, input=run_input
)
except ClientError as err:
logger.error(
"Couldn't start state machine %s. Here's why: %s: %s",
state_machine_arn,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return response["executionArn"]
def describe_run(self, run_arn):
"""
Get data about a state machine run, such as its current status or final output.
:param run_arn: The ARN of the run to look up.
:return: The retrieved run data.
"""
try:
response = self.stepfunctions_client.describe_execution(
executionArn=run_arn
)
except ClientError as err:
logger.error(
"Couldn't describe run %s. Here's why: %s: %s",
run_arn,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return response
def delete(self, state_machine_arn):
"""
Delete a state machine and all of its run data.
:param state_machine_arn: The ARN of the state machine to delete.
"""
try:
response = self.stepfunctions_client.delete_state_machine(
stateMachineArn=state_machine_arn
)
except ClientError as err:
logger.error(
"Couldn't delete state machine %s. Here's why: %s: %s",
state_machine_arn,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return response
```
アクティビティアクションをラップするクラスを定義します。
```
class Activity:
"""Encapsulates Step Function activity actions."""
def __init__(self, stepfunctions_client):
"""
:param stepfunctions_client: A Boto3 Step Functions client.
"""
self.stepfunctions_client = stepfunctions_client
def create(self, name):
"""
Create an activity.
:param name: The name of the activity to create.
:return: The Amazon Resource Name (ARN) of the newly created activity.
"""
try:
response = self.stepfunctions_client.create_activity(name=name)
except ClientError as err:
logger.error(
"Couldn't create activity %s. Here's why: %s: %s",
name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return response["activityArn"]
def find(self, name):
"""
Find an activity by name. This requires listing activities until one is found
with a matching name.
:param name: The name of the activity to search for.
:return: If found, the ARN of the activity; otherwise, None.
"""
try:
paginator = self.stepfunctions_client.get_paginator("list_activities")
for page in paginator.paginate():
for activity in page.get("activities", []):
if activity["name"] == name:
return activity["activityArn"]
except ClientError as err:
logger.error(
"Couldn't list activities. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
def get_task(self, activity_arn):
"""
Gets task data for an activity. When a state machine is waiting for the
specified activity, a response is returned with data from the state machine.
When a state machine is not waiting, this call blocks for 60 seconds.
:param activity_arn: The ARN of the activity to get task data for.
:return: The task data for the activity.
"""
try:
response = self.stepfunctions_client.get_activity_task(
activityArn=activity_arn
)
except ClientError as err:
logger.error(
"Couldn't get a task for activity %s. Here's why: %s: %s",
activity_arn,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return response
def send_task_success(self, task_token, task_response):
"""
Sends a success response to a waiting activity step. A state machine with an
activity step waits for the activity to get task data and then respond with
either success or failure before it resumes processing.
:param task_token: The token associated with the task. This is included in the
response to the get_activity_task action and must be sent
without modification.
:param task_response: The response data from the activity. This data is
received and processed by the state machine.
"""
try:
self.stepfunctions_client.send_task_success(
taskToken=task_token, output=task_response
)
except ClientError as err:
logger.error(
"Couldn't send task success. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
def delete(self, activity_arn):
"""
Delete an activity.
:param activity_arn: The ARN of the activity to delete.
"""
try:
response = self.stepfunctions_client.delete_activity(
activityArn=activity_arn
)
except ClientError as err:
logger.error(
"Couldn't delete activity %s. Here's why: %s: %s",
activity_arn,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return response
```
+ API の詳細については、「**AWS SDK for Python (Boto3) API リファレンス」の以下のトピックを参照してください。
+ [CreateActivity](https://docs.aws.amazon.com/goto/boto3/states-2016-11-23/CreateActivity)
+ [CreateStateMachine](https://docs.aws.amazon.com/goto/boto3/states-2016-11-23/CreateStateMachine)
+ [DeleteActivity](https://docs.aws.amazon.com/goto/boto3/states-2016-11-23/DeleteActivity)
+ [DeleteStateMachine](https://docs.aws.amazon.com/goto/boto3/states-2016-11-23/DeleteStateMachine)
+ [DescribeExecution](https://docs.aws.amazon.com/goto/boto3/states-2016-11-23/DescribeExecution)
+ [DescribeStateMachine](https://docs.aws.amazon.com/goto/boto3/states-2016-11-23/DescribeStateMachine)
+ [GetActivityTask](https://docs.aws.amazon.com/goto/boto3/states-2016-11-23/GetActivityTask)
+ [ListActivities](https://docs.aws.amazon.com/goto/boto3/states-2016-11-23/ListActivities)
+ [ListStateMachines](https://docs.aws.amazon.com/goto/boto3/states-2016-11-23/ListStateMachines)
+ [SendTaskSuccess](https://docs.aws.amazon.com/goto/boto3/states-2016-11-23/SendTaskSuccess)
+ [StartExecution](https://docs.aws.amazon.com/goto/boto3/states-2016-11-23/StartExecution)
+ [StopExecution](https://docs.aws.amazon.com/goto/boto3/states-2016-11-23/StopExecution)
## アクション
### `CreateActivity`
次のコード例は、`CreateActivity` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/stepfunctions#code-examples)での設定と実行の方法を確認してください。
```
class Activity:
"""Encapsulates Step Function activity actions."""
def __init__(self, stepfunctions_client):
"""
:param stepfunctions_client: A Boto3 Step Functions client.
"""
self.stepfunctions_client = stepfunctions_client
def create(self, name):
"""
Create an activity.
:param name: The name of the activity to create.
:return: The Amazon Resource Name (ARN) of the newly created activity.
"""
try:
response = self.stepfunctions_client.create_activity(name=name)
except ClientError as err:
logger.error(
"Couldn't create activity %s. Here's why: %s: %s",
name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return response["activityArn"]
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[CreateActivity](https://docs.aws.amazon.com/goto/boto3/states-2016-11-23/CreateActivity)」を参照してください。
### `CreateStateMachine`
次のコード例は、`CreateStateMachine` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/stepfunctions#code-examples)での設定と実行の方法を確認してください。
```
class StateMachine:
"""Encapsulates Step Functions state machine actions."""
def __init__(self, stepfunctions_client):
"""
:param stepfunctions_client: A Boto3 Step Functions client.
"""
self.stepfunctions_client = stepfunctions_client
def create(self, name, definition, role_arn):
"""
Creates a state machine with the specific definition. The state machine assumes
the provided role before it starts a run.
:param name: The name to give the state machine.
:param definition: The Amazon States Language definition of the steps in the
the state machine.
:param role_arn: The Amazon Resource Name (ARN) of the role that is assumed by
Step Functions when the state machine is run.
:return: The ARN of the newly created state machine.
"""
try:
response = self.stepfunctions_client.create_state_machine(
name=name, definition=definition, roleArn=role_arn
)
except ClientError as err:
logger.error(
"Couldn't create state machine %s. Here's why: %s: %s",
name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return response["stateMachineArn"]
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[CreateStateMachine](https://docs.aws.amazon.com/goto/boto3/states-2016-11-23/CreateStateMachine)」を参照してください。
### `DeleteActivity`
次のコード例は、`DeleteActivity` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/stepfunctions#code-examples)での設定と実行の方法を確認してください。
```
class Activity:
"""Encapsulates Step Function activity actions."""
def __init__(self, stepfunctions_client):
"""
:param stepfunctions_client: A Boto3 Step Functions client.
"""
self.stepfunctions_client = stepfunctions_client
def delete(self, activity_arn):
"""
Delete an activity.
:param activity_arn: The ARN of the activity to delete.
"""
try:
response = self.stepfunctions_client.delete_activity(
activityArn=activity_arn
)
except ClientError as err:
logger.error(
"Couldn't delete activity %s. Here's why: %s: %s",
activity_arn,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return response
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[DeleteActivity](https://docs.aws.amazon.com/goto/boto3/states-2016-11-23/DeleteActivity)」を参照してください。
### `DeleteStateMachine`
次のコード例は、`DeleteStateMachine` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/stepfunctions#code-examples)での設定と実行の方法を確認してください。
```
class StateMachine:
"""Encapsulates Step Functions state machine actions."""
def __init__(self, stepfunctions_client):
"""
:param stepfunctions_client: A Boto3 Step Functions client.
"""
self.stepfunctions_client = stepfunctions_client
def delete(self, state_machine_arn):
"""
Delete a state machine and all of its run data.
:param state_machine_arn: The ARN of the state machine to delete.
"""
try:
response = self.stepfunctions_client.delete_state_machine(
stateMachineArn=state_machine_arn
)
except ClientError as err:
logger.error(
"Couldn't delete state machine %s. Here's why: %s: %s",
state_machine_arn,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return response
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[DeleteStateMachine](https://docs.aws.amazon.com/goto/boto3/states-2016-11-23/DeleteStateMachine)」を参照してください。
### `DescribeExecution`
次のコード例は、`DescribeExecution` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/stepfunctions#code-examples)での設定と実行の方法を確認してください。
```
def describe_run(self, run_arn):
"""
Get data about a state machine run, such as its current status or final output.
:param run_arn: The ARN of the run to look up.
:return: The retrieved run data.
"""
try:
response = self.stepfunctions_client.describe_execution(
executionArn=run_arn
)
except ClientError as err:
logger.error(
"Couldn't describe run %s. Here's why: %s: %s",
run_arn,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return response
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[DescribeExecution](https://docs.aws.amazon.com/goto/boto3/states-2016-11-23/DescribeExecution)」を参照してください。
### `DescribeStateMachine`
次のコード例は、`DescribeStateMachine` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/stepfunctions#code-examples)での設定と実行の方法を確認してください。
```
class StateMachine:
"""Encapsulates Step Functions state machine actions."""
def __init__(self, stepfunctions_client):
"""
:param stepfunctions_client: A Boto3 Step Functions client.
"""
self.stepfunctions_client = stepfunctions_client
def describe(self, state_machine_arn):
"""
Get data about a state machine.
:param state_machine_arn: The ARN of the state machine to look up.
:return: The retrieved state machine data.
"""
try:
response = self.stepfunctions_client.describe_state_machine(
stateMachineArn=state_machine_arn
)
except ClientError as err:
logger.error(
"Couldn't describe state machine %s. Here's why: %s: %s",
state_machine_arn,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return response
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[DescribeStateMachine](https://docs.aws.amazon.com/goto/boto3/states-2016-11-23/DescribeStateMachine)」を参照してください。
### `GetActivityTask`
次のコード例は、`GetActivityTask` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/stepfunctions#code-examples)での設定と実行の方法を確認してください。
```
class Activity:
"""Encapsulates Step Function activity actions."""
def __init__(self, stepfunctions_client):
"""
:param stepfunctions_client: A Boto3 Step Functions client.
"""
self.stepfunctions_client = stepfunctions_client
def get_task(self, activity_arn):
"""
Gets task data for an activity. When a state machine is waiting for the
specified activity, a response is returned with data from the state machine.
When a state machine is not waiting, this call blocks for 60 seconds.
:param activity_arn: The ARN of the activity to get task data for.
:return: The task data for the activity.
"""
try:
response = self.stepfunctions_client.get_activity_task(
activityArn=activity_arn
)
except ClientError as err:
logger.error(
"Couldn't get a task for activity %s. Here's why: %s: %s",
activity_arn,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return response
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[GetActivityTask](https://docs.aws.amazon.com/goto/boto3/states-2016-11-23/GetActivityTask)」を参照してください。
### `ListActivities`
次のコード例は、`ListActivities` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/stepfunctions#code-examples)での設定と実行の方法を確認してください。
```
class Activity:
"""Encapsulates Step Function activity actions."""
def __init__(self, stepfunctions_client):
"""
:param stepfunctions_client: A Boto3 Step Functions client.
"""
self.stepfunctions_client = stepfunctions_client
def find(self, name):
"""
Find an activity by name. This requires listing activities until one is found
with a matching name.
:param name: The name of the activity to search for.
:return: If found, the ARN of the activity; otherwise, None.
"""
try:
paginator = self.stepfunctions_client.get_paginator("list_activities")
for page in paginator.paginate():
for activity in page.get("activities", []):
if activity["name"] == name:
return activity["activityArn"]
except ClientError as err:
logger.error(
"Couldn't list activities. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[ListActivities](https://docs.aws.amazon.com/goto/boto3/states-2016-11-23/ListActivities)」を参照してください。
### `ListStateMachines`
次のコード例は、`ListStateMachines` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/stepfunctions#code-examples)での設定と実行の方法を確認してください。
アカウントのステートマシンのリストを検索して、ステートマシンを名前で検索します。
```
class StateMachine:
"""Encapsulates Step Functions state machine actions."""
def __init__(self, stepfunctions_client):
"""
:param stepfunctions_client: A Boto3 Step Functions client.
"""
self.stepfunctions_client = stepfunctions_client
def find(self, name):
"""
Find a state machine by name. This requires listing the state machines until
one is found with a matching name.
:param name: The name of the state machine to search for.
:return: The ARN of the state machine if found; otherwise, None.
"""
try:
paginator = self.stepfunctions_client.get_paginator("list_state_machines")
for page in paginator.paginate():
for state_machine in page.get("stateMachines", []):
if state_machine["name"] == name:
return state_machine["stateMachineArn"]
except ClientError as err:
logger.error(
"Couldn't list state machines. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[ListStateMachines](https://docs.aws.amazon.com/goto/boto3/states-2016-11-23/ListStateMachines)」を参照してください。
### `SendTaskSuccess`
次のコード例は、`SendTaskSuccess` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/stepfunctions#code-examples)での設定と実行の方法を確認してください。
```
class Activity:
"""Encapsulates Step Function activity actions."""
def __init__(self, stepfunctions_client):
"""
:param stepfunctions_client: A Boto3 Step Functions client.
"""
self.stepfunctions_client = stepfunctions_client
def send_task_success(self, task_token, task_response):
"""
Sends a success response to a waiting activity step. A state machine with an
activity step waits for the activity to get task data and then respond with
either success or failure before it resumes processing.
:param task_token: The token associated with the task. This is included in the
response to the get_activity_task action and must be sent
without modification.
:param task_response: The response data from the activity. This data is
received and processed by the state machine.
"""
try:
self.stepfunctions_client.send_task_success(
taskToken=task_token, output=task_response
)
except ClientError as err:
logger.error(
"Couldn't send task success. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[SendTaskSuccess](https://docs.aws.amazon.com/goto/boto3/states-2016-11-23/SendTaskSuccess)」を参照してください。
### `StartExecution`
次のコード例は、`StartExecution` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/stepfunctions#code-examples)での設定と実行の方法を確認してください。
```
class StateMachine:
"""Encapsulates Step Functions state machine actions."""
def __init__(self, stepfunctions_client):
"""
:param stepfunctions_client: A Boto3 Step Functions client.
"""
self.stepfunctions_client = stepfunctions_client
def start(self, state_machine_arn, run_input):
"""
Start a run of a state machine with a specified input. A run is also known
as an "execution" in Step Functions.
:param state_machine_arn: The ARN of the state machine to run.
:param run_input: The input to the state machine, in JSON format.
:return: The ARN of the run. This can be used to get information about the run,
including its current status and final output.
"""
try:
response = self.stepfunctions_client.start_execution(
stateMachineArn=state_machine_arn, input=run_input
)
except ClientError as err:
logger.error(
"Couldn't start state machine %s. Here's why: %s: %s",
state_machine_arn,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return response["executionArn"]
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[StartExecution](https://docs.aws.amazon.com/goto/boto3/states-2016-11-23/StartExecution)」を参照してください。
## シナリオ
### メッセンジャーアプリケーションを作成する
次のコード例は、データベーステーブルからメッセージレコードを取得する AWS Step Functions メッセンジャーアプリケーションを作成する方法を示しています。
**SDK for Python (Boto3)**
AWS SDK for Python (Boto3) で を使用して AWS Step Functions 、Amazon DynamoDB テーブルからメッセージレコードを取得し、Amazon Simple Queue Service (Amazon SQS) で送信するメッセンジャーアプリケーションを作成する方法を示します。ステートマシンは AWS Lambda 関数と統合して、未送信メッセージがないかデータベースをスキャンします。
+ Amazon DynamoDB テーブルからメッセージレコードを取得および更新するステートマシンを作成します。
+ ステートマシンの定義を更新して、Amazon Simple Queue Service (Amazon SQS) にもメッセージを送信します。
+ ステートマシンの実行を開始および停止します。
+ サービス統合を使用して、ステートマシンから Lambda、DynamoDB、および Amazon SQS に接続します。
完全なソースコードとセットアップおよび実行の手順については、[GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/stepfunctions_messenger) で完全な例を参照してください。
**この例で使用されているサービス**
+ DynamoDB
+ Lambda
+ Amazon SQS
+ ステップ関数
### Step Functions を使用して生成 AI アプリケーションをオーケストレーションする
次のコード例は、Amazon Bedrock と Step Functions を使用して生成 AI アプリケーションを構築およびオーケストレーションする方法を示しています。
**SDK for Python (Boto3)**
Amazon Bedrock Serverless のプロンプトチェイニングシナリオは、[AWS Step Functions](https://docs.aws.amazon.com/step-functions/latest/dg/welcome.html)、[Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/what-is-bedrock.html)、および [https://docs.aws.amazon.com/bedrock/latest/userguide/agents.html](https://docs.aws.amazon.com/bedrock/latest/userguide/agents.html) を使用して、複雑でサーバーレス、高度にスケーラブルな生成 AI アプリケーションを構築およびオーケストレーションする方法を示しています。これには、次の実際の例が含まれています。
+ 文学ブログの特定の小説の分析を行う。この例では、プロンプトのシンプルでシーケンシャルなチェーンを示しています。
+ 特定のトピックに関する短いストーリーを生成する。この例では、AI が以前に生成した項目のリストを繰り返し処理する方法を示しています。
+ 特定の目的地への週末の旅程を作成する。この例では、複数の個別のプロンプトを並列化する方法を示しています。
+ 映画のプロデューサーに映画のアイデアを提案する。この例では、異なる推論パラメータを使用して同じプロンプトを並列化する方法、チェーン内の前のステップにバックトラックする方法、ワークフローの一部として人間の入力を含める方法を示しています。
+ ユーザーの手元にある材料に基づいて料理を計画する。この例では、プロンプトチェーンが 2 つの異なる AI 会話を組み込んで、2 つの AI ペルソナが相互に議論を行い、最終的な結果を改善する方法を示しています。
+ 当日中で最も人気のある GitHub リポジトリを検索して要約する。この例では、外部 API とやり取りする複数の AI エージェントをチェーンさせる方法を示しています。
完全なソースコードと設定および実行の手順については、[GitHub](https://github.com/aws-samples/amazon-bedrock-serverless-prompt-chaining) で完全なプロジェクトを参照してください。
**この例で使用されているサービス**
+ Amazon Bedrock
+ Amazon Bedrock ランタイム
+ Amazon Bedrock エージェント
+ Amazon Bedrock エージェントランタイム
+ ステップ関数
# AWS STS SDK for Python を使用した例 (Boto3)
次のコード例は、 AWS SDK for Python (Boto3) で を使用してアクションを実行し、一般的なシナリオを実装する方法を示しています AWS STS。
*アクション*はより大きなプログラムからのコードの抜粋であり、コンテキスト内で実行する必要があります。アクションは個々のサービス機能を呼び出す方法を示していますが、コンテキスト内のアクションは、関連するシナリオで確認できます。
*シナリオ*は、1 つのサービス内から、または他の AWS のサービスと組み合わせて複数の関数を呼び出し、特定のタスクを実行する方法を示すコード例です。
各例には完全なソースコードへのリンクが含まれており、コードの設定方法と実行方法に関する手順を確認できます。
**Topics**
+ [アクション](#actions)
+ [シナリオ](#scenarios)
## アクション
### `AssumeRole`
次のコード例は、`AssumeRole` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sts#code-examples)での設定と実行の方法を確認してください。
MFA トークンを必要とする IAM ロールを想定し、一時的な認証情報を使用してアカウントの Amazon S3 バケットを一覧表示します。
```
def list_buckets_from_assumed_role_with_mfa(
assume_role_arn, session_name, mfa_serial_number, mfa_totp, sts_client
):
"""
Assumes a role from another account and uses the temporary credentials from
that role to list the Amazon S3 buckets that are owned by the other account.
Requires an MFA device serial number and token.
The assumed role must grant permission to list the buckets in the other account.
:param assume_role_arn: The Amazon Resource Name (ARN) of the role that
grants access to list the other account's buckets.
:param session_name: The name of the STS session.
:param mfa_serial_number: The serial number of the MFA device. For a virtual MFA
device, this is an ARN.
:param mfa_totp: A time-based, one-time password issued by the MFA device.
:param sts_client: A Boto3 STS instance that has permission to assume the role.
"""
response = sts_client.assume_role(
RoleArn=assume_role_arn,
RoleSessionName=session_name,
SerialNumber=mfa_serial_number,
TokenCode=mfa_totp,
)
temp_credentials = response["Credentials"]
print(f"Assumed role {assume_role_arn} and got temporary credentials.")
s3_resource = boto3.resource(
"s3",
aws_access_key_id=temp_credentials["AccessKeyId"],
aws_secret_access_key=temp_credentials["SecretAccessKey"],
aws_session_token=temp_credentials["SessionToken"],
)
print(f"Listing buckets for the assumed role's account:")
for bucket in s3_resource.buckets.all():
print(bucket.name)
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[AssumeRole](https://docs.aws.amazon.com/goto/boto3/sts-2011-06-15/AssumeRole)」を参照してください。
### `GetSessionToken`
次のコード例は、`GetSessionToken` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sts#code-examples)での設定と実行の方法を確認してください。
MFA トークンを渡してセッショントークンを取得し、それを使用してアカウントの Amazon S3 バケットを一覧表示します。
```
def list_buckets_with_session_token_with_mfa(mfa_serial_number, mfa_totp, sts_client):
"""
Gets a session token with MFA credentials and uses the temporary session
credentials to list Amazon S3 buckets.
Requires an MFA device serial number and token.
:param mfa_serial_number: The serial number of the MFA device. For a virtual MFA
device, this is an Amazon Resource Name (ARN).
:param mfa_totp: A time-based, one-time password issued by the MFA device.
:param sts_client: A Boto3 STS instance that has permission to assume the role.
"""
if mfa_serial_number is not None:
response = sts_client.get_session_token(
SerialNumber=mfa_serial_number, TokenCode=mfa_totp
)
else:
response = sts_client.get_session_token()
temp_credentials = response["Credentials"]
s3_resource = boto3.resource(
"s3",
aws_access_key_id=temp_credentials["AccessKeyId"],
aws_secret_access_key=temp_credentials["SecretAccessKey"],
aws_session_token=temp_credentials["SessionToken"],
)
print(f"Buckets for the account:")
for bucket in s3_resource.buckets.all():
print(bucket.name)
```
+ API の詳細については、「AWS SDK for Python (Boto3) API リファレンス」の「[GetSessionToken](https://docs.aws.amazon.com/goto/boto3/sts-2011-06-15/GetSessionToken)」を参照してください。
## シナリオ
### MFA トークンを必要とする IAM ロールを割り当てる
次のコード例は、MFA トークンを必要とするロールを引き受ける方法を示しています。
**警告**
セキュリティリスクを避けるため、専用ソフトウェアの開発や実際のデータを扱うときは、IAM ユーザーを認証に使用しないでください。代わりに、[AWS IAM アイデンティティセンター](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html) などの ID プロバイダーとのフェデレーションを使用してください。
+ Amazon S3 バケットを一覧表示するためのアクセス許可を付与する、IAM ロールを作成します。
+ MFA 認証情報が指定された場合にのみロールを引き受けることが許可された、IAM ユーザーを作成します。
+ ユーザーのための MFA デバイスを登録します。
+ ロールを引き受け、Amazon S3 バケットを一覧表示するために一時的な認証情報を使用します。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sts#code-examples)での設定と実行の方法を確認してください。
IAM ユーザーを作成し、MFA デバイスを登録し、Amazon S3 バケットを一覧表示するアクセス許可を付与するためのロールを作成します。ユーザーには、ロールの引き受けのみ権限があります。
```
def setup(iam_resource):
"""
Creates a new user with no permissions.
Creates a new virtual MFA device.
Displays the QR code to seed the device.
Asks for two codes from the MFA device.
Registers the MFA device for the user.
Creates an access key pair for the user.
Creates a role with a policy that lets the user assume the role and requires MFA.
Creates a policy that allows listing Amazon S3 buckets.
Attaches the policy to the role.
Creates an inline policy for the user that lets the user assume the role.
For demonstration purposes, the user is created in the same account as the role,
but in practice the user would likely be from another account.
Any MFA device that can scan a QR code will work with this demonstration.
Common choices are mobile apps like LastPass Authenticator,
Microsoft Authenticator, or Google Authenticator.
:param iam_resource: A Boto3 AWS Identity and Access Management (IAM) resource
that has permissions to create users, roles, and policies
in the account.
:return: The newly created user, user key, virtual MFA device, and role.
"""
user = iam_resource.create_user(UserName=unique_name("user"))
print(f"Created user {user.name}.")
virtual_mfa_device = iam_resource.create_virtual_mfa_device(
VirtualMFADeviceName=unique_name("mfa")
)
print(f"Created virtual MFA device {virtual_mfa_device.serial_number}")
print(
f"Showing the QR code for the device. Scan this in the MFA app of your "
f"choice."
)
with open("qr.png", "wb") as qr_file:
qr_file.write(virtual_mfa_device.qr_code_png)
webbrowser.open(qr_file.name)
print(f"Enter two consecutive code from your MFA device.")
mfa_code_1 = input("Enter the first code: ")
mfa_code_2 = input("Enter the second code: ")
user.enable_mfa(
SerialNumber=virtual_mfa_device.serial_number,
AuthenticationCode1=mfa_code_1,
AuthenticationCode2=mfa_code_2,
)
os.remove(qr_file.name)
print(f"MFA device is registered with the user.")
user_key = user.create_access_key_pair()
print(f"Created access key pair for user.")
print(f"Wait for user to be ready.", end="")
progress_bar(10)
role = iam_resource.create_role(
RoleName=unique_name("role"),
AssumeRolePolicyDocument=json.dumps(
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {"AWS": user.arn},
"Action": "sts:AssumeRole",
"Condition": {"Bool": {"aws:MultiFactorAuthPresent": True}},
}
],
}
),
)
print(f"Created role {role.name} that requires MFA.")
policy = iam_resource.create_policy(
PolicyName=unique_name("policy"),
PolicyDocument=json.dumps(
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "s3:ListAllMyBuckets",
"Resource": "arn:aws:s3:::*",
}
],
}
),
)
role.attach_policy(PolicyArn=policy.arn)
print(f"Created policy {policy.policy_name} and attached it to the role.")
user.create_policy(
PolicyName=unique_name("user-policy"),
PolicyDocument=json.dumps(
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": role.arn,
}
],
}
),
)
print(
f"Created an inline policy for {user.name} that lets the user assume "
f"the role."
)
print("Give AWS time to propagate these new resources and connections.", end="")
progress_bar(10)
return user, user_key, virtual_mfa_device, role
```
MFA トークンなしでロールを引き受けることは許可されていないことを示します。
```
def try_to_assume_role_without_mfa(assume_role_arn, session_name, sts_client):
"""
Shows that attempting to assume the role without sending MFA credentials results
in an AccessDenied error.
:param assume_role_arn: The Amazon Resource Name (ARN) of the role to assume.
:param session_name: The name of the STS session.
:param sts_client: A Boto3 STS instance that has permission to assume the role.
"""
print(f"Trying to assume the role without sending MFA credentials...")
try:
sts_client.assume_role(RoleArn=assume_role_arn, RoleSessionName=session_name)
raise RuntimeError("Expected AccessDenied error.")
except ClientError as error:
if error.response["Error"]["Code"] == "AccessDenied":
print("Got AccessDenied.")
else:
raise
```
Amazon S3 バケットを一覧表示するためのアクセス許可を付与するロールを引き受け、必要な MFA トークンを渡して、バケットが一覧表示可能なことを出力します。
```
def list_buckets_from_assumed_role_with_mfa(
assume_role_arn, session_name, mfa_serial_number, mfa_totp, sts_client
):
"""
Assumes a role from another account and uses the temporary credentials from
that role to list the Amazon S3 buckets that are owned by the other account.
Requires an MFA device serial number and token.
The assumed role must grant permission to list the buckets in the other account.
:param assume_role_arn: The Amazon Resource Name (ARN) of the role that
grants access to list the other account's buckets.
:param session_name: The name of the STS session.
:param mfa_serial_number: The serial number of the MFA device. For a virtual MFA
device, this is an ARN.
:param mfa_totp: A time-based, one-time password issued by the MFA device.
:param sts_client: A Boto3 STS instance that has permission to assume the role.
"""
response = sts_client.assume_role(
RoleArn=assume_role_arn,
RoleSessionName=session_name,
SerialNumber=mfa_serial_number,
TokenCode=mfa_totp,
)
temp_credentials = response["Credentials"]
print(f"Assumed role {assume_role_arn} and got temporary credentials.")
s3_resource = boto3.resource(
"s3",
aws_access_key_id=temp_credentials["AccessKeyId"],
aws_secret_access_key=temp_credentials["SecretAccessKey"],
aws_session_token=temp_credentials["SessionToken"],
)
print(f"Listing buckets for the assumed role's account:")
for bucket in s3_resource.buckets.all():
print(bucket.name)
```
デモ用に作成されたリソースを破棄します。
```
def teardown(user, virtual_mfa_device, role):
"""
Removes all resources created during setup.
:param user: The demo user.
:param role: The demo role.
"""
for attached in role.attached_policies.all():
policy_name = attached.policy_name
role.detach_policy(PolicyArn=attached.arn)
attached.delete()
print(f"Detached and deleted {policy_name}.")
role.delete()
print(f"Deleted {role.name}.")
for user_pol in user.policies.all():
user_pol.delete()
print("Deleted inline user policy.")
for key in user.access_keys.all():
key.delete()
print("Deleted user's access key.")
for mfa in user.mfa_devices.all():
mfa.disassociate()
virtual_mfa_device.delete()
user.delete()
print(f"Deleted {user.name}.")
```
このシナリオは、前に定義した関数を使用して実行します。
```
def usage_demo():
"""Drives the demonstration."""
print("-" * 88)
print(
f"Welcome to the AWS Security Token Service assume role demo, "
f"starring multi-factor authentication (MFA)!"
)
print("-" * 88)
iam_resource = boto3.resource("iam")
user, user_key, virtual_mfa_device, role = setup(iam_resource)
print(f"Created {user.name} and {role.name}.")
try:
sts_client = boto3.client(
"sts", aws_access_key_id=user_key.id, aws_secret_access_key=user_key.secret
)
try_to_assume_role_without_mfa(role.arn, "demo-sts-session", sts_client)
mfa_totp = input("Enter the code from your registered MFA device: ")
list_buckets_from_assumed_role_with_mfa(
role.arn,
"demo-sts-session",
virtual_mfa_device.serial_number,
mfa_totp,
sts_client,
)
finally:
teardown(user, virtual_mfa_device, role)
print("Thanks for watching!")
```
+ API の詳細については、「AWS SDK for Python (Boto3) API リファレンス」の「[AssumeRole](https://docs.aws.amazon.com/goto/boto3/sts-2011-06-15/AssumeRole)」を参照してください。
### フェデレーションユーザー向け URL の作成
次のコード例は、以下の操作方法を示しています。
+ 現在のアカウントの Amazon S3 リソースに対する読み取り専用のアクセス権限を付与する IAM ロールを作成します。
+ AWS フェデレーションエンドポイントからセキュリティトークンを取得します。
+ フェデレーションされた認証情報を使用して、コンソールにアクセスする際に使用する URL を作成します。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sts#code-examples)での設定と実行の方法を確認してください。
現在のアカウントの Amazon S3 リソースに対する読み取り専用アクセス権限を付与するロールを作成します。
```
def setup(iam_resource):
"""
Creates a role that can be assumed by the current user.
Attaches a policy that allows only Amazon S3 read-only access.
:param iam_resource: A Boto3 AWS Identity and Access Management (IAM) instance
that has the permission to create a role.
:return: The newly created role.
"""
role = iam_resource.create_role(
RoleName=unique_name("role"),
AssumeRolePolicyDocument=json.dumps(
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {"AWS": iam_resource.CurrentUser().arn},
"Action": "sts:AssumeRole",
}
],
}
),
)
role.attach_policy(PolicyArn="arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess")
print(f"Created role {role.name}.")
print("Give AWS time to propagate these new resources and connections.", end="")
progress_bar(10)
return role
```
AWS フェデレーションエンドポイントからセキュリティトークンを取得し、フェデレーション認証情報を使用してコンソールにアクセスするために使用できる URL を作成します。
```
def construct_federated_url(assume_role_arn, session_name, issuer, sts_client):
"""
Constructs a URL that gives federated users direct access to the AWS Management
Console.
1. Acquires temporary credentials from AWS Security Token Service (AWS STS) that
can be used to assume a role with limited permissions.
2. Uses the temporary credentials to request a sign-in token from the
AWS federation endpoint.
3. Builds a URL that can be used in a browser to navigate to the AWS federation
endpoint, includes the sign-in token for authentication, and redirects to
the AWS Management Console with permissions defined by the role that was
specified in step 1.
:param assume_role_arn: The role that specifies the permissions that are granted.
The current user must have permission to assume the role.
:param session_name: The name for the STS session.
:param issuer: The organization that issues the URL.
:param sts_client: A Boto3 STS instance that can assume the role.
:return: The federated URL.
"""
response = sts_client.assume_role(
RoleArn=assume_role_arn, RoleSessionName=session_name
)
temp_credentials = response["Credentials"]
print(f"Assumed role {assume_role_arn} and got temporary credentials.")
session_data = {
"sessionId": temp_credentials["AccessKeyId"],
"sessionKey": temp_credentials["SecretAccessKey"],
"sessionToken": temp_credentials["SessionToken"],
}
aws_federated_signin_endpoint = "https://signin.aws.amazon.com/federation"
# Make a request to the AWS federation endpoint to get a sign-in token.
# The requests.get function URL-encodes the parameters and builds the query string
# before making the request.
response = requests.get(
aws_federated_signin_endpoint,
params={
"Action": "getSigninToken",
"SessionDuration": str(datetime.timedelta(hours=12).seconds),
"Session": json.dumps(session_data),
},
)
signin_token = json.loads(response.text)
print(f"Got a sign-in token from the AWS sign-in federation endpoint.")
# Make a federated URL that can be used to sign into the AWS Management Console.
query_string = urllib.parse.urlencode(
{
"Action": "login",
"Issuer": issuer,
"Destination": "https://console.aws.amazon.com/",
"SigninToken": signin_token["SigninToken"],
}
)
federated_url = f"{aws_federated_signin_endpoint}?{query_string}"
return federated_url
```
デモ用に作成されたリソースを破棄します。
```
def teardown(role):
"""
Removes all resources created during setup.
:param role: The demo role.
"""
for attached in role.attached_policies.all():
role.detach_policy(PolicyArn=attached.arn)
print(f"Detached {attached.policy_name}.")
role.delete()
print(f"Deleted {role.name}.")
```
このシナリオは、前に定義した関数を使用して実行します。
```
def usage_demo():
"""Drives the demonstration."""
print("-" * 88)
print(f"Welcome to the AWS Security Token Service federated URL demo.")
print("-" * 88)
iam_resource = boto3.resource("iam")
role = setup(iam_resource)
sts_client = boto3.client("sts")
try:
federated_url = construct_federated_url(
role.arn, "AssumeRoleDemoSession", "example.org", sts_client
)
print(
"Constructed a federated URL that can be used to connect to the "
"AWS Management Console with role-defined permissions:"
)
print("-" * 88)
print(federated_url)
print("-" * 88)
_ = input(
"Copy and paste the above URL into a browser to open the AWS "
"Management Console with limited permissions. When done, press "
"Enter to clean up and complete this demo."
)
finally:
teardown(role)
print("Thanks for watching!")
```
+ API の詳細については、「AWS SDK for Python (Boto3) API リファレンス」の「[AssumeRole](https://docs.aws.amazon.com/goto/boto3/sts-2011-06-15/AssumeRole)」を参照してください。
### MFA トークンを必要とするセッショントークンの取得
次のコード例では、MFA トークンを必要とするセッショントークンを取得する方法を示します。
**警告**
セキュリティリスクを避けるため、専用ソフトウェアの開発や実際のデータを扱うときは、IAM ユーザーを認証に使用しないでください。代わりに、[AWS IAM アイデンティティセンター](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html) などの ID プロバイダーとのフェデレーションを使用してください。
+ Amazon S3 バケットを一覧表示するためのアクセス許可を付与する、IAM ロールを作成します。
+ MFA 認証情報が指定された場合にのみロールを引き受けることが許可された、IAM ユーザーを作成します。
+ ユーザーのための MFA デバイスを登録します。
+ セッショントークンを取得するための MFA 認証情報を指定し、一時的な認証情報により S3 バケットを一覧表示します。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sts#code-examples)での設定と実行の方法を確認してください。
IAM ユーザーの作成と MFA デバイスの登録を行い、ユーザーが Amazon S3 バケットを一覧表示できるようにするアクセス許可を、MFA 認証情報が使用されている場合にのみ付与するロールを作成します。
```
def setup(iam_resource):
"""
Creates a new user with no permissions.
Creates a new virtual multi-factor authentication (MFA) device.
Displays the QR code to seed the device.
Asks for two codes from the MFA device.
Registers the MFA device for the user.
Creates an access key pair for the user.
Creates an inline policy for the user that lets the user list Amazon S3 buckets,
but only when MFA credentials are used.
Any MFA device that can scan a QR code will work with this demonstration.
Common choices are mobile apps like LastPass Authenticator,
Microsoft Authenticator, or Google Authenticator.
:param iam_resource: A Boto3 AWS Identity and Access Management (IAM) resource
that has permissions to create users, MFA devices, and
policies in the account.
:return: The newly created user, user key, and virtual MFA device.
"""
user = iam_resource.create_user(UserName=unique_name("user"))
print(f"Created user {user.name}.")
virtual_mfa_device = iam_resource.create_virtual_mfa_device(
VirtualMFADeviceName=unique_name("mfa")
)
print(f"Created virtual MFA device {virtual_mfa_device.serial_number}")
print(
f"Showing the QR code for the device. Scan this in the MFA app of your "
f"choice."
)
with open("qr.png", "wb") as qr_file:
qr_file.write(virtual_mfa_device.qr_code_png)
webbrowser.open(qr_file.name)
print(f"Enter two consecutive code from your MFA device.")
mfa_code_1 = input("Enter the first code: ")
mfa_code_2 = input("Enter the second code: ")
user.enable_mfa(
SerialNumber=virtual_mfa_device.serial_number,
AuthenticationCode1=mfa_code_1,
AuthenticationCode2=mfa_code_2,
)
os.remove(qr_file.name)
print(f"MFA device is registered with the user.")
user_key = user.create_access_key_pair()
print(f"Created access key pair for user.")
print(f"Wait for user to be ready.", end="")
progress_bar(10)
user.create_policy(
PolicyName=unique_name("user-policy"),
PolicyDocument=json.dumps(
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "s3:ListAllMyBuckets",
"Resource": "arn:aws:s3:::*",
"Condition": {"Bool": {"aws:MultiFactorAuthPresent": True}},
}
],
}
),
)
print(
f"Created an inline policy for {user.name} that lets the user list buckets, "
f"but only when MFA credentials are present."
)
print("Give AWS time to propagate these new resources and connections.", end="")
progress_bar(10)
return user, user_key, virtual_mfa_device
```
MFA トークンを渡して一時的なセッション認証情報を取得し、その認証情報を使用してアカウントの S3 バケットを一覧表示します。
```
def list_buckets_with_session_token_with_mfa(mfa_serial_number, mfa_totp, sts_client):
"""
Gets a session token with MFA credentials and uses the temporary session
credentials to list Amazon S3 buckets.
Requires an MFA device serial number and token.
:param mfa_serial_number: The serial number of the MFA device. For a virtual MFA
device, this is an Amazon Resource Name (ARN).
:param mfa_totp: A time-based, one-time password issued by the MFA device.
:param sts_client: A Boto3 STS instance that has permission to assume the role.
"""
if mfa_serial_number is not None:
response = sts_client.get_session_token(
SerialNumber=mfa_serial_number, TokenCode=mfa_totp
)
else:
response = sts_client.get_session_token()
temp_credentials = response["Credentials"]
s3_resource = boto3.resource(
"s3",
aws_access_key_id=temp_credentials["AccessKeyId"],
aws_secret_access_key=temp_credentials["SecretAccessKey"],
aws_session_token=temp_credentials["SessionToken"],
)
print(f"Buckets for the account:")
for bucket in s3_resource.buckets.all():
print(bucket.name)
```
デモ用に作成されたリソースを破棄します。
```
def teardown(user, virtual_mfa_device):
"""
Removes all resources created during setup.
:param user: The demo user.
:param role: The demo MFA device.
"""
for user_pol in user.policies.all():
user_pol.delete()
print("Deleted inline user policy.")
for key in user.access_keys.all():
key.delete()
print("Deleted user's access key.")
for mfa in user.mfa_devices.all():
mfa.disassociate()
virtual_mfa_device.delete()
user.delete()
print(f"Deleted {user.name}.")
```
このシナリオは、前に定義した関数を使用して実行します。
```
def usage_demo():
"""Drives the demonstration."""
print("-" * 88)
print(
f"Welcome to the AWS Security Token Service assume role demo, "
f"starring multi-factor authentication (MFA)!"
)
print("-" * 88)
iam_resource = boto3.resource("iam")
user, user_key, virtual_mfa_device = setup(iam_resource)
try:
sts_client = boto3.client(
"sts", aws_access_key_id=user_key.id, aws_secret_access_key=user_key.secret
)
try:
print("Listing buckets without specifying MFA credentials.")
list_buckets_with_session_token_with_mfa(None, None, sts_client)
except ClientError as error:
if error.response["Error"]["Code"] == "AccessDenied":
print("Got expected AccessDenied error.")
mfa_totp = input("Enter the code from your registered MFA device: ")
list_buckets_with_session_token_with_mfa(
virtual_mfa_device.serial_number, mfa_totp, sts_client
)
finally:
teardown(user, virtual_mfa_device)
print("Thanks for watching!")
```
+ API の詳細については、「AWS SDK for Python (Boto3) API リファレンス」の「[GetSessionToken](https://docs.aws.amazon.com/goto/boto3/sts-2011-06-15/GetSessionToken)」を参照してください。
# サポート SDK for Python (Boto3) を使用した例
次のコード例は、 AWS SDK for Python (Boto3) で を使用してアクションを実行し、一般的なシナリオを実装する方法を示しています サポート。
*基本* は、重要なオペレーションをサービス内で実行する方法を示すコード例です。
*アクション*はより大きなプログラムからのコードの抜粋であり、コンテキスト内で実行する必要があります。アクションは個々のサービス機能を呼び出す方法を示していますが、コンテキスト内のアクションは、関連するシナリオで確認できます。
各例には完全なソースコードへのリンクが含まれており、コンテキスト内でコードを設定および実行する方法の手順を確認できます。
**Topics**
+ [はじめに](#get_started)
+ [基本](#basics)
+ [アクション](#actions)
## はじめに
### こんにち サポートは
次のコード例は、 サポートの使用を開始する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/support#code-examples)での設定と実行の方法を確認してください。
```
import logging
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
def hello_support(support_client):
"""
Use the AWS SDK for Python (Boto3) to create an AWS Support client and count
the available services in your account.
This example uses the default settings specified in your shared credentials
and config files.
:param support_client: A Boto3 Support Client object.
"""
try:
print("Hello, AWS Support! Let's count the available Support services:")
response = support_client.describe_services()
print(f"There are {len(response['services'])} services available.")
except ClientError as err:
if err.response["Error"]["Code"] == "SubscriptionRequiredException":
logger.info(
"You must have a Business, Enterprise On-Ramp, or Enterprise Support "
"plan to use the AWS Support API. \n\tPlease upgrade your subscription to run these "
"examples."
)
else:
logger.error(
"Couldn't count services. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
if __name__ == "__main__":
hello_support(boto3.client("support"))
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[DescribeServices](https://docs.aws.amazon.com/goto/boto3/support-2013-04-15/DescribeServices)」を参照してください。
## 基本
### 基本を学ぶ
次のコード例は、以下の操作方法を示しています。
+ ケースの利用可能なサービスと重要度レベルを取得して表示します。
+ 選択したサービス、カテゴリ、重要度レベルを使用してサポートケースを作成する方法
+ 当日のオープンケースのリストを取得して表示する方法
+ 新しいケースに添付セットとコミュニケーションを追加する方法
+ ケースの新しい添付ファイルとコミュニケーションについて説明する方法
+ ケースを解決する方法
+ 当日の解決済みケースのリストを取得して表示します。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/support#code-examples)での設定と実行の方法を確認してください。
コマンドプロンプトからインタラクティブなシナリオを実行します。
```
class SupportCasesScenario:
"""Runs an interactive scenario that shows how to get started using AWS Support."""
def __init__(self, support_wrapper):
"""
:param support_wrapper: An object that wraps AWS Support actions.
"""
self.support_wrapper = support_wrapper
def display_and_select_service(self):
"""
Lists support services and prompts the user to select one.
:return: The support service selected by the user.
"""
print("-" * 88)
services_list = self.support_wrapper.describe_services("en")
print(f"AWS Support client returned {len(services_list)} services.")
print("Displaying first 10 services:")
service_choices = [svc["name"] for svc in services_list[:10]]
selected_index = q.choose(
"Select an example support service by entering a number from the preceding list:",
service_choices,
)
selected_service = services_list[selected_index]
print("-" * 88)
return selected_service
def display_and_select_category(self, service):
"""
Lists categories for a support service and prompts the user to select one.
:param service: The service of the categories.
:return: The selected category.
"""
print("-" * 88)
print(
f"Available support categories for Service {service['name']} {len(service['categories'])}:"
)
categories_choices = [category["name"] for category in service["categories"]]
selected_index = q.choose(
"Select an example support category by entering a number from the preceding list:",
categories_choices,
)
selected_category = service["categories"][selected_index]
print("-" * 88)
return selected_category
def display_and_select_severity(self):
"""
Lists available severity levels and prompts the user to select one.
:return: The selected severity level.
"""
print("-" * 88)
severity_levels_list = self.support_wrapper.describe_severity_levels("en")
print(f"Available severity levels:")
severity_choices = [level["name"] for level in severity_levels_list]
selected_index = q.choose(
"Select an example severity level by entering a number from the preceding list:",
severity_choices,
)
selected_severity = severity_levels_list[selected_index]
print("-" * 88)
return selected_severity
def create_example_case(self, service, category, severity_level):
"""
Creates an example support case with the user's selections.
:param service: The service for the new case.
:param category: The category for the new case.
:param severity_level: The severity level for the new case.
:return: The caseId of the new support case.
"""
print("-" * 88)
print(f"Creating new case for service {service['name']}.")
case_id = self.support_wrapper.create_case(service, category, severity_level)
print(f"\tNew case created with ID {case_id}.")
print("-" * 88)
return case_id
def list_open_cases(self):
"""
List the open cases for the current day.
"""
print("-" * 88)
print("Let's list the open cases for the current day.")
start_time = str(datetime.utcnow().date())
end_time = str(datetime.utcnow().date() + timedelta(days=1))
open_cases = self.support_wrapper.describe_cases(start_time, end_time, False)
for case in open_cases:
print(f"\tCase: {case['caseId']}: status {case['status']}.")
print("-" * 88)
def create_attachment_set(self):
"""
Create an attachment set with a sample file.
:return: The attachment set ID of the new attachment set.
"""
print("-" * 88)
print("Creating attachment set with a sample file.")
attachment_set_id = self.support_wrapper.add_attachment_to_set()
print(f"\tNew attachment set created with ID {attachment_set_id}.")
print("-" * 88)
return attachment_set_id
def add_communication(self, case_id, attachment_set_id):
"""
Add a communication with an attachment set to the case.
:param case_id: The ID of the case for the communication.
:param attachment_set_id: The ID of the attachment set to
add to the communication.
"""
print("-" * 88)
print(f"Adding a communication and attachment set to the case.")
self.support_wrapper.add_communication_to_case(attachment_set_id, case_id)
print(
f"Added a communication and attachment set {attachment_set_id} to the case {case_id}."
)
print("-" * 88)
def list_communications(self, case_id):
"""
List the communications associated with a case.
:param case_id: The ID of the case.
:return: The attachment ID of an attachment.
"""
print("-" * 88)
print("Let's list the communications for our case.")
attachment_id = ""
communications = self.support_wrapper.describe_all_case_communications(case_id)
for communication in communications:
print(
f"\tCommunication created on {communication['timeCreated']} "
f"has {len(communication['attachmentSet'])} attachments."
)
if len(communication["attachmentSet"]) > 0:
attachment_id = communication["attachmentSet"][0]["attachmentId"]
print("-" * 88)
return attachment_id
def describe_case_attachment(self, attachment_id):
"""
Describe an attachment associated with a case.
:param attachment_id: The ID of the attachment.
"""
print("-" * 88)
print("Let's list the communications for our case.")
attached_file = self.support_wrapper.describe_attachment(attachment_id)
print(f"\tAttachment includes file {attached_file}.")
print("-" * 88)
def resolve_case(self, case_id):
"""
Shows how to resolve an AWS Support case by its ID.
:param case_id: The ID of the case to resolve.
"""
print("-" * 88)
print(f"Resolving case with ID {case_id}.")
case_status = self.support_wrapper.resolve_case(case_id)
print(f"\tFinal case status is {case_status}.")
print("-" * 88)
def list_resolved_cases(self):
"""
List the resolved cases for the current day.
"""
print("-" * 88)
print("Let's list the resolved cases for the current day.")
start_time = str(datetime.utcnow().date())
end_time = str(datetime.utcnow().date() + timedelta(days=1))
resolved_cases = self.support_wrapper.describe_cases(start_time, end_time, True)
for case in resolved_cases:
print(f"\tCase: {case['caseId']}: status {case['status']}.")
print("-" * 88)
def run_scenario(self):
logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
print("-" * 88)
print("Welcome to the AWS Support get started with support cases demo.")
print("-" * 88)
selected_service = self.display_and_select_service()
selected_category = self.display_and_select_category(selected_service)
selected_severity = self.display_and_select_severity()
new_case_id = self.create_example_case(
selected_service, selected_category, selected_severity
)
wait(10)
self.list_open_cases()
new_attachment_set_id = self.create_attachment_set()
self.add_communication(new_case_id, new_attachment_set_id)
new_attachment_id = self.list_communications(new_case_id)
self.describe_case_attachment(new_attachment_id)
self.resolve_case(new_case_id)
wait(10)
self.list_resolved_cases()
print("\nThanks for watching!")
print("-" * 88)
if __name__ == "__main__":
try:
scenario = SupportCasesScenario(SupportWrapper.from_client())
scenario.run_scenario()
except Exception:
logging.exception("Something went wrong with the demo.")
```
サポートされるクライアントアクションをラップするクラスを定義します。
```
class SupportWrapper:
"""Encapsulates Support actions."""
def __init__(self, support_client):
"""
:param support_client: A Boto3 Support client.
"""
self.support_client = support_client
@classmethod
def from_client(cls):
"""
Instantiates this class from a Boto3 client.
"""
support_client = boto3.client("support")
return cls(support_client)
def describe_services(self, language):
"""
Get the descriptions of AWS services available for support for a language.
:param language: The language for support services.
Currently, only "en" (English) and "ja" (Japanese) are supported.
:return: The list of AWS service descriptions.
"""
try:
response = self.support_client.describe_services(language=language)
services = response["services"]
except ClientError as err:
if err.response["Error"]["Code"] == "SubscriptionRequiredException":
logger.info(
"You must have a Business, Enterprise On-Ramp, or Enterprise Support "
"plan to use the AWS Support API. \n\tPlease upgrade your subscription to run these "
"examples."
)
else:
logger.error(
"Couldn't get Support services for language %s. Here's why: %s: %s",
language,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return services
def describe_severity_levels(self, language):
"""
Get the descriptions of available severity levels for support cases for a language.
:param language: The language for support severity levels.
Currently, only "en" (English) and "ja" (Japanese) are supported.
:return: The list of severity levels.
"""
try:
response = self.support_client.describe_severity_levels(language=language)
severity_levels = response["severityLevels"]
except ClientError as err:
if err.response["Error"]["Code"] == "SubscriptionRequiredException":
logger.info(
"You must have a Business, Enterprise On-Ramp, or Enterprise Support "
"plan to use the AWS Support API. \n\tPlease upgrade your subscription to run these "
"examples."
)
else:
logger.error(
"Couldn't get severity levels for language %s. Here's why: %s: %s",
language,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return severity_levels
def create_case(self, service, category, severity):
"""
Create a new support case.
:param service: The service to use for the new case.
:param category: The category to use for the new case.
:param severity: The severity to use for the new case.
:return: The caseId of the new case.
"""
try:
response = self.support_client.create_case(
subject="Example case for testing, ignore.",
serviceCode=service["code"],
severityCode=severity["code"],
categoryCode=category["code"],
communicationBody="Example support case body.",
language="en",
issueType="customer-service",
)
case_id = response["caseId"]
except ClientError as err:
if err.response["Error"]["Code"] == "SubscriptionRequiredException":
logger.info(
"You must have a Business, Enterprise On-Ramp, or Enterprise Support "
"plan to use the AWS Support API. \n\tPlease upgrade your subscription to run these "
"examples."
)
else:
logger.error(
"Couldn't create case. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return case_id
def add_attachment_to_set(self):
"""
Add an attachment to a set, or create a new attachment set if one does not exist.
:return: The attachment set ID.
"""
try:
response = self.support_client.add_attachments_to_set(
attachments=[
{
"fileName": "attachment_file.txt",
"data": b"This is a sample file for attachment to a support case.",
}
]
)
new_set_id = response["attachmentSetId"]
except ClientError as err:
if err.response["Error"]["Code"] == "SubscriptionRequiredException":
logger.info(
"You must have a Business, Enterprise On-Ramp, or Enterprise Support "
"plan to use the AWS Support API. \n\tPlease upgrade your subscription to run these "
"examples."
)
else:
logger.error(
"Couldn't add attachment. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return new_set_id
def add_communication_to_case(self, attachment_set_id, case_id):
"""
Add a communication and an attachment set to a case.
:param attachment_set_id: The ID of an existing attachment set.
:param case_id: The ID of the case.
"""
try:
self.support_client.add_communication_to_case(
caseId=case_id,
communicationBody="This is an example communication added to a support case.",
attachmentSetId=attachment_set_id,
)
except ClientError as err:
if err.response["Error"]["Code"] == "SubscriptionRequiredException":
logger.info(
"You must have a Business, Enterprise On-Ramp, or Enterprise Support "
"plan to use the AWS Support API. \n\tPlease upgrade your subscription to run these "
"examples."
)
else:
logger.error(
"Couldn't add communication. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
def describe_all_case_communications(self, case_id):
"""
Describe all the communications for a case using a paginator.
:param case_id: The ID of the case.
:return: The communications for the case.
"""
try:
communications = []
paginator = self.support_client.get_paginator("describe_communications")
for page in paginator.paginate(caseId=case_id):
communications += page["communications"]
except ClientError as err:
if err.response["Error"]["Code"] == "SubscriptionRequiredException":
logger.info(
"You must have a Business, Enterprise On-Ramp, or Enterprise Support "
"plan to use the AWS Support API. \n\tPlease upgrade your subscription to run these "
"examples."
)
else:
logger.error(
"Couldn't describe communications. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return communications
def describe_attachment(self, attachment_id):
"""
Get information about an attachment by its attachmentID.
:param attachment_id: The ID of the attachment.
:return: The name of the attached file.
"""
try:
response = self.support_client.describe_attachment(
attachmentId=attachment_id
)
attached_file = response["attachment"]["fileName"]
except ClientError as err:
if err.response["Error"]["Code"] == "SubscriptionRequiredException":
logger.info(
"You must have a Business, Enterprise On-Ramp, or Enterprise Support "
"plan to use the AWS Support API. \n\tPlease upgrade your subscription to run these "
"examples."
)
else:
logger.error(
"Couldn't get attachment description. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return attached_file
def resolve_case(self, case_id):
"""
Resolve a support case by its caseId.
:param case_id: The ID of the case to resolve.
:return: The final status of the case.
"""
try:
response = self.support_client.resolve_case(caseId=case_id)
final_status = response["finalCaseStatus"]
except ClientError as err:
if err.response["Error"]["Code"] == "SubscriptionRequiredException":
logger.info(
"You must have a Business, Enterprise On-Ramp, or Enterprise Support "
"plan to use the AWS Support API. \n\tPlease upgrade your subscription to run these "
"examples."
)
else:
logger.error(
"Couldn't resolve case. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return final_status
def describe_cases(self, after_time, before_time, resolved):
"""
Describe support cases over a period of time, optionally filtering
by status.
:param after_time: The start time to include for cases.
:param before_time: The end time to include for cases.
:param resolved: True to include resolved cases in the results,
otherwise results are open cases.
:return: The final status of the case.
"""
try:
cases = []
paginator = self.support_client.get_paginator("describe_cases")
for page in paginator.paginate(
afterTime=after_time,
beforeTime=before_time,
includeResolvedCases=resolved,
language="en",
):
cases += page["cases"]
except ClientError as err:
if err.response["Error"]["Code"] == "SubscriptionRequiredException":
logger.info(
"You must have a Business, Enterprise On-Ramp, or Enterprise Support "
"plan to use the AWS Support API. \n\tPlease upgrade your subscription to run these "
"examples."
)
else:
logger.error(
"Couldn't describe cases. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
if resolved:
cases = filter(lambda case: case["status"] == "resolved", cases)
return cases
```
+ API の詳細については、「**AWS SDK for Python (Boto3) API リファレンス」の以下のトピックを参照してください。
+ [AddAttachmentsToSet](https://docs.aws.amazon.com/goto/boto3/support-2013-04-15/AddAttachmentsToSet)
+ [AddCommunicationToCase](https://docs.aws.amazon.com/goto/boto3/support-2013-04-15/AddCommunicationToCase)
+ [CreateCase](https://docs.aws.amazon.com/goto/boto3/support-2013-04-15/CreateCase)
+ [DescribeAttachment](https://docs.aws.amazon.com/goto/boto3/support-2013-04-15/DescribeAttachment)
+ [DescribeCases](https://docs.aws.amazon.com/goto/boto3/support-2013-04-15/DescribeCases)
+ [DescribeCommunications](https://docs.aws.amazon.com/goto/boto3/support-2013-04-15/DescribeCommunications)
+ [DescribeServices](https://docs.aws.amazon.com/goto/boto3/support-2013-04-15/DescribeServices)
+ [DescribeSeverityLevels](https://docs.aws.amazon.com/goto/boto3/support-2013-04-15/DescribeSeverityLevels)
+ [ResolveCase](https://docs.aws.amazon.com/goto/boto3/support-2013-04-15/ResolveCase)
## アクション
### `AddAttachmentsToSet`
次のコード例は、`AddAttachmentsToSet` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/support#code-examples)での設定と実行の方法を確認してください。
```
class SupportWrapper:
"""Encapsulates Support actions."""
def __init__(self, support_client):
"""
:param support_client: A Boto3 Support client.
"""
self.support_client = support_client
@classmethod
def from_client(cls):
"""
Instantiates this class from a Boto3 client.
"""
support_client = boto3.client("support")
return cls(support_client)
def add_attachment_to_set(self):
"""
Add an attachment to a set, or create a new attachment set if one does not exist.
:return: The attachment set ID.
"""
try:
response = self.support_client.add_attachments_to_set(
attachments=[
{
"fileName": "attachment_file.txt",
"data": b"This is a sample file for attachment to a support case.",
}
]
)
new_set_id = response["attachmentSetId"]
except ClientError as err:
if err.response["Error"]["Code"] == "SubscriptionRequiredException":
logger.info(
"You must have a Business, Enterprise On-Ramp, or Enterprise Support "
"plan to use the AWS Support API. \n\tPlease upgrade your subscription to run these "
"examples."
)
else:
logger.error(
"Couldn't add attachment. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return new_set_id
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[AddAttachmentsToSet](https://docs.aws.amazon.com/goto/boto3/support-2013-04-15/AddAttachmentsToSet)」を参照してください。
### `AddCommunicationToCase`
次のコード例は、`AddCommunicationToCase` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/support#code-examples)での設定と実行の方法を確認してください。
```
class SupportWrapper:
"""Encapsulates Support actions."""
def __init__(self, support_client):
"""
:param support_client: A Boto3 Support client.
"""
self.support_client = support_client
@classmethod
def from_client(cls):
"""
Instantiates this class from a Boto3 client.
"""
support_client = boto3.client("support")
return cls(support_client)
def add_communication_to_case(self, attachment_set_id, case_id):
"""
Add a communication and an attachment set to a case.
:param attachment_set_id: The ID of an existing attachment set.
:param case_id: The ID of the case.
"""
try:
self.support_client.add_communication_to_case(
caseId=case_id,
communicationBody="This is an example communication added to a support case.",
attachmentSetId=attachment_set_id,
)
except ClientError as err:
if err.response["Error"]["Code"] == "SubscriptionRequiredException":
logger.info(
"You must have a Business, Enterprise On-Ramp, or Enterprise Support "
"plan to use the AWS Support API. \n\tPlease upgrade your subscription to run these "
"examples."
)
else:
logger.error(
"Couldn't add communication. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[AddCommunicationToCase](https://docs.aws.amazon.com/goto/boto3/support-2013-04-15/AddCommunicationToCase)」を参照してください。
### `CreateCase`
次のコード例は、`CreateCase` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/support#code-examples)での設定と実行の方法を確認してください。
```
class SupportWrapper:
"""Encapsulates Support actions."""
def __init__(self, support_client):
"""
:param support_client: A Boto3 Support client.
"""
self.support_client = support_client
@classmethod
def from_client(cls):
"""
Instantiates this class from a Boto3 client.
"""
support_client = boto3.client("support")
return cls(support_client)
def create_case(self, service, category, severity):
"""
Create a new support case.
:param service: The service to use for the new case.
:param category: The category to use for the new case.
:param severity: The severity to use for the new case.
:return: The caseId of the new case.
"""
try:
response = self.support_client.create_case(
subject="Example case for testing, ignore.",
serviceCode=service["code"],
severityCode=severity["code"],
categoryCode=category["code"],
communicationBody="Example support case body.",
language="en",
issueType="customer-service",
)
case_id = response["caseId"]
except ClientError as err:
if err.response["Error"]["Code"] == "SubscriptionRequiredException":
logger.info(
"You must have a Business, Enterprise On-Ramp, or Enterprise Support "
"plan to use the AWS Support API. \n\tPlease upgrade your subscription to run these "
"examples."
)
else:
logger.error(
"Couldn't create case. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return case_id
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[CreateCase](https://docs.aws.amazon.com/goto/boto3/support-2013-04-15/CreateCase)」を参照してください。
### `DescribeAttachment`
次のコード例は、`DescribeAttachment` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/support#code-examples)での設定と実行の方法を確認してください。
```
class SupportWrapper:
"""Encapsulates Support actions."""
def __init__(self, support_client):
"""
:param support_client: A Boto3 Support client.
"""
self.support_client = support_client
@classmethod
def from_client(cls):
"""
Instantiates this class from a Boto3 client.
"""
support_client = boto3.client("support")
return cls(support_client)
def describe_attachment(self, attachment_id):
"""
Get information about an attachment by its attachmentID.
:param attachment_id: The ID of the attachment.
:return: The name of the attached file.
"""
try:
response = self.support_client.describe_attachment(
attachmentId=attachment_id
)
attached_file = response["attachment"]["fileName"]
except ClientError as err:
if err.response["Error"]["Code"] == "SubscriptionRequiredException":
logger.info(
"You must have a Business, Enterprise On-Ramp, or Enterprise Support "
"plan to use the AWS Support API. \n\tPlease upgrade your subscription to run these "
"examples."
)
else:
logger.error(
"Couldn't get attachment description. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return attached_file
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[DescribeAttachment](https://docs.aws.amazon.com/goto/boto3/support-2013-04-15/DescribeAttachment)」を参照してください。
### `DescribeCases`
次のコード例は、`DescribeCases` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/support#code-examples)での設定と実行の方法を確認してください。
```
class SupportWrapper:
"""Encapsulates Support actions."""
def __init__(self, support_client):
"""
:param support_client: A Boto3 Support client.
"""
self.support_client = support_client
@classmethod
def from_client(cls):
"""
Instantiates this class from a Boto3 client.
"""
support_client = boto3.client("support")
return cls(support_client)
def describe_cases(self, after_time, before_time, resolved):
"""
Describe support cases over a period of time, optionally filtering
by status.
:param after_time: The start time to include for cases.
:param before_time: The end time to include for cases.
:param resolved: True to include resolved cases in the results,
otherwise results are open cases.
:return: The final status of the case.
"""
try:
cases = []
paginator = self.support_client.get_paginator("describe_cases")
for page in paginator.paginate(
afterTime=after_time,
beforeTime=before_time,
includeResolvedCases=resolved,
language="en",
):
cases += page["cases"]
except ClientError as err:
if err.response["Error"]["Code"] == "SubscriptionRequiredException":
logger.info(
"You must have a Business, Enterprise On-Ramp, or Enterprise Support "
"plan to use the AWS Support API. \n\tPlease upgrade your subscription to run these "
"examples."
)
else:
logger.error(
"Couldn't describe cases. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
if resolved:
cases = filter(lambda case: case["status"] == "resolved", cases)
return cases
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[DescribeCases](https://docs.aws.amazon.com/goto/boto3/support-2013-04-15/DescribeCases)」を参照してください。
### `DescribeCommunications`
次のコード例は、`DescribeCommunications` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/support#code-examples)での設定と実行の方法を確認してください。
```
class SupportWrapper:
"""Encapsulates Support actions."""
def __init__(self, support_client):
"""
:param support_client: A Boto3 Support client.
"""
self.support_client = support_client
@classmethod
def from_client(cls):
"""
Instantiates this class from a Boto3 client.
"""
support_client = boto3.client("support")
return cls(support_client)
def describe_all_case_communications(self, case_id):
"""
Describe all the communications for a case using a paginator.
:param case_id: The ID of the case.
:return: The communications for the case.
"""
try:
communications = []
paginator = self.support_client.get_paginator("describe_communications")
for page in paginator.paginate(caseId=case_id):
communications += page["communications"]
except ClientError as err:
if err.response["Error"]["Code"] == "SubscriptionRequiredException":
logger.info(
"You must have a Business, Enterprise On-Ramp, or Enterprise Support "
"plan to use the AWS Support API. \n\tPlease upgrade your subscription to run these "
"examples."
)
else:
logger.error(
"Couldn't describe communications. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return communications
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[DescribeCommunications](https://docs.aws.amazon.com/goto/boto3/support-2013-04-15/DescribeCommunications)」を参照してください。
### `DescribeServices`
次のコード例は、`DescribeServices` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/support#code-examples)での設定と実行の方法を確認してください。
```
class SupportWrapper:
"""Encapsulates Support actions."""
def __init__(self, support_client):
"""
:param support_client: A Boto3 Support client.
"""
self.support_client = support_client
@classmethod
def from_client(cls):
"""
Instantiates this class from a Boto3 client.
"""
support_client = boto3.client("support")
return cls(support_client)
def describe_services(self, language):
"""
Get the descriptions of AWS services available for support for a language.
:param language: The language for support services.
Currently, only "en" (English) and "ja" (Japanese) are supported.
:return: The list of AWS service descriptions.
"""
try:
response = self.support_client.describe_services(language=language)
services = response["services"]
except ClientError as err:
if err.response["Error"]["Code"] == "SubscriptionRequiredException":
logger.info(
"You must have a Business, Enterprise On-Ramp, or Enterprise Support "
"plan to use the AWS Support API. \n\tPlease upgrade your subscription to run these "
"examples."
)
else:
logger.error(
"Couldn't get Support services for language %s. Here's why: %s: %s",
language,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return services
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[DescribeServices](https://docs.aws.amazon.com/goto/boto3/support-2013-04-15/DescribeServices)」を参照してください。
### `DescribeSeverityLevels`
次のコード例は、`DescribeSeverityLevels` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/support#code-examples)での設定と実行の方法を確認してください。
```
class SupportWrapper:
"""Encapsulates Support actions."""
def __init__(self, support_client):
"""
:param support_client: A Boto3 Support client.
"""
self.support_client = support_client
@classmethod
def from_client(cls):
"""
Instantiates this class from a Boto3 client.
"""
support_client = boto3.client("support")
return cls(support_client)
def describe_severity_levels(self, language):
"""
Get the descriptions of available severity levels for support cases for a language.
:param language: The language for support severity levels.
Currently, only "en" (English) and "ja" (Japanese) are supported.
:return: The list of severity levels.
"""
try:
response = self.support_client.describe_severity_levels(language=language)
severity_levels = response["severityLevels"]
except ClientError as err:
if err.response["Error"]["Code"] == "SubscriptionRequiredException":
logger.info(
"You must have a Business, Enterprise On-Ramp, or Enterprise Support "
"plan to use the AWS Support API. \n\tPlease upgrade your subscription to run these "
"examples."
)
else:
logger.error(
"Couldn't get severity levels for language %s. Here's why: %s: %s",
language,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return severity_levels
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[DescribeSeverityLevels](https://docs.aws.amazon.com/goto/boto3/support-2013-04-15/DescribeSeverityLevels)」を参照してください。
### `ResolveCase`
次のコード例は、`ResolveCase` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/support#code-examples)での設定と実行の方法を確認してください。
```
class SupportWrapper:
"""Encapsulates Support actions."""
def __init__(self, support_client):
"""
:param support_client: A Boto3 Support client.
"""
self.support_client = support_client
@classmethod
def from_client(cls):
"""
Instantiates this class from a Boto3 client.
"""
support_client = boto3.client("support")
return cls(support_client)
def resolve_case(self, case_id):
"""
Resolve a support case by its caseId.
:param case_id: The ID of the case to resolve.
:return: The final status of the case.
"""
try:
response = self.support_client.resolve_case(caseId=case_id)
final_status = response["finalCaseStatus"]
except ClientError as err:
if err.response["Error"]["Code"] == "SubscriptionRequiredException":
logger.info(
"You must have a Business, Enterprise On-Ramp, or Enterprise Support "
"plan to use the AWS Support API. \n\tPlease upgrade your subscription to run these "
"examples."
)
else:
logger.error(
"Couldn't resolve case. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return final_status
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[resolve\$1case](https://docs.aws.amazon.com/goto/boto3/support-2013-04-15/ResolveCase)」を参照してください。
# SDK for Python (Boto3) を使用した Systems Manager の例
次のコード例は、Systems Manager AWS SDK for Python (Boto3) で を使用してアクションを実行し、一般的なシナリオを実装する方法を示しています。
*基本* は、重要なオペレーションをサービス内で実行する方法を示すコード例です。
*アクション*はより大きなプログラムからのコードの抜粋であり、コンテキスト内で実行する必要があります。アクションは個々のサービス機能を呼び出す方法を示していますが、コンテキスト内のアクションは、関連するシナリオで確認できます。
各例には完全なソースコードへのリンクが含まれており、コンテキスト内でコードを設定および実行する方法の手順を確認できます。
**Topics**
+ [はじめに](#get_started)
+ [基本](#basics)
+ [アクション](#actions)
## はじめに
### こんにちは、Systems Manager
次のコード例は、Systems Manager の使用を開始する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ssm#code-examples)での設定と実行の方法を確認してください。
```
import boto3
from botocore.exceptions import ClientError
def hello_systems_manager(ssm_client):
"""
Use the AWS SDK for Python (Boto3) to create an AWS Systems Manager
client and list the first 5 documents in your account.
This example uses the default settings specified in your shared credentials
and config files.
:param ssm_client: A Boto3 AWS Systems Manager Client object. This object wraps
the low-level AWS Systems Manager service API.
"""
print("Hello, AWS Systems Manager! Let's list some of your documents:\n")
paginator = ssm_client.get_paginator("list_documents")
page_iterator = paginator.paginate(PaginationConfig={"MaxItems": 5})
for page in page_iterator:
for document in page["DocumentIdentifiers"]:
print(f" {document['Name']}")
if __name__ == "__main__":
try:
hello_systems_manager(boto3.client("ssm"))
except ClientError as err:
print("Hello systems manager had an error.")
print(err.response["Error"]["Code"])
print(err.response["Error"]["Message"])
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[ListDocuments](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/ListDocuments)」を参照してください。
## 基本
### 基本を学ぶ
次のコード例は、以下の操作方法を示しています。
+ メンテナンスウィンドウを作成します。
+ メンテナンスウィンドウのスケジュールを変更します。
+ ドキュメントを作成します。
+ 指定された EC2 インスタンスにコマンドを送信します。
+ 新しい OpsItem を作成します。
+ OpsItem を更新して解決します。
+ メンテナンスウィンドウ、OpsItem、ドキュメントを削除します。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ssm#code-examples)での設定と実行の方法を確認してください。
コマンドプロンプトからインタラクティブなシナリオを実行します。
```
class SystemsManagerScenario:
"""Runs an interactive scenario that shows how to get started using Amazon Systems Manager."""
def __init__(self, document_wrapper, maintenance_window_wrapper, ops_item_wrapper):
"""
:param document_wrapper: An object that wraps Systems Manager document functions.
:param maintenance_window_wrapper: An object that wraps Systems Manager maintenance window functions.
:param ops_item_wrapper: An object that wraps Systems Manager OpsItem functions.
"""
self.document_wrapper = document_wrapper
self.maintenance_window_wrapper = maintenance_window_wrapper
self.ops_item_wrapper = ops_item_wrapper
def run(self):
"""Demonstrates how to use the AWS SDK for Python (Boto3) to get started with Systems Manager."""
try:
print("-" * 88)
print(
"""
Welcome to the AWS Systems Manager SDK Getting Started scenario.
This program demonstrates how to interact with Systems Manager using the AWS SDK for Python (Boto3).
Systems Manager is the operations hub for your AWS applications and resources and a secure end-to-end management
solution. The program's primary functions include creating a maintenance window, creating a document, sending a
command to a document, listing documents, listing commands, creating an OpsItem, modifying an OpsItem, and deleting
Systems Manager resources. Upon completion of the program, all AWS resources are cleaned up.
Let's get started..."""
)
q.ask("Please hit Enter")
print("-" * 88)
print("Create a Systems Manager maintenance window.")
maintenance_window_name = q.ask(
"Please enter the maintenance window name (default is ssm-maintenance-window):",
)
if not maintenance_window_name:
maintenance_window_name = "ssm-maintenance-window"
self.maintenance_window_wrapper.create(
name=maintenance_window_name,
schedule="cron(0 10 ? * MON-FRI *)",
duration=2,
cutoff=1,
allow_unassociated_targets=True,
)
print("-" * 88)
print("Modify the maintenance window by changing the schedule")
q.ask("Please hit Enter")
self.maintenance_window_wrapper.update(
name=maintenance_window_name,
schedule="cron(0 0 ? * MON *)",
duration=24,
cutoff=1,
allow_unassociated_targets=True,
enabled=True,
)
print("-" * 88)
print(
"Create a document that defines the actions that Systems Manager performs on your EC2 instance."
)
document_name = q.ask(
"Please enter the document name (default is ssmdocument):"
)
if not document_name:
document_name = "ssmdocument"
self.document_wrapper.create(
name=document_name,
content="""
{
"schemaVersion": "2.2",
"description": "Run a simple shell command",
"mainSteps": [
{
"action": "aws:runShellScript",
"name": "runEchoCommand",
"inputs": {
"runCommand": [
"echo 'Hello, world!'"
]
}
}
]
}
""",
)
self.document_wrapper.wait_until_active()
print(
"""
Now you have the option of running a command on an EC2 instance that echoes 'Hello, world!'.
In order to run this command, you must provide the instance ID of a Linux EC2 instance. If you do
not already have a running Linux EC2 instance in your account, you can create one using the AWS console.
For information about creating an EC2 instance, see
https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-launch-instance-wizard.html.
"""
)
if q.ask(
"Would you like to run a command on an EC2 instance? (y/n)",
q.is_yesno,
):
instance_id = q.ask(
"Please enter the instance ID of the EC2 instance:", q.non_empty
)
command_id = self.document_wrapper.send_command(
instance_ids=[instance_id]
)
self.document_wrapper.wait_command_executed(
command_id=command_id, instance_id=instance_id
)
print("-" * 88)
print(
"Lets get the time when the specific command was sent to the specific managed node"
)
q.ask("Please hit Enter")
self.document_wrapper.list_command_invocations(instance_id=instance_id)
print("-" * 88)
print("-" * 88)
print(
"""
Now we will create a Systems Manager OpsItem.
An OpsItem is a feature provided by the Systems Manager service.
It is a type of operational data item that allows you to manage and track various operational issues,
events, or tasks within your AWS environment.
You can create OpsItems to track and manage operational issues as they arise.
For example, you could create an OpsItem whenever your application detects a critical error
or an anomaly in your infrastructure.
"""
)
q.ask("Please hit Enter")
self.ops_item_wrapper.create(
title="Disk Space Alert",
description="Created by the Systems Manager Python (Boto3) API",
source="EC2",
category="Performance",
severity="2",
)
print("-" * 88)
print("-" * 88)
print(f"Now we will update the OpsItem {self.ops_item_wrapper.id}")
q.ask("Please hit Enter")
self.ops_item_wrapper.update(
title="Disk Space Alert",
description=f"An update to {self.ops_item_wrapper.id}",
)
print(
f"Now we will get the status of the OpsItem {self.ops_item_wrapper.id}"
)
q.ask("Please hit Enter")
# It may take a second for the ops item to be available
counter = 0
while not self.ops_item_wrapper.describe() and counter < 5:
counter += 1
time.sleep(1)
print(f"Now we will resolve the OpsItem {self.ops_item_wrapper.id}")
q.ask("Please hit Enter")
self.ops_item_wrapper.update(status="Resolved")
print("-" * 88)
print("-" * 88)
if q.ask(
"Would you like to delete the Systems Manager resources? (y/n)",
q.is_yesno,
):
print("You selected to delete the resources.")
self.cleanup()
else:
print("The Systems Manager resources will not be deleted")
print("-" * 88)
print("This concludes the Systems Manager SDK Getting Started scenario.")
print("-" * 88)
except Exception:
self.cleanup()
raise
def cleanup(self):
self.maintenance_window_wrapper.delete()
self.ops_item_wrapper.delete()
self.document_wrapper.delete()
if __name__ == "__main__":
try:
scenario = SystemsManagerScenario(
DocumentWrapper.from_client(),
MaintenanceWindowWrapper.from_client(),
OpsItemWrapper.from_client(),
)
scenario.run()
except Exception:
logging.exception("Something went wrong with the demo.")
```
ドキュメントとコマンドのアクションをラップするクラスを定義します。
```
class DocumentWrapper:
"""Encapsulates AWS Systems Manager Document actions."""
def __init__(self, ssm_client):
"""
:param ssm_client: A Boto3 Systems Manager client.
"""
self.ssm_client = ssm_client
self.name = None
@classmethod
def from_client(cls):
ssm_client = boto3.client("ssm")
return cls(ssm_client)
def create(self, content, name):
"""
Creates a document.
:param content: The content of the document.
:param name: The name of the document.
"""
try:
self.ssm_client.create_document(
Name=name, Content=content, DocumentType="Command"
)
self.name = name
except self.ssm_client.exceptions.DocumentAlreadyExists:
print(f"Document {name} already exists.")
self.name = name
except ClientError as err:
logger.error(
"Couldn't create %s. Here's why: %s: %s",
name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
def delete(self):
"""
Deletes an AWS Systems Manager document.
"""
if self.name is None:
return
try:
self.ssm_client.delete_document(Name=self.name)
print(f"Deleted document {self.name}.")
self.name = None
except ClientError as err:
logger.error(
"Couldn't delete %s. Here's why: %s: %s",
self.name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
def send_command(self, instance_ids):
"""
Sends a command to one or more instances.
:param instance_ids: The IDs of the instances to send the command to.
:return: The ID of the command.
"""
try:
response = self.ssm_client.send_command(
InstanceIds=instance_ids, DocumentName=self.name, TimeoutSeconds=3600
)
return response["Command"]["CommandId"]
except ClientError as err:
logger.error(
"Couldn't send command to %s. Here's why: %s: %s",
self.name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
def describe(self):
"""
Describes the document.
:return: Document status.
"""
try:
response = self.ssm_client.describe_document(Name=self.name)
return response["Document"]["Status"]
except ClientError as err:
logger.error(
"Couldn't get %s. Here's why: %s: %s",
self.name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
def wait_until_active(self, max_attempts=20, delay=5):
"""
Waits until the document is active.
:param max_attempts: The maximum number of attempts for checking the status.
:param delay: The delay in seconds between each check.
"""
attempt = 0
status = ""
while attempt <= max_attempts:
status = self.describe()
if status == "Active":
break
attempt += 1
time.sleep(delay)
if status != "Active":
logger.error("Document is not active.")
else:
logger.info("Document is active.")
def wait_command_executed(self, command_id, instance_id):
"""
Waits until the command is executed on the instance.
:param command_id: The ID of the command.
:param instance_id: The ID of the instance.
"""
waiter = self.ssm_client.get_waiter("command_executed")
waiter.wait(CommandId=command_id, InstanceId=instance_id)
def list_command_invocations(self, instance_id):
"""
Lists the commands for an instance.
:param instance_id: The ID of the instance.
:return: The list of commands.
"""
try:
paginator = self.ssm_client.get_paginator("list_command_invocations")
command_invocations = []
for page in paginator.paginate(InstanceId=instance_id):
command_invocations.extend(page["CommandInvocations"])
num_of_commands = len(command_invocations)
print(
f"{num_of_commands} command invocation(s) found for instance {instance_id}."
)
if num_of_commands > 10:
print("Displaying the first 10 commands:")
num_of_commands = 10
date_format = "%A, %d %B %Y %I:%M%p"
for command in command_invocations[:num_of_commands]:
print(
f" The time of command invocation is {command['RequestedDateTime'].strftime(date_format)}"
)
except ClientError as err:
logger.error(
"Couldn't list commands for %s. Here's why: %s: %s",
instance_id,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
Ops 項目のアクションをラップするクラスを定義します。
```
class OpsItemWrapper:
"""Encapsulates AWS Systems Manager OpsItem actions."""
def __init__(self, ssm_client):
"""
:param ssm_client: A Boto3 Systems Manager client.
"""
self.ssm_client = ssm_client
self.id = None
@classmethod
def from_client(cls):
"""
:return: A OpsItemWrapper instance.
"""
ssm_client = boto3.client("ssm")
return cls(ssm_client)
def create(self, title, source, category, severity, description):
"""
Create an OpsItem
:param title: The OpsItem title.
:param source: The OpsItem source.
:param category: The OpsItem category.
:param severity: The OpsItem severity.
:param description: The OpsItem description.
"""
try:
response = self.ssm_client.create_ops_item(
Title=title,
Source=source,
Category=category,
Severity=severity,
Description=description,
)
self.id = response["OpsItemId"]
except self.ssm_client.exceptions.OpsItemLimitExceededException as err:
logger.error(
"Couldn't create ops item because you have exceeded your open OpsItem limit. "
"Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
except ClientError as err:
logger.error(
"Couldn't create ops item %s. Here's why: %s: %s",
title,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
def delete(self):
"""
Delete the OpsItem.
"""
if self.id is None:
return
try:
self.ssm_client.delete_ops_item(OpsItemId=self.id)
print(f"Deleted ops item with id {self.id}")
self.id = None
except ClientError as err:
logger.error(
"Couldn't delete ops item %s. Here's why: %s: %s",
self.id,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
def describe(self):
"""
Describe an OpsItem.
"""
try:
paginator = self.ssm_client.get_paginator("describe_ops_items")
ops_items = []
for page in paginator.paginate(
OpsItemFilters=[
{"Key": "OpsItemId", "Values": [self.id], "Operator": "Equal"}
]
):
ops_items.extend(page["OpsItemSummaries"])
for item in ops_items:
print(
f"The item title is {item['Title']} and the status is {item['Status']}"
)
return len(ops_items) > 0
except ClientError as err:
logger.error(
"Couldn't describe ops item %s. Here's why: %s: %s",
self.id,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
def update(self, title=None, description=None, status=None):
"""
Update an OpsItem.
:param title: The new OpsItem title.
:param description: The new OpsItem description.
:param status: The new OpsItem status.
:return:
"""
args = dict(OpsItemId=self.id)
if title is not None:
args["Title"] = title
if description is not None:
args["Description"] = description
if status is not None:
args["Status"] = status
try:
self.ssm_client.update_ops_item(**args)
except ClientError as err:
logger.error(
"Couldn't update ops item %s. Here's why: %s: %s",
self.id,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
メンテナンスウィンドウのアクションをラップするクラスを定義します。
```
class MaintenanceWindowWrapper:
"""Encapsulates AWS Systems Manager maintenance window actions."""
def __init__(self, ssm_client):
"""
:param ssm_client: A Boto3 Systems Manager client.
"""
self.ssm_client = ssm_client
self.window_id = None
self.name = None
@classmethod
def from_client(cls):
ssm_client = boto3.client("ssm")
return cls(ssm_client)
def create(self, name, schedule, duration, cutoff, allow_unassociated_targets):
"""
Create an AWS Systems Manager maintenance window.
:param name: The name of the maintenance window.
:param schedule: The schedule of the maintenance window.
:param duration: The duration of the maintenance window.
:param cutoff: The cutoff time of the maintenance window.
:param allow_unassociated_targets: Allow the maintenance window to run on managed nodes, even
if you haven't registered those nodes as targets.
"""
try:
response = self.ssm_client.create_maintenance_window(
Name=name,
Schedule=schedule,
Duration=duration,
Cutoff=cutoff,
AllowUnassociatedTargets=allow_unassociated_targets,
)
self.window_id = response["WindowId"]
self.name = name
logger.info("Created maintenance window %s.", self.window_id)
except ParamValidationError as error:
logger.error(
"Parameter validation error when trying to create maintenance window %s. Here's why: %s",
self.window_id,
error,
)
raise
except ClientError as err:
logger.error(
"Couldn't create maintenance window %s. Here's why: %s: %s",
name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
def delete(self):
"""
Delete the associated AWS Systems Manager maintenance window.
"""
if self.window_id is None:
return
try:
self.ssm_client.delete_maintenance_window(WindowId=self.window_id)
logger.info("Deleted maintenance window %s.", self.window_id)
print(f"Deleted maintenance window {self.name}")
self.window_id = None
except ClientError as err:
logger.error(
"Couldn't delete maintenance window %s. Here's why: %s: %s",
self.window_id,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
def update(
self, name, enabled, schedule, duration, cutoff, allow_unassociated_targets
):
"""
Update an AWS Systems Manager maintenance window.
:param name: The name of the maintenance window.
:param enabled: Whether the maintenance window is enabled to run on managed nodes.
:param schedule: The schedule of the maintenance window.
:param duration: The duration of the maintenance window.
:param cutoff: The cutoff time of the maintenance window.
:param allow_unassociated_targets: Allow the maintenance window to run on managed nodes, even
if you haven't registered those nodes as targets.
"""
try:
self.ssm_client.update_maintenance_window(
WindowId=self.window_id,
Name=name,
Enabled=enabled,
Schedule=schedule,
Duration=duration,
Cutoff=cutoff,
AllowUnassociatedTargets=allow_unassociated_targets,
)
self.name = name
logger.info("Updated maintenance window %s.", self.window_id)
except ParamValidationError as error:
logger.error(
"Parameter validation error when trying to update maintenance window %s. Here's why: %s",
self.window_id,
error,
)
raise
except ClientError as err:
logger.error(
"Couldn't update maintenance window %s. Here's why: %s: %s",
self.name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ API の詳細については、『*AWS SDK for Python (Boto3) API リファレンス*』の以下のトピックを参照してください。
+ [CreateDocument](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/CreateDocument)
+ [CreateMaintenanceWindow](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/CreateMaintenanceWindow)
+ [CreateOpsItem](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/CreateOpsItem)
+ [DeleteMaintenanceWindow](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/DeleteMaintenanceWindow)
+ [ListCommandInvocations](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/ListCommandInvocations)
+ [SendCommand](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/SendCommand)
+ [UpdateOpsItem](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/UpdateOpsItem)
## アクション
### `CreateDocument`
次のコード例は、`CreateDocument` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ssm#code-examples)での設定と実行の方法を確認してください。
```
class DocumentWrapper:
"""Encapsulates AWS Systems Manager Document actions."""
def __init__(self, ssm_client):
"""
:param ssm_client: A Boto3 Systems Manager client.
"""
self.ssm_client = ssm_client
self.name = None
@classmethod
def from_client(cls):
ssm_client = boto3.client("ssm")
return cls(ssm_client)
def create(self, content, name):
"""
Creates a document.
:param content: The content of the document.
:param name: The name of the document.
"""
try:
self.ssm_client.create_document(
Name=name, Content=content, DocumentType="Command"
)
self.name = name
except self.ssm_client.exceptions.DocumentAlreadyExists:
print(f"Document {name} already exists.")
self.name = name
except ClientError as err:
logger.error(
"Couldn't create %s. Here's why: %s: %s",
name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[CreateDocument](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/CreateDocument)」を参照してください。
### `CreateMaintenanceWindow`
次のコード例は、`CreateMaintenanceWindow` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ssm#code-examples)での設定と実行の方法を確認してください。
```
class MaintenanceWindowWrapper:
"""Encapsulates AWS Systems Manager maintenance window actions."""
def __init__(self, ssm_client):
"""
:param ssm_client: A Boto3 Systems Manager client.
"""
self.ssm_client = ssm_client
self.window_id = None
self.name = None
@classmethod
def from_client(cls):
ssm_client = boto3.client("ssm")
return cls(ssm_client)
def create(self, name, schedule, duration, cutoff, allow_unassociated_targets):
"""
Create an AWS Systems Manager maintenance window.
:param name: The name of the maintenance window.
:param schedule: The schedule of the maintenance window.
:param duration: The duration of the maintenance window.
:param cutoff: The cutoff time of the maintenance window.
:param allow_unassociated_targets: Allow the maintenance window to run on managed nodes, even
if you haven't registered those nodes as targets.
"""
try:
response = self.ssm_client.create_maintenance_window(
Name=name,
Schedule=schedule,
Duration=duration,
Cutoff=cutoff,
AllowUnassociatedTargets=allow_unassociated_targets,
)
self.window_id = response["WindowId"]
self.name = name
logger.info("Created maintenance window %s.", self.window_id)
except ParamValidationError as error:
logger.error(
"Parameter validation error when trying to create maintenance window %s. Here's why: %s",
self.window_id,
error,
)
raise
except ClientError as err:
logger.error(
"Couldn't create maintenance window %s. Here's why: %s: %s",
name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[CreateMaintenanceWindow](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/CreateMaintenanceWindow)」を参照してください。
### `CreateOpsItem`
次のコード例は、`CreateOpsItem` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ssm#code-examples)での設定と実行の方法を確認してください。
```
class OpsItemWrapper:
"""Encapsulates AWS Systems Manager OpsItem actions."""
def __init__(self, ssm_client):
"""
:param ssm_client: A Boto3 Systems Manager client.
"""
self.ssm_client = ssm_client
self.id = None
@classmethod
def from_client(cls):
"""
:return: A OpsItemWrapper instance.
"""
ssm_client = boto3.client("ssm")
return cls(ssm_client)
def create(self, title, source, category, severity, description):
"""
Create an OpsItem
:param title: The OpsItem title.
:param source: The OpsItem source.
:param category: The OpsItem category.
:param severity: The OpsItem severity.
:param description: The OpsItem description.
"""
try:
response = self.ssm_client.create_ops_item(
Title=title,
Source=source,
Category=category,
Severity=severity,
Description=description,
)
self.id = response["OpsItemId"]
except self.ssm_client.exceptions.OpsItemLimitExceededException as err:
logger.error(
"Couldn't create ops item because you have exceeded your open OpsItem limit. "
"Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
except ClientError as err:
logger.error(
"Couldn't create ops item %s. Here's why: %s: %s",
title,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[CreateOpsItem](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/CreateOpsItem)」を参照してください。
### `DeleteDocument`
次のコード例は、`DeleteDocument` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ssm#code-examples)での設定と実行の方法を確認してください。
```
class DocumentWrapper:
"""Encapsulates AWS Systems Manager Document actions."""
def __init__(self, ssm_client):
"""
:param ssm_client: A Boto3 Systems Manager client.
"""
self.ssm_client = ssm_client
self.name = None
@classmethod
def from_client(cls):
ssm_client = boto3.client("ssm")
return cls(ssm_client)
def delete(self):
"""
Deletes an AWS Systems Manager document.
"""
if self.name is None:
return
try:
self.ssm_client.delete_document(Name=self.name)
print(f"Deleted document {self.name}.")
self.name = None
except ClientError as err:
logger.error(
"Couldn't delete %s. Here's why: %s: %s",
self.name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[DeleteDocument](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/DeleteDocument)」を参照してください。
### `DeleteMaintenanceWindow`
次のコード例は、`DeleteMaintenanceWindow` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ssm#code-examples)での設定と実行の方法を確認してください。
```
class MaintenanceWindowWrapper:
"""Encapsulates AWS Systems Manager maintenance window actions."""
def __init__(self, ssm_client):
"""
:param ssm_client: A Boto3 Systems Manager client.
"""
self.ssm_client = ssm_client
self.window_id = None
self.name = None
@classmethod
def from_client(cls):
ssm_client = boto3.client("ssm")
return cls(ssm_client)
def delete(self):
"""
Delete the associated AWS Systems Manager maintenance window.
"""
if self.window_id is None:
return
try:
self.ssm_client.delete_maintenance_window(WindowId=self.window_id)
logger.info("Deleted maintenance window %s.", self.window_id)
print(f"Deleted maintenance window {self.name}")
self.window_id = None
except ClientError as err:
logger.error(
"Couldn't delete maintenance window %s. Here's why: %s: %s",
self.window_id,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[DeleteMaintenanceWindow](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/DeleteMaintenanceWindow)」を参照してください。
### `DeleteOpsItem`
次のコード例は、`DeleteOpsItem` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ssm#code-examples)での設定と実行の方法を確認してください。
```
class OpsItemWrapper:
"""Encapsulates AWS Systems Manager OpsItem actions."""
def __init__(self, ssm_client):
"""
:param ssm_client: A Boto3 Systems Manager client.
"""
self.ssm_client = ssm_client
self.id = None
@classmethod
def from_client(cls):
"""
:return: A OpsItemWrapper instance.
"""
ssm_client = boto3.client("ssm")
return cls(ssm_client)
def delete(self):
"""
Delete the OpsItem.
"""
if self.id is None:
return
try:
self.ssm_client.delete_ops_item(OpsItemId=self.id)
print(f"Deleted ops item with id {self.id}")
self.id = None
except ClientError as err:
logger.error(
"Couldn't delete ops item %s. Here's why: %s: %s",
self.id,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ API の詳細については、「AWS SDK for Python (Boto3) API リファレンス」の「[DeleteOpsItem](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/DeleteOpsItem)」を参照してください。
### `DescribeOpsItems`
次のコード例は、`DescribeOpsItems` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ssm#code-examples)での設定と実行の方法を確認してください。
```
class OpsItemWrapper:
"""Encapsulates AWS Systems Manager OpsItem actions."""
def __init__(self, ssm_client):
"""
:param ssm_client: A Boto3 Systems Manager client.
"""
self.ssm_client = ssm_client
self.id = None
@classmethod
def from_client(cls):
"""
:return: A OpsItemWrapper instance.
"""
ssm_client = boto3.client("ssm")
return cls(ssm_client)
def describe(self):
"""
Describe an OpsItem.
"""
try:
paginator = self.ssm_client.get_paginator("describe_ops_items")
ops_items = []
for page in paginator.paginate(
OpsItemFilters=[
{"Key": "OpsItemId", "Values": [self.id], "Operator": "Equal"}
]
):
ops_items.extend(page["OpsItemSummaries"])
for item in ops_items:
print(
f"The item title is {item['Title']} and the status is {item['Status']}"
)
return len(ops_items) > 0
except ClientError as err:
logger.error(
"Couldn't describe ops item %s. Here's why: %s: %s",
self.id,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[DescribeOpsItems](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/DescribeOpsItems)」を参照してください。
### `ListCommandInvocations`
次のコード例は、`ListCommandInvocations` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ssm#code-examples)での設定と実行の方法を確認してください。
```
class DocumentWrapper:
"""Encapsulates AWS Systems Manager Document actions."""
def __init__(self, ssm_client):
"""
:param ssm_client: A Boto3 Systems Manager client.
"""
self.ssm_client = ssm_client
self.name = None
@classmethod
def from_client(cls):
ssm_client = boto3.client("ssm")
return cls(ssm_client)
def list_command_invocations(self, instance_id):
"""
Lists the commands for an instance.
:param instance_id: The ID of the instance.
:return: The list of commands.
"""
try:
paginator = self.ssm_client.get_paginator("list_command_invocations")
command_invocations = []
for page in paginator.paginate(InstanceId=instance_id):
command_invocations.extend(page["CommandInvocations"])
num_of_commands = len(command_invocations)
print(
f"{num_of_commands} command invocation(s) found for instance {instance_id}."
)
if num_of_commands > 10:
print("Displaying the first 10 commands:")
num_of_commands = 10
date_format = "%A, %d %B %Y %I:%M%p"
for command in command_invocations[:num_of_commands]:
print(
f" The time of command invocation is {command['RequestedDateTime'].strftime(date_format)}"
)
except ClientError as err:
logger.error(
"Couldn't list commands for %s. Here's why: %s: %s",
instance_id,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[ListCommandInvocations](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/ListCommandInvocations)」を参照してください。
### `SendCommand`
次のコード例は、`SendCommand` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ssm#code-examples)での設定と実行の方法を確認してください。
```
class DocumentWrapper:
"""Encapsulates AWS Systems Manager Document actions."""
def __init__(self, ssm_client):
"""
:param ssm_client: A Boto3 Systems Manager client.
"""
self.ssm_client = ssm_client
self.name = None
@classmethod
def from_client(cls):
ssm_client = boto3.client("ssm")
return cls(ssm_client)
def send_command(self, instance_ids):
"""
Sends a command to one or more instances.
:param instance_ids: The IDs of the instances to send the command to.
:return: The ID of the command.
"""
try:
response = self.ssm_client.send_command(
InstanceIds=instance_ids, DocumentName=self.name, TimeoutSeconds=3600
)
return response["Command"]["CommandId"]
except ClientError as err:
logger.error(
"Couldn't send command to %s. Here's why: %s: %s",
self.name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[SendCommand](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/SendCommand)」を参照してください。
### `UpdateMaintenanceWindow`
次のコード例は、`UpdateMaintenanceWindow` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ssm#code-examples)での設定と実行の方法を確認してください。
```
class MaintenanceWindowWrapper:
"""Encapsulates AWS Systems Manager maintenance window actions."""
def __init__(self, ssm_client):
"""
:param ssm_client: A Boto3 Systems Manager client.
"""
self.ssm_client = ssm_client
self.window_id = None
self.name = None
@classmethod
def from_client(cls):
ssm_client = boto3.client("ssm")
return cls(ssm_client)
def update(
self, name, enabled, schedule, duration, cutoff, allow_unassociated_targets
):
"""
Update an AWS Systems Manager maintenance window.
:param name: The name of the maintenance window.
:param enabled: Whether the maintenance window is enabled to run on managed nodes.
:param schedule: The schedule of the maintenance window.
:param duration: The duration of the maintenance window.
:param cutoff: The cutoff time of the maintenance window.
:param allow_unassociated_targets: Allow the maintenance window to run on managed nodes, even
if you haven't registered those nodes as targets.
"""
try:
self.ssm_client.update_maintenance_window(
WindowId=self.window_id,
Name=name,
Enabled=enabled,
Schedule=schedule,
Duration=duration,
Cutoff=cutoff,
AllowUnassociatedTargets=allow_unassociated_targets,
)
self.name = name
logger.info("Updated maintenance window %s.", self.window_id)
except ParamValidationError as error:
logger.error(
"Parameter validation error when trying to update maintenance window %s. Here's why: %s",
self.window_id,
error,
)
raise
except ClientError as err:
logger.error(
"Couldn't update maintenance window %s. Here's why: %s: %s",
self.name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[UpdateMaintenanceWindow](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/UpdateMaintenanceWindow)」を参照してください。
### `UpdateOpsItem`
次のコード例は、`UpdateOpsItem` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ssm#code-examples)での設定と実行の方法を確認してください。
```
class OpsItemWrapper:
"""Encapsulates AWS Systems Manager OpsItem actions."""
def __init__(self, ssm_client):
"""
:param ssm_client: A Boto3 Systems Manager client.
"""
self.ssm_client = ssm_client
self.id = None
@classmethod
def from_client(cls):
"""
:return: A OpsItemWrapper instance.
"""
ssm_client = boto3.client("ssm")
return cls(ssm_client)
def update(self, title=None, description=None, status=None):
"""
Update an OpsItem.
:param title: The new OpsItem title.
:param description: The new OpsItem description.
:param status: The new OpsItem status.
:return:
"""
args = dict(OpsItemId=self.id)
if title is not None:
args["Title"] = title
if description is not None:
args["Description"] = description
if status is not None:
args["Status"] = status
try:
self.ssm_client.update_ops_item(**args)
except ClientError as err:
logger.error(
"Couldn't update ops item %s. Here's why: %s: %s",
self.id,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[UpdateOpsItem](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/UpdateOpsItem)」を参照してください。
# SDK for Python (Boto3) を使用する Amazon Textract の例
次のコード例は、Amazon Textract AWS SDK for Python (Boto3) で を使用してアクションを実行し、一般的なシナリオを実装する方法を示しています。
*アクション*はより大きなプログラムからのコードの抜粋であり、コンテキスト内で実行する必要があります。アクションは個々のサービス機能を呼び出す方法を示していますが、コンテキスト内のアクションは、関連するシナリオで確認できます。
*シナリオ*は、1 つのサービス内から、または他の AWS のサービスと組み合わせて複数の関数を呼び出し、特定のタスクを実行する方法を示すコード例です。
各例には完全なソースコードへのリンクが含まれており、コードの設定方法と実行方法に関する手順を確認できます。
**Topics**
+ [アクション](#actions)
+ [シナリオ](#scenarios)
## アクション
### `AnalyzeDocument`
次のコード例は、`AnalyzeDocument` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/textract#code-examples)での設定と実行の方法を確認してください。
```
class TextractWrapper:
"""Encapsulates Textract functions."""
def __init__(self, textract_client, s3_resource, sqs_resource):
"""
:param textract_client: A Boto3 Textract client.
:param s3_resource: A Boto3 Amazon S3 resource.
:param sqs_resource: A Boto3 Amazon SQS resource.
"""
self.textract_client = textract_client
self.s3_resource = s3_resource
self.sqs_resource = sqs_resource
def analyze_file(
self, feature_types, *, document_file_name=None, document_bytes=None
):
"""
Detects text and additional elements, such as forms or tables, in a local image
file or from in-memory byte data.
The image must be in PNG or JPG format.
:param feature_types: The types of additional document features to detect.
:param document_file_name: The name of a document image file.
:param document_bytes: In-memory byte data of a document image.
:return: The response from Amazon Textract, including a list of blocks
that describe elements detected in the image.
"""
if document_file_name is not None:
with open(document_file_name, "rb") as document_file:
document_bytes = document_file.read()
try:
response = self.textract_client.analyze_document(
Document={"Bytes": document_bytes}, FeatureTypes=feature_types
)
logger.info("Detected %s blocks.", len(response["Blocks"]))
except ClientError:
logger.exception("Couldn't detect text.")
raise
else:
return response
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[AnalyzeDocument](https://docs.aws.amazon.com/goto/boto3/textract-2018-06-27/AnalyzeDocument)」を参照してください。
### `DetectDocumentText`
次のコード例は、`DetectDocumentText` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/textract#code-examples)での設定と実行の方法を確認してください。
```
class TextractWrapper:
"""Encapsulates Textract functions."""
def __init__(self, textract_client, s3_resource, sqs_resource):
"""
:param textract_client: A Boto3 Textract client.
:param s3_resource: A Boto3 Amazon S3 resource.
:param sqs_resource: A Boto3 Amazon SQS resource.
"""
self.textract_client = textract_client
self.s3_resource = s3_resource
self.sqs_resource = sqs_resource
def detect_file_text(self, *, document_file_name=None, document_bytes=None):
"""
Detects text elements in a local image file or from in-memory byte data.
The image must be in PNG or JPG format.
:param document_file_name: The name of a document image file.
:param document_bytes: In-memory byte data of a document image.
:return: The response from Amazon Textract, including a list of blocks
that describe elements detected in the image.
"""
if document_file_name is not None:
with open(document_file_name, "rb") as document_file:
document_bytes = document_file.read()
try:
response = self.textract_client.detect_document_text(
Document={"Bytes": document_bytes}
)
logger.info("Detected %s blocks.", len(response["Blocks"]))
except ClientError:
logger.exception("Couldn't detect text.")
raise
else:
return response
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[DetectDocumentText](https://docs.aws.amazon.com/goto/boto3/textract-2018-06-27/DetectDocumentText)」を参照してください。
### `GetDocumentAnalysis`
次のコード例は、`GetDocumentAnalysis` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/textract#code-examples)での設定と実行の方法を確認してください。
```
class TextractWrapper:
"""Encapsulates Textract functions."""
def __init__(self, textract_client, s3_resource, sqs_resource):
"""
:param textract_client: A Boto3 Textract client.
:param s3_resource: A Boto3 Amazon S3 resource.
:param sqs_resource: A Boto3 Amazon SQS resource.
"""
self.textract_client = textract_client
self.s3_resource = s3_resource
self.sqs_resource = sqs_resource
def get_analysis_job(self, job_id):
"""
Gets data for a previously started detection job that includes additional
elements.
:param job_id: The ID of the job to retrieve.
:return: The job data, including a list of blocks that describe elements
detected in the image.
"""
try:
response = self.textract_client.get_document_analysis(JobId=job_id)
job_status = response["JobStatus"]
logger.info("Job %s status is %s.", job_id, job_status)
except ClientError:
logger.exception("Couldn't get data for job %s.", job_id)
raise
else:
return response
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[GetDocumentAnalysis](https://docs.aws.amazon.com/goto/boto3/textract-2018-06-27/GetDocumentAnalysis)」を参照してください。
### `StartDocumentAnalysis`
次のコード例は、`StartDocumentAnalysis` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/textract#code-examples)での設定と実行の方法を確認してください。
非同期ジョブを開始してドキュメントを分析します。
```
class TextractWrapper:
"""Encapsulates Textract functions."""
def __init__(self, textract_client, s3_resource, sqs_resource):
"""
:param textract_client: A Boto3 Textract client.
:param s3_resource: A Boto3 Amazon S3 resource.
:param sqs_resource: A Boto3 Amazon SQS resource.
"""
self.textract_client = textract_client
self.s3_resource = s3_resource
self.sqs_resource = sqs_resource
def start_analysis_job(
self,
bucket_name,
document_file_name,
feature_types,
sns_topic_arn,
sns_role_arn,
):
"""
Starts an asynchronous job to detect text and additional elements, such as
forms or tables, in an image stored in an Amazon S3 bucket. Textract publishes
a notification to the specified Amazon SNS topic when the job completes.
The image must be in PNG, JPG, or PDF format.
:param bucket_name: The name of the Amazon S3 bucket that contains the image.
:param document_file_name: The name of the document image stored in Amazon S3.
:param feature_types: The types of additional document features to detect.
:param sns_topic_arn: The Amazon Resource Name (ARN) of an Amazon SNS topic
where job completion notification is published.
:param sns_role_arn: The ARN of an AWS Identity and Access Management (IAM)
role that can be assumed by Textract and grants permission
to publish to the Amazon SNS topic.
:return: The ID of the job.
"""
try:
response = self.textract_client.start_document_analysis(
DocumentLocation={
"S3Object": {"Bucket": bucket_name, "Name": document_file_name}
},
NotificationChannel={
"SNSTopicArn": sns_topic_arn,
"RoleArn": sns_role_arn,
},
FeatureTypes=feature_types,
)
job_id = response["JobId"]
logger.info(
"Started text analysis job %s on %s.", job_id, document_file_name
)
except ClientError:
logger.exception("Couldn't analyze text in %s.", document_file_name)
raise
else:
return job_id
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[StartDocumentAnalysis](https://docs.aws.amazon.com/goto/boto3/textract-2018-06-27/StartDocumentAnalysis)」を参照してください。
### `StartDocumentTextDetection`
次のコード例は、`StartDocumentTextDetection` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/textract#code-examples)での設定と実行の方法を確認してください。
ドキュメント内のテキストを検出する非同期ジョブを開始します。
```
class TextractWrapper:
"""Encapsulates Textract functions."""
def __init__(self, textract_client, s3_resource, sqs_resource):
"""
:param textract_client: A Boto3 Textract client.
:param s3_resource: A Boto3 Amazon S3 resource.
:param sqs_resource: A Boto3 Amazon SQS resource.
"""
self.textract_client = textract_client
self.s3_resource = s3_resource
self.sqs_resource = sqs_resource
def start_detection_job(
self, bucket_name, document_file_name, sns_topic_arn, sns_role_arn
):
"""
Starts an asynchronous job to detect text elements in an image stored in an
Amazon S3 bucket. Textract publishes a notification to the specified Amazon SNS
topic when the job completes.
The image must be in PNG, JPG, or PDF format.
:param bucket_name: The name of the Amazon S3 bucket that contains the image.
:param document_file_name: The name of the document image stored in Amazon S3.
:param sns_topic_arn: The Amazon Resource Name (ARN) of an Amazon SNS topic
where the job completion notification is published.
:param sns_role_arn: The ARN of an AWS Identity and Access Management (IAM)
role that can be assumed by Textract and grants permission
to publish to the Amazon SNS topic.
:return: The ID of the job.
"""
try:
response = self.textract_client.start_document_text_detection(
DocumentLocation={
"S3Object": {"Bucket": bucket_name, "Name": document_file_name}
},
NotificationChannel={
"SNSTopicArn": sns_topic_arn,
"RoleArn": sns_role_arn,
},
)
job_id = response["JobId"]
logger.info(
"Started text detection job %s on %s.", job_id, document_file_name
)
except ClientError:
logger.exception("Couldn't detect text in %s.", document_file_name)
raise
else:
return job_id
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[StartDocumentTextDetection](https://docs.aws.amazon.com/goto/boto3/textract-2018-06-27/StartDocumentTextDetection)」を参照してください。
## シナリオ
### Amazon Textract エクスプローラーアプリケーションを作成する
次のコード例は、インタラクティブアプリケーションで Amazon Textract の出力を調べる方法を示しています。
**SDK for Python (Boto3)**
Amazon Textract AWS SDK for Python (Boto3) で を使用して、ドキュメントイメージ内のテキスト、フォーム、テーブル要素を検出する方法を示します。入力イメージと Amazon Textract 出力は、検出された要素を探索できる Tkinter アプリケーションに表示されます。
+ Amazon Textract にドキュメントイメージを送信し、検出された要素の出力を調べます。
+ Amazon Textract に直接イメージを送信するか、Amazon Simple Storage Service (Amazon S3) バケットを通じてイメージを送信します。
+ 非同期 API を使用して、ジョブの完了時に Amazon Simple Notification Service (Amazon SNS) トピックに通知を発行するジョブを開始します。
+ Amazon Simple Queue Service (Amazon SQS) キューにジョブ完了メッセージについてポーリングし、結果を表示します。
完全なソースコードとセットアップおよび実行の手順については、[GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/textract_explorer) で完全な例を参照してください。
**この例で使用されているサービス**
+ Amazon Cognito ID
+ Amazon S3
+ Amazon SNS
+ Amazon SQS
+ Amazon Textract
### 画像から抽出されたテキスト内のエンティティを検出する
次のコード例は、Amazon Comprehend を使用して、Amazon S3 に格納されている画像から Amazon Textract によって抽出されたテキスト内のエンティティを検出する方法を示しています。
**SDK for Python (Boto3)**
Jupyter ノートブック AWS SDK for Python (Boto3) で を使用して、イメージから抽出されたテキスト内のエンティティを検出する方法を示します。この例では、Amazon Textract を使用して Amazon Simple Storage Service (Amazon S3) に保存されている画像からテキストを抽出し、Amazon Comprehend を使用して、抽出されたテキスト内のエンティティを検出します。
この例は Jupyter Notebook であり、ノートブックをホストできる環境で実行する必要があります。Amazon SageMaker AI を使用してサンプルを実行する方法については、「[TextractAndComprehendNotebook.ipynb](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/textract_comprehend_notebook/TextractAndComprehendNotebook.ipynb)」の手順を参照してください。
完全なソースコードとセットアップおよび実行の手順については、[GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/textract_comprehend_notebook#readme) で完全な例を参照してください。
**この例で使用されているサービス**
+ Amazon Comprehend
+ Amazon S3
+ Amazon Textract
# SDK for Python (Boto3) を使用する Amazon Transcribe の例
次のコード例は、Amazon Transcribe AWS SDK for Python (Boto3) で を使用してアクションを実行し、一般的なシナリオを実装する方法を示しています。
*アクション*はより大きなプログラムからのコードの抜粋であり、コンテキスト内で実行する必要があります。アクションは個々のサービス機能を呼び出す方法を示していますが、コンテキスト内のアクションは、関連するシナリオで確認できます。
*シナリオ*は、1 つのサービス内から、または他の AWS のサービスと組み合わせて複数の関数を呼び出し、特定のタスクを実行する方法を示すコード例です。
各例には完全なソースコードへのリンクが含まれており、コードの設定方法と実行方法に関する手順を確認できます。
**Topics**
+ [アクション](#actions)
+ [シナリオ](#scenarios)
## アクション
### `CreateVocabulary`
次のコード例は、`CreateVocabulary` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/transcribe#code-examples)での設定と実行の方法を確認してください。
```
def create_vocabulary(
vocabulary_name, language_code, transcribe_client, phrases=None, table_uri=None
):
"""
Creates a custom vocabulary that can be used to improve the accuracy of
transcription jobs. This function returns as soon as the vocabulary processing
is started. Call get_vocabulary to get the current status of the vocabulary.
The vocabulary is ready to use when its status is 'READY'.
:param vocabulary_name: The name of the custom vocabulary.
:param language_code: The language code of the vocabulary.
For example, en-US or nl-NL.
:param transcribe_client: The Boto3 Transcribe client.
:param phrases: A list of comma-separated phrases to include in the vocabulary.
:param table_uri: A table of phrases and pronunciation hints to include in the
vocabulary.
:return: Information about the newly created vocabulary.
"""
try:
vocab_args = {"VocabularyName": vocabulary_name, "LanguageCode": language_code}
if phrases is not None:
vocab_args["Phrases"] = phrases
elif table_uri is not None:
vocab_args["VocabularyFileUri"] = table_uri
response = transcribe_client.create_vocabulary(**vocab_args)
logger.info("Created custom vocabulary %s.", response["VocabularyName"])
except ClientError:
logger.exception("Couldn't create custom vocabulary %s.", vocabulary_name)
raise
else:
return response
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[CreateVocabulary](https://docs.aws.amazon.com/goto/boto3/transcribe-2017-10-26/CreateVocabulary)」を参照してください。
### `DeleteTranscriptionJob`
次のコード例は、`DeleteTranscriptionJob` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/transcribe#code-examples)での設定と実行の方法を確認してください。
```
def delete_job(job_name, transcribe_client):
"""
Deletes a transcription job. This also deletes the transcript associated with
the job.
:param job_name: The name of the job to delete.
:param transcribe_client: The Boto3 Transcribe client.
"""
try:
transcribe_client.delete_transcription_job(TranscriptionJobName=job_name)
logger.info("Deleted job %s.", job_name)
except ClientError:
logger.exception("Couldn't delete job %s.", job_name)
raise
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[DeleteTranscriptionJob](https://docs.aws.amazon.com/goto/boto3/transcribe-2017-10-26/DeleteTranscriptionJob)」を参照してください。
### `DeleteVocabulary`
次のコード例は、`DeleteVocabulary` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/transcribe#code-examples)での設定と実行の方法を確認してください。
```
def delete_vocabulary(vocabulary_name, transcribe_client):
"""
Deletes a custom vocabulary.
:param vocabulary_name: The name of the vocabulary to delete.
:param transcribe_client: The Boto3 Transcribe client.
"""
try:
transcribe_client.delete_vocabulary(VocabularyName=vocabulary_name)
logger.info("Deleted vocabulary %s.", vocabulary_name)
except ClientError:
logger.exception("Couldn't delete vocabulary %s.", vocabulary_name)
raise
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[DeleteVocabulary](https://docs.aws.amazon.com/goto/boto3/transcribe-2017-10-26/DeleteVocabulary)」を参照してください。
### `GetTranscriptionJob`
次のコード例は、`GetTranscriptionJob` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/transcribe#code-examples)での設定と実行の方法を確認してください。
```
def get_job(job_name, transcribe_client):
"""
Gets details about a transcription job.
:param job_name: The name of the job to retrieve.
:param transcribe_client: The Boto3 Transcribe client.
:return: The retrieved transcription job.
"""
try:
response = transcribe_client.get_transcription_job(
TranscriptionJobName=job_name
)
job = response["TranscriptionJob"]
logger.info("Got job %s.", job["TranscriptionJobName"])
except ClientError:
logger.exception("Couldn't get job %s.", job_name)
raise
else:
return job
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[GetTranscriptionJob](https://docs.aws.amazon.com/goto/boto3/transcribe-2017-10-26/GetTranscriptionJob)」を参照してください。
### `GetVocabulary`
次のコード例は、`GetVocabulary` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/transcribe#code-examples)での設定と実行の方法を確認してください。
```
def get_vocabulary(vocabulary_name, transcribe_client):
"""
Gets information about a custom vocabulary.
:param vocabulary_name: The name of the vocabulary to retrieve.
:param transcribe_client: The Boto3 Transcribe client.
:return: Information about the vocabulary.
"""
try:
response = transcribe_client.get_vocabulary(VocabularyName=vocabulary_name)
logger.info("Got vocabulary %s.", response["VocabularyName"])
except ClientError:
logger.exception("Couldn't get vocabulary %s.", vocabulary_name)
raise
else:
return response
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[GetVocabulary](https://docs.aws.amazon.com/goto/boto3/transcribe-2017-10-26/GetVocabulary)」を参照してください。
### `ListTranscriptionJobs`
次のコード例は、`ListTranscriptionJobs` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/transcribe#code-examples)での設定と実行の方法を確認してください。
```
def list_jobs(job_filter, transcribe_client):
"""
Lists summaries of the transcription jobs for the current AWS account.
:param job_filter: The list of returned jobs must contain this string in their
names.
:param transcribe_client: The Boto3 Transcribe client.
:return: The list of retrieved transcription job summaries.
"""
try:
response = transcribe_client.list_transcription_jobs(JobNameContains=job_filter)
jobs = response["TranscriptionJobSummaries"]
next_token = response.get("NextToken")
while next_token is not None:
response = transcribe_client.list_transcription_jobs(
JobNameContains=job_filter, NextToken=next_token
)
jobs += response["TranscriptionJobSummaries"]
next_token = response.get("NextToken")
logger.info("Got %s jobs with filter %s.", len(jobs), job_filter)
except ClientError:
logger.exception("Couldn't get jobs with filter %s.", job_filter)
raise
else:
return jobs
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[ListTranscriptionJobs](https://docs.aws.amazon.com/goto/boto3/transcribe-2017-10-26/ListTranscriptionJobs)」を参照してください。
### `ListVocabularies`
次のコード例は、`ListVocabularies` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/transcribe#code-examples)での設定と実行の方法を確認してください。
```
def list_vocabularies(vocabulary_filter, transcribe_client):
"""
Lists the custom vocabularies created for this AWS account.
:param vocabulary_filter: The returned vocabularies must contain this string in
their names.
:param transcribe_client: The Boto3 Transcribe client.
:return: The list of retrieved vocabularies.
"""
try:
response = transcribe_client.list_vocabularies(NameContains=vocabulary_filter)
vocabs = response["Vocabularies"]
next_token = response.get("NextToken")
while next_token is not None:
response = transcribe_client.list_vocabularies(
NameContains=vocabulary_filter, NextToken=next_token
)
vocabs += response["Vocabularies"]
next_token = response.get("NextToken")
logger.info(
"Got %s vocabularies with filter %s.", len(vocabs), vocabulary_filter
)
except ClientError:
logger.exception(
"Couldn't list vocabularies with filter %s.", vocabulary_filter
)
raise
else:
return vocabs
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[ListVocabularies](https://docs.aws.amazon.com/goto/boto3/transcribe-2017-10-26/ListVocabularies)」を参照してください。
### `StartTranscriptionJob`
次のコード例は、`StartTranscriptionJob` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/transcribe#code-examples)での設定と実行の方法を確認してください。
```
def start_job(
job_name,
media_uri,
media_format,
language_code,
transcribe_client,
vocabulary_name=None,
):
"""
Starts a transcription job. This function returns as soon as the job is started.
To get the current status of the job, call get_transcription_job. The job is
successfully completed when the job status is 'COMPLETED'.
:param job_name: The name of the transcription job. This must be unique for
your AWS account.
:param media_uri: The URI where the audio file is stored. This is typically
in an Amazon S3 bucket.
:param media_format: The format of the audio file. For example, mp3 or wav.
:param language_code: The language code of the audio file.
For example, en-US or ja-JP
:param transcribe_client: The Boto3 Transcribe client.
:param vocabulary_name: The name of a custom vocabulary to use when transcribing
the audio file.
:return: Data about the job.
"""
try:
job_args = {
"TranscriptionJobName": job_name,
"Media": {"MediaFileUri": media_uri},
"MediaFormat": media_format,
"LanguageCode": language_code,
}
if vocabulary_name is not None:
job_args["Settings"] = {"VocabularyName": vocabulary_name}
response = transcribe_client.start_transcription_job(**job_args)
job = response["TranscriptionJob"]
logger.info("Started transcription job %s.", job_name)
except ClientError:
logger.exception("Couldn't start transcription job %s.", job_name)
raise
else:
return job
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の「[StartTranscriptionJob](https://docs.aws.amazon.com/goto/boto3/transcribe-2017-10-26/StartTranscriptionJob)」を参照してください。
### `UpdateVocabulary`
次のコード例は、`UpdateVocabulary` を使用する方法を示しています。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/transcribe#code-examples)での設定と実行の方法を確認してください。
```
def update_vocabulary(
vocabulary_name, language_code, transcribe_client, phrases=None, table_uri=None
):
"""
Updates an existing custom vocabulary. The entire vocabulary is replaced with
the contents of the update.
:param vocabulary_name: The name of the vocabulary to update.
:param language_code: The language code of the vocabulary.
:param transcribe_client: The Boto3 Transcribe client.
:param phrases: A list of comma-separated phrases to include in the vocabulary.
:param table_uri: A table of phrases and pronunciation hints to include in the
vocabulary.
"""
try:
vocab_args = {"VocabularyName": vocabulary_name, "LanguageCode": language_code}
if phrases is not None:
vocab_args["Phrases"] = phrases
elif table_uri is not None:
vocab_args["VocabularyFileUri"] = table_uri
response = transcribe_client.update_vocabulary(**vocab_args)
logger.info("Updated custom vocabulary %s.", response["VocabularyName"])
except ClientError:
logger.exception("Couldn't update custom vocabulary %s.", vocabulary_name)
raise
```
+ API の詳細については、*AWS SDK for Python (Boto3) API リファレンス*の「[UpdateVocabulary](https://docs.aws.amazon.com/goto/boto3/transcribe-2017-10-26/UpdateVocabulary)」を参照してください。
## シナリオ
### カスタム語彙を作成し改良する
次のコード例は、以下の操作方法を示しています。
+ Amazon S3 に音声ファイルをアップロードします。
+ Amazon Transcribe ジョブを実行してファイルを文字起こしし、結果を取得します。
+ カスタム語彙を作成して改良し、文字起こしの精度を向上させます。
+ カスタム語彙を使ってジョブを実行し、結果を取得します。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/transcribe#code-examples)での設定と実行の方法を確認してください。
ルイス キャロルによる「ジャバウォッキー」の朗読を収録した音声ファイルを文字起こしします。まず、Amazon Transcribe アクションをラップする関数を作成します。
```
def start_job(
job_name,
media_uri,
media_format,
language_code,
transcribe_client,
vocabulary_name=None,
):
"""
Starts a transcription job. This function returns as soon as the job is started.
To get the current status of the job, call get_transcription_job. The job is
successfully completed when the job status is 'COMPLETED'.
:param job_name: The name of the transcription job. This must be unique for
your AWS account.
:param media_uri: The URI where the audio file is stored. This is typically
in an Amazon S3 bucket.
:param media_format: The format of the audio file. For example, mp3 or wav.
:param language_code: The language code of the audio file.
For example, en-US or ja-JP
:param transcribe_client: The Boto3 Transcribe client.
:param vocabulary_name: The name of a custom vocabulary to use when transcribing
the audio file.
:return: Data about the job.
"""
try:
job_args = {
"TranscriptionJobName": job_name,
"Media": {"MediaFileUri": media_uri},
"MediaFormat": media_format,
"LanguageCode": language_code,
}
if vocabulary_name is not None:
job_args["Settings"] = {"VocabularyName": vocabulary_name}
response = transcribe_client.start_transcription_job(**job_args)
job = response["TranscriptionJob"]
logger.info("Started transcription job %s.", job_name)
except ClientError:
logger.exception("Couldn't start transcription job %s.", job_name)
raise
else:
return job
def get_job(job_name, transcribe_client):
"""
Gets details about a transcription job.
:param job_name: The name of the job to retrieve.
:param transcribe_client: The Boto3 Transcribe client.
:return: The retrieved transcription job.
"""
try:
response = transcribe_client.get_transcription_job(
TranscriptionJobName=job_name
)
job = response["TranscriptionJob"]
logger.info("Got job %s.", job["TranscriptionJobName"])
except ClientError:
logger.exception("Couldn't get job %s.", job_name)
raise
else:
return job
def delete_job(job_name, transcribe_client):
"""
Deletes a transcription job. This also deletes the transcript associated with
the job.
:param job_name: The name of the job to delete.
:param transcribe_client: The Boto3 Transcribe client.
"""
try:
transcribe_client.delete_transcription_job(TranscriptionJobName=job_name)
logger.info("Deleted job %s.", job_name)
except ClientError:
logger.exception("Couldn't delete job %s.", job_name)
raise
def create_vocabulary(
vocabulary_name, language_code, transcribe_client, phrases=None, table_uri=None
):
"""
Creates a custom vocabulary that can be used to improve the accuracy of
transcription jobs. This function returns as soon as the vocabulary processing
is started. Call get_vocabulary to get the current status of the vocabulary.
The vocabulary is ready to use when its status is 'READY'.
:param vocabulary_name: The name of the custom vocabulary.
:param language_code: The language code of the vocabulary.
For example, en-US or nl-NL.
:param transcribe_client: The Boto3 Transcribe client.
:param phrases: A list of comma-separated phrases to include in the vocabulary.
:param table_uri: A table of phrases and pronunciation hints to include in the
vocabulary.
:return: Information about the newly created vocabulary.
"""
try:
vocab_args = {"VocabularyName": vocabulary_name, "LanguageCode": language_code}
if phrases is not None:
vocab_args["Phrases"] = phrases
elif table_uri is not None:
vocab_args["VocabularyFileUri"] = table_uri
response = transcribe_client.create_vocabulary(**vocab_args)
logger.info("Created custom vocabulary %s.", response["VocabularyName"])
except ClientError:
logger.exception("Couldn't create custom vocabulary %s.", vocabulary_name)
raise
else:
return response
def get_vocabulary(vocabulary_name, transcribe_client):
"""
Gets information about a custom vocabulary.
:param vocabulary_name: The name of the vocabulary to retrieve.
:param transcribe_client: The Boto3 Transcribe client.
:return: Information about the vocabulary.
"""
try:
response = transcribe_client.get_vocabulary(VocabularyName=vocabulary_name)
logger.info("Got vocabulary %s.", response["VocabularyName"])
except ClientError:
logger.exception("Couldn't get vocabulary %s.", vocabulary_name)
raise
else:
return response
def update_vocabulary(
vocabulary_name, language_code, transcribe_client, phrases=None, table_uri=None
):
"""
Updates an existing custom vocabulary. The entire vocabulary is replaced with
the contents of the update.
:param vocabulary_name: The name of the vocabulary to update.
:param language_code: The language code of the vocabulary.
:param transcribe_client: The Boto3 Transcribe client.
:param phrases: A list of comma-separated phrases to include in the vocabulary.
:param table_uri: A table of phrases and pronunciation hints to include in the
vocabulary.
"""
try:
vocab_args = {"VocabularyName": vocabulary_name, "LanguageCode": language_code}
if phrases is not None:
vocab_args["Phrases"] = phrases
elif table_uri is not None:
vocab_args["VocabularyFileUri"] = table_uri
response = transcribe_client.update_vocabulary(**vocab_args)
logger.info("Updated custom vocabulary %s.", response["VocabularyName"])
except ClientError:
logger.exception("Couldn't update custom vocabulary %s.", vocabulary_name)
raise
def list_vocabularies(vocabulary_filter, transcribe_client):
"""
Lists the custom vocabularies created for this AWS account.
:param vocabulary_filter: The returned vocabularies must contain this string in
their names.
:param transcribe_client: The Boto3 Transcribe client.
:return: The list of retrieved vocabularies.
"""
try:
response = transcribe_client.list_vocabularies(NameContains=vocabulary_filter)
vocabs = response["Vocabularies"]
next_token = response.get("NextToken")
while next_token is not None:
response = transcribe_client.list_vocabularies(
NameContains=vocabulary_filter, NextToken=next_token
)
vocabs += response["Vocabularies"]
next_token = response.get("NextToken")
logger.info(
"Got %s vocabularies with filter %s.", len(vocabs), vocabulary_filter
)
except ClientError:
logger.exception(
"Couldn't list vocabularies with filter %s.", vocabulary_filter
)
raise
else:
return vocabs
def delete_vocabulary(vocabulary_name, transcribe_client):
"""
Deletes a custom vocabulary.
:param vocabulary_name: The name of the vocabulary to delete.
:param transcribe_client: The Boto3 Transcribe client.
"""
try:
transcribe_client.delete_vocabulary(VocabularyName=vocabulary_name)
logger.info("Deleted vocabulary %s.", vocabulary_name)
except ClientError:
logger.exception("Couldn't delete vocabulary %s.", vocabulary_name)
raise
```
ラッパー関数を呼び出して、カスタム語彙なしで音声を文字起こししてから、カスタム語彙の異なるバージョンで文字起こしを行うと、よりよい結果が取得できます。
```
def usage_demo():
"""Shows how to use the Amazon Transcribe service."""
logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
s3_resource = boto3.resource("s3")
transcribe_client = boto3.client("transcribe")
print("-" * 88)
print("Welcome to the Amazon Transcribe demo!")
print("-" * 88)
bucket_name = f"jabber-bucket-{time.time_ns()}"
print(f"Creating bucket {bucket_name}.")
bucket = s3_resource.create_bucket(
Bucket=bucket_name,
CreateBucketConfiguration={
"LocationConstraint": transcribe_client.meta.region_name
},
)
media_file_name = ".media/Jabberwocky.mp3"
media_object_key = "Jabberwocky.mp3"
print(f"Uploading media file {media_file_name}.")
bucket.upload_file(media_file_name, media_object_key)
media_uri = f"s3://{bucket.name}/{media_object_key}"
job_name_simple = f"Jabber-{time.time_ns()}"
print(f"Starting transcription job {job_name_simple}.")
start_job(
job_name_simple,
f"s3://{bucket_name}/{media_object_key}",
"mp3",
"en-US",
transcribe_client,
)
transcribe_waiter = TranscribeCompleteWaiter(transcribe_client)
transcribe_waiter.wait(job_name_simple)
job_simple = get_job(job_name_simple, transcribe_client)
transcript_simple = requests.get(
job_simple["Transcript"]["TranscriptFileUri"]
).json()
print(f"Transcript for job {transcript_simple['jobName']}:")
print(transcript_simple["results"]["transcripts"][0]["transcript"])
print("-" * 88)
print(
"Creating a custom vocabulary that lists the nonsense words to try to "
"improve the transcription."
)
vocabulary_name = f"Jabber-vocabulary-{time.time_ns()}"
create_vocabulary(
vocabulary_name,
"en-US",
transcribe_client,
phrases=[
"brillig",
"slithy",
"borogoves",
"mome",
"raths",
"Jub-Jub",
"frumious",
"manxome",
"Tumtum",
"uffish",
"whiffling",
"tulgey",
"thou",
"frabjous",
"callooh",
"callay",
"chortled",
],
)
vocabulary_ready_waiter = VocabularyReadyWaiter(transcribe_client)
vocabulary_ready_waiter.wait(vocabulary_name)
job_name_vocabulary_list = f"Jabber-vocabulary-list-{time.time_ns()}"
print(f"Starting transcription job {job_name_vocabulary_list}.")
start_job(
job_name_vocabulary_list,
media_uri,
"mp3",
"en-US",
transcribe_client,
vocabulary_name,
)
transcribe_waiter.wait(job_name_vocabulary_list)
job_vocabulary_list = get_job(job_name_vocabulary_list, transcribe_client)
transcript_vocabulary_list = requests.get(
job_vocabulary_list["Transcript"]["TranscriptFileUri"]
).json()
print(f"Transcript for job {transcript_vocabulary_list['jobName']}:")
print(transcript_vocabulary_list["results"]["transcripts"][0]["transcript"])
print("-" * 88)
print(
"Updating the custom vocabulary with table data that provides additional "
"pronunciation hints."
)
table_vocab_file = "jabber-vocabulary-table.txt"
bucket.upload_file(table_vocab_file, table_vocab_file)
update_vocabulary(
vocabulary_name,
"en-US",
transcribe_client,
table_uri=f"s3://{bucket.name}/{table_vocab_file}",
)
vocabulary_ready_waiter.wait(vocabulary_name)
job_name_vocab_table = f"Jabber-vocab-table-{time.time_ns()}"
print(f"Starting transcription job {job_name_vocab_table}.")
start_job(
job_name_vocab_table,
media_uri,
"mp3",
"en-US",
transcribe_client,
vocabulary_name=vocabulary_name,
)
transcribe_waiter.wait(job_name_vocab_table)
job_vocab_table = get_job(job_name_vocab_table, transcribe_client)
transcript_vocab_table = requests.get(
job_vocab_table["Transcript"]["TranscriptFileUri"]
).json()
print(f"Transcript for job {transcript_vocab_table['jobName']}:")
print(transcript_vocab_table["results"]["transcripts"][0]["transcript"])
print("-" * 88)
print("Getting data for jobs and vocabularies.")
jabber_jobs = list_jobs("Jabber", transcribe_client)
print(f"Found {len(jabber_jobs)} jobs:")
for job_sum in jabber_jobs:
job = get_job(job_sum["TranscriptionJobName"], transcribe_client)
print(
f"\t{job['TranscriptionJobName']}, {job['Media']['MediaFileUri']}, "
f"{job['Settings'].get('VocabularyName')}"
)
jabber_vocabs = list_vocabularies("Jabber", transcribe_client)
print(f"Found {len(jabber_vocabs)} vocabularies:")
for vocab_sum in jabber_vocabs:
vocab = get_vocabulary(vocab_sum["VocabularyName"], transcribe_client)
vocab_content = requests.get(vocab["DownloadUri"]).text
print(f"\t{vocab['VocabularyName']} contents:")
print(vocab_content)
print("-" * 88)
print("Deleting demo jobs.")
for job_name in [job_name_simple, job_name_vocabulary_list, job_name_vocab_table]:
delete_job(job_name, transcribe_client)
print("Deleting demo vocabulary.")
delete_vocabulary(vocabulary_name, transcribe_client)
print("Deleting demo bucket.")
bucket.objects.delete()
bucket.delete()
print("Thanks for watching!")
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の以下のトピックを参照してください。
+ [CreateVocabulary](https://docs.aws.amazon.com/goto/boto3/transcribe-2017-10-26/CreateVocabulary)
+ [DeleteTranscriptionJob](https://docs.aws.amazon.com/goto/boto3/transcribe-2017-10-26/DeleteTranscriptionJob)
+ [DeleteVocabulary](https://docs.aws.amazon.com/goto/boto3/transcribe-2017-10-26/DeleteVocabulary)
+ [GetTranscriptionJob](https://docs.aws.amazon.com/goto/boto3/transcribe-2017-10-26/GetTranscriptionJob)
+ [GetVocabulary](https://docs.aws.amazon.com/goto/boto3/transcribe-2017-10-26/GetVocabulary)
+ [ListVocabularies](https://docs.aws.amazon.com/goto/boto3/transcribe-2017-10-26/ListVocabularies)
+ [StartTranscriptionJob](https://docs.aws.amazon.com/goto/boto3/transcribe-2017-10-26/StartTranscriptionJob)
+ [UpdateVocabulary](https://docs.aws.amazon.com/goto/boto3/transcribe-2017-10-26/UpdateVocabulary)
### 音声の文字起こしとジョブデータを取得する
次のコード例は、以下の操作方法を示しています。
+ Amazon Transcribe で文字起こしジョブを開始します。
+ ジョブが完了するまで待ちます。
+ 書き起こしが保存されている URI を取得します。
詳細については、「[Amazon Transcribe の開始方法](https://docs.aws.amazon.com/transcribe/latest/dg/getting-started.html)」を参照してください。
**SDK for Python (Boto3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/transcribe#code-examples)での設定と実行の方法を確認してください。
```
import time
import boto3
def transcribe_file(job_name, file_uri, transcribe_client):
transcribe_client.start_transcription_job(
TranscriptionJobName=job_name,
Media={"MediaFileUri": file_uri},
MediaFormat="wav",
LanguageCode="en-US",
)
max_tries = 60
while max_tries > 0:
max_tries -= 1
job = transcribe_client.get_transcription_job(TranscriptionJobName=job_name)
job_status = job["TranscriptionJob"]["TranscriptionJobStatus"]
if job_status in ["COMPLETED", "FAILED"]:
print(f"Job {job_name} is {job_status}.")
if job_status == "COMPLETED":
print(
f"Download the transcript from\n"
f"\t{job['TranscriptionJob']['Transcript']['TranscriptFileUri']}."
)
break
else:
print(f"Waiting for {job_name}. Current status is {job_status}.")
time.sleep(10)
def main():
transcribe_client = boto3.client("transcribe")
file_uri = "s3://test-transcribe/answer2.wav"
transcribe_file("Example-job", file_uri, transcribe_client)
if __name__ == "__main__":
main()
```
+ API の詳細については、「*AWS SDK for Python (Boto3) API リファレンス*」の以下のトピックを参照してください。
+ [GetTranscriptionJob](https://docs.aws.amazon.com/goto/boto3/transcribe-2017-10-26/GetTranscriptionJob)
+ [StartTranscriptionJob](https://docs.aws.amazon.com/goto/boto3/transcribe-2017-10-26/StartTranscriptionJob)