"
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()
```
+ Para obter detalhes da API, consulte a [ExecuteQuery](https://docs.aws.amazon.com/goto/boto3/neptune-2014-10-31/ExecuteQuery)Referência da API *AWS SDK for Python (Boto3*).
### `StartDBCluster`
O código de exemplo a seguir mostra como usar `StartDBCluster`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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)
```
+ Para obter detalhes da API, consulte Referência da API [Start DBCluster](https://docs.aws.amazon.com/goto/boto3/neptune-2014-10-31/StartDBCluster) in *AWS SDK for Python (Boto3*).
### `StopDBCluster`
O código de exemplo a seguir mostra como usar `StopDBCluster`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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)
```
+ Para obter detalhes da API, consulte Referência da API [Stop DBCluster](https://docs.aws.amazon.com/goto/boto3/neptune-2014-10-31/StopDBCluster) in *AWS SDK for Python (Boto3*).
# Exemplos do Organizations usando o SDK para Python (Boto3)
Os exemplos de código a seguir mostram como realizar ações e implementar cenários comuns usando o AWS SDK para Python (Boto3) with Organizations.
*Ações* são trechos de código de programas maiores e devem ser executadas em contexto. Embora as ações mostrem como chamar perfis de serviço individuais, você pode ver as ações no contexto em seus cenários relacionados.
Cada exemplo inclui um link para o código-fonte completo, em que você pode encontrar instruções sobre como configurar e executar o código.
**Topics**
+ [Ações](#actions)
## Ações
### `AttachPolicy`
O código de exemplo a seguir mostra como usar `AttachPolicy`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [AttachPolicy](https://docs.aws.amazon.com/goto/boto3/organizations-2016-11-28/AttachPolicy)Referência da API *AWS SDK for Python (Boto3*).
### `CreatePolicy`
O código de exemplo a seguir mostra como usar `CreatePolicy`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [CreatePolicy](https://docs.aws.amazon.com/goto/boto3/organizations-2016-11-28/CreatePolicy)Referência da API *AWS SDK for Python (Boto3*).
### `DeletePolicy`
O código de exemplo a seguir mostra como usar `DeletePolicy`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DeletePolicy](https://docs.aws.amazon.com/goto/boto3/organizations-2016-11-28/DeletePolicy)Referência da API *AWS SDK for Python (Boto3*).
### `DescribePolicy`
O código de exemplo a seguir mostra como usar `DescribePolicy`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DescribePolicy](https://docs.aws.amazon.com/goto/boto3/organizations-2016-11-28/DescribePolicy)Referência da API *AWS SDK for Python (Boto3*).
### `DetachPolicy`
O código de exemplo a seguir mostra como usar `DetachPolicy`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DetachPolicy](https://docs.aws.amazon.com/goto/boto3/organizations-2016-11-28/DetachPolicy)Referência da API *AWS SDK for Python (Boto3*).
### `ListPolicies`
O código de exemplo a seguir mostra como usar `ListPolicies`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [ListPolicies](https://docs.aws.amazon.com/goto/boto3/organizations-2016-11-28/ListPolicies)Referência da API *AWS SDK for Python (Boto3*).
# Exemplos da Central de Parceiros usando o SDK para Python (Boto3)
Os exemplos de código a seguir mostram como realizar ações e implementar cenários comuns usando o AWS SDK para Python (Boto3) com o Partner Central.
*Ações* são trechos de código de programas maiores e devem ser executadas em contexto. Embora as ações mostrem como chamar perfis de serviço individuais, você pode ver as ações no contexto em seus cenários relacionados.
*Cenários* são exemplos de código que mostram como realizar tarefas específicas chamando várias funções dentro de um serviço ou combinadas com outros Serviços da AWS.
Cada exemplo inclui um link para o código-fonte completo, em que você pode encontrar instruções sobre como configurar e executar o código.
**Topics**
+ [Ações](#actions)
+ [Cenários](#scenarios)
## Ações
### `AssignOpportunity`
O código de exemplo a seguir mostra como usar `AssignOpportunity`.
**SDK para Python (Boto3)**
Reatribua uma oportunidade existente a outro usuário.
```
#!/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()
```
+ Para obter detalhes da API, consulte a [AssignOpportunity](https://docs.aws.amazon.com/goto/boto3/partnercentral-selling-2022-07-26/AssignOpportunity)Referência da API *AWS SDK for Python (Boto3*).
### `AssociateOpportunity`
O código de exemplo a seguir mostra como usar `AssociateOpportunity`.
**SDK para Python (Boto3)**
Crie uma associação formal entre uma oportunidade e várias entidades relacionadas.
```
#!/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()
```
+ Para obter detalhes da API, consulte a [AssociateOpportunity](https://docs.aws.amazon.com/goto/boto3/partnercentral-selling-2022-07-26/AssociateOpportunity)Referência da API *AWS SDK for Python (Boto3*).
### `CreateOpportunity`
O código de exemplo a seguir mostra como usar `CreateOpportunity`.
**SDK para Python (Boto3)**
Crie uma oportunidade.
```
#!/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()
```
+ Para obter detalhes da API, consulte a [CreateOpportunity](https://docs.aws.amazon.com/goto/boto3/partnercentral-selling-2022-07-26/CreateOpportunity)Referência da API *AWS SDK for Python (Boto3*).
### `DisassociateOpportunity`
O código de exemplo a seguir mostra como usar `DisassociateOpportunity`.
**SDK para Python (Boto3)**
Remova uma associação existente entre uma oportunidade e entidades relacionadas.
```
#!/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()
```
+ Para obter detalhes da API, consulte a [DisassociateOpportunity](https://docs.aws.amazon.com/goto/boto3/partnercentral-selling-2022-07-26/DisassociateOpportunity)Referência da API *AWS SDK for Python (Boto3*).
### `GetAwsOpportunitySummary`
O código de exemplo a seguir mostra como usar `GetAwsOpportunitySummary`.
**SDK para Python (Boto3)**
Recupera um resumo de uma AWS oportunidade.
```
#!/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()
```
+ Para obter detalhes da API, consulte a [GetAwsOpportunitySummary](https://docs.aws.amazon.com/goto/boto3/partnercentral-selling-2022-07-26/GetAwsOpportunitySummary)Referência da API *AWS SDK for Python (Boto3*).
### `GetEngagementInvitation`
O código de exemplo a seguir mostra como usar `GetEngagementInvitation`.
**SDK para Python (Boto3)**
Recupera os detalhes de um convite de engajamento compartilhado AWS por um parceiro.
```
#!/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()
```
+ Para obter detalhes da API, consulte a [GetEngagementInvitation](https://docs.aws.amazon.com/goto/boto3/partnercentral-selling-2022-07-26/GetEngagementInvitation)Referência da API *AWS SDK for Python (Boto3*).
### `GetOpportunity`
O código de exemplo a seguir mostra como usar `GetOpportunity`.
**SDK para Python (Boto3)**
Tenha uma oportunidade.
```
#!/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()
```
+ Para obter detalhes da API, consulte a [GetOpportunity](https://docs.aws.amazon.com/goto/boto3/partnercentral-selling-2022-07-26/GetOpportunity)Referência da API *AWS SDK for Python (Boto3*).
### `ListEngagementInvitations`
O código de exemplo a seguir mostra como usar `ListEngagementInvitations`.
**SDK para Python (Boto3)**
Recupera uma lista de convites de engajamento enviados ao parceiro.
```
#!/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()
```
+ Para obter detalhes da API, consulte a [ListEngagementInvitations](https://docs.aws.amazon.com/goto/boto3/partnercentral-selling-2022-07-26/ListEngagementInvitations)Referência da API *AWS SDK for Python (Boto3*).
### `ListOpportunities`
O código de exemplo a seguir mostra como usar `ListOpportunities`.
**SDK para Python (Boto3)**
Liste oportunidades.
```
#!/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()
```
+ Para obter detalhes da API, consulte a [ListOpportunities](https://docs.aws.amazon.com/goto/boto3/partnercentral-selling-2022-07-26/ListOpportunities)Referência da API *AWS SDK for Python (Boto3*).
### `ListSolutions`
O código de exemplo a seguir mostra como usar `ListSolutions`.
**SDK para Python (Boto3)**
Recupera uma lista de soluções de parceiros que o parceiro registrou na Central de Parceiros.
```
#!/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()
```
+ Para obter detalhes da API, consulte a [ListSolutions](https://docs.aws.amazon.com/goto/boto3/partnercentral-selling-2022-07-26/ListSolutions)Referência da API *AWS SDK for Python (Boto3*).
### `RejectEngagementInvitation`
O código de exemplo a seguir mostra como usar `RejectEngagementInvitation`.
**SDK para Python (Boto3)**
Rejeita e EngagementInvitation isso é AWS compartilhado.
```
#!/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()
```
+ Para obter detalhes da API, consulte a [RejectEngagementInvitation](https://docs.aws.amazon.com/goto/boto3/partnercentral-selling-2022-07-26/RejectEngagementInvitation)Referência da API *AWS SDK for Python (Boto3*).
### `StartEngagementByAcceptingInvitationTask`
O código de exemplo a seguir mostra como usar `StartEngagementByAcceptingInvitationTask`.
**SDK para Python (Boto3)**
Inicia o noivado aceitando um 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()
```
+ Para obter detalhes da API, consulte a [StartEngagementByAcceptingInvitationTask](https://docs.aws.amazon.com/goto/boto3/partnercentral-selling-2022-07-26/StartEngagementByAcceptingInvitationTask)Referência da API *AWS SDK for Python (Boto3*).
### `StartEngagementFromOpportunityTask`
O código de exemplo a seguir mostra como usar `StartEngagementFromOpportunityTask`.
**SDK para Python (Boto3)**
Inicia o processo de engajamento com base em uma oportunidade existente aceitando o convite de engajamento e criando uma oportunidade correspondente no sistema do parceiro.
```
#!/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()
```
+ Para obter detalhes da API, consulte a [StartEngagementFromOpportunityTask](https://docs.aws.amazon.com/goto/boto3/partnercentral-selling-2022-07-26/StartEngagementFromOpportunityTask)Referência da API *AWS SDK for Python (Boto3*).
### `UpdateOpportunity`
O código de exemplo a seguir mostra como usar `UpdateOpportunity`.
**SDK para Python (Boto3)**
Atualize uma oportunidade.
```
#!/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()
```
+ Para obter detalhes da API, consulte a [UpdateOpportunity](https://docs.aws.amazon.com/goto/boto3/partnercentral-selling-2022-07-26/UpdateOpportunity)Referência da API *AWS SDK for Python (Boto3*).
## Cenários
### Atualizar a entidade associada de uma oportunidade
O exemplo de código a seguir mostra como:
+ Desassociar uma entidade antiga.
+ Associar uma entidade nova.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/partner-central-api-sample-codes/python_preview/#code-examples).
Atualizar a entidade associada de uma oportunidade
```
#!/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()
```
+ Consulte detalhes da API nos tópicos a seguir na *Referência de API do AWS SDK para Python (Boto3)*.
+ [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)
# Exemplos do Amazon Pinpoint usando o SDK para Python (Boto3)
Os exemplos de código a seguir mostram como realizar ações e implementar cenários comuns usando o AWS SDK para Python (Boto3) com o Amazon Pinpoint.
*Ações* são trechos de código de programas maiores e devem ser executadas em contexto. Embora as ações mostrem como chamar perfis de serviço individuais, você pode ver as ações no contexto em seus cenários relacionados.
Cada exemplo inclui um link para o código-fonte completo, em que você pode encontrar instruções sobre como configurar e executar o código.
**Topics**
+ [Ações](#actions)
## Ações
### `SendMessages`
O código de exemplo a seguir mostra como usar `SendMessages`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/pinpoint#code-examples).
Envie uma mensagem de e-mail.
```
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()
```
Envie uma mensagem 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()
```
Enviar uma mensagem com um modelo de e-mail existente.
```
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()
```
Envie uma mensagem de texto com um modelo de SMS existente.
```
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()
```
+ Para obter detalhes da API, consulte a [SendMessages](https://docs.aws.amazon.com/goto/boto3/pinpoint-2016-12-01/SendMessages)Referência da API *AWS SDK for Python (Boto3*).
# Exemplos da API SMS and Voice do Amazon Pinpoint usando o SDK para Python (Boto3)
Os exemplos de código a seguir mostram como realizar ações e implementar cenários comuns usando o AWS SDK para Python (Boto3) Amazon Pinpoint SMS and Voice API.
*Ações* são trechos de código de programas maiores e devem ser executadas em contexto. Embora as ações mostrem como chamar perfis de serviço individuais, você pode ver as ações no contexto em seus cenários relacionados.
Cada exemplo inclui um link para o código-fonte completo, em que você pode encontrar instruções sobre como configurar e executar o código.
**Topics**
+ [Ações](#actions)
## Ações
### `SendVoiceMessage`
O código de exemplo a seguir mostra como usar `SendVoiceMessage`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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()
```
+ Para obter detalhes da API, consulte a [SendVoiceMessage](https://docs.aws.amazon.com/goto/boto3/pinpoint-sms-voice-2018-09-05/SendVoiceMessage)Referência da API *AWS SDK for Python (Boto3*).
# Exemplos do Amazon Polly usando o SDK para Python (Boto3)
Os exemplos de código a seguir mostram como realizar ações e implementar cenários comuns usando o AWS SDK para Python (Boto3) com o Amazon Polly.
*Ações* são trechos de código de programas maiores e devem ser executadas em contexto. Embora as ações mostrem como chamar perfis de serviço individuais, você pode ver as ações no contexto em seus cenários relacionados.
*Cenários* são exemplos de código que mostram como realizar tarefas específicas chamando várias funções dentro de um serviço ou combinadas com outros Serviços da AWS.
Cada exemplo inclui um link para o código-fonte completo, em que você pode encontrar instruções sobre como configurar e executar o código.
**Topics**
+ [Ações](#actions)
+ [Cenários](#scenarios)
## Ações
### `DescribeVoices`
O código de exemplo a seguir mostra como usar `DescribeVoices`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DescribeVoices](https://docs.aws.amazon.com/goto/boto3/polly-2016-06-10/DescribeVoices)Referência da API *AWS SDK for Python (Boto3*).
### `GetLexicon`
O código de exemplo a seguir mostra como usar `GetLexicon`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [GetLexicon](https://docs.aws.amazon.com/goto/boto3/polly-2016-06-10/GetLexicon)Referência da API *AWS SDK for Python (Boto3*).
### `GetSpeechSynthesisTask`
O código de exemplo a seguir mostra como usar `GetSpeechSynthesisTask`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [GetSpeechSynthesisTask](https://docs.aws.amazon.com/goto/boto3/polly-2016-06-10/GetSpeechSynthesisTask)Referência da API *AWS SDK for Python (Boto3*).
### `ListLexicons`
O código de exemplo a seguir mostra como usar `ListLexicons`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [ListLexicons](https://docs.aws.amazon.com/goto/boto3/polly-2016-06-10/ListLexicons)Referência da API *AWS SDK for Python (Boto3*).
### `PutLexicon`
O código de exemplo a seguir mostra como usar `PutLexicon`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [PutLexicon](https://docs.aws.amazon.com/goto/boto3/polly-2016-06-10/PutLexicon)Referência da API *AWS SDK for Python (Boto3*).
### `StartSpeechSynthesisTask`
O código de exemplo a seguir mostra como usar `StartSpeechSynthesisTask`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [StartSpeechSynthesisTask](https://docs.aws.amazon.com/goto/boto3/polly-2016-06-10/StartSpeechSynthesisTask)Referência da API *AWS SDK for Python (Boto3*).
### `SynthesizeSpeech`
O código de exemplo a seguir mostra como usar `SynthesizeSpeech`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [SynthesizeSpeech](https://docs.aws.amazon.com/goto/boto3/polly-2016-06-10/SynthesizeSpeech)Referência da API *AWS SDK for Python (Boto3*).
## Cenários
### Criar um aplicativo de sincronização labial
O exemplo de código a seguir mostra como criar um aplicativo de sincronização de lábios com o Amazon Polly.
**SDK para Python (Boto3).**
Mostra como usar o Amazon Polly e o Tkinter para criar um aplicativo de sincronização labial que exibe um rosto animado falando junto com a fala sintetizada pelo Amazon Polly. A sincronização labial é realizada solicitando uma lista de fonemas do Amazon Polly que correspondam à fala sintetizada.
+ Obter metadados de voz do Amazon Polly e exibi-os em um aplicativo Tkinter.
+ Obter áudio de fala sintetizado e respectivas marcas de fala de fonema do Amazon Polly.
+ Reproduzir o áudio com movimentos sincronizados da boca em um rosto animado.
+ Enviar tarefas de síntese assíncrona para textos longos e recuperar a saída de um bucket do Amazon Simple Storage Service (Amazon S3).
Para obter o código-fonte completo e instruções sobre como configurar e executar, veja o exemplo completo em [GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/polly#code-examples).
**Serviços usados neste exemplo**
+ Amazon Polly
# Exemplos do Amazon RDS usando o SDK para Python (Boto3)
Os exemplos de código a seguir mostram como realizar ações e implementar cenários comuns usando o AWS SDK para Python (Boto3) com o Amazon RDS.
As *noções básicas* são exemplos de código que mostram como realizar as operações essenciais em um serviço.
*Ações* são trechos de código de programas maiores e devem ser executadas em contexto. Embora as ações mostrem como chamar perfis de serviço individuais, você pode ver as ações no contexto em seus cenários relacionados.
*Cenários* são exemplos de código que mostram como realizar tarefas específicas chamando várias funções dentro de um serviço ou combinadas com outros Serviços da AWS.
Cada exemplo inclui um link para o código-fonte completo, em que você pode encontrar instruções sobre como configurar e executar o código.
**Topics**
+ [Conceitos básicos](#get_started)
+ [Conceitos básicos](#basics)
+ [Ações](#actions)
+ [Cenários](#scenarios)
+ [Exemplos sem servidor](#serverless_examples)
## Conceitos básicos
### Olá, Amazon RDS
O exemplo de código a seguir mostra como começar a usar o Amazon RDS.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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']}")
```
+ Para obter detalhes da API, consulte a Referência da API [Descrever DBInstances](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/DescribeDBInstances) no *AWS SDK for Python (Boto3*).
## Conceitos básicos
### Conheça os conceitos básicos
O exemplo de código a seguir mostra como:
+ Criar um grupo de parâmetros de banco de dados e definir os valores dos parâmetros.
+ Criar uma instância de banco de dados configurada para usar o grupo de parâmetros. A instância de banco de dados também contém um banco de dados.
+ Criar um snapshot da instância.
+ Exclua a instância e o grupo de parâmetros.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rds#code-examples).
Execute um cenário interativo em um prompt de comando.
```
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.")
```
Defina as funções que são chamadas pelo cenário para gerenciar as ações do 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
```
+ Para obter detalhes da API, consulte os tópicos a seguir na *Referência da API AWS SDK para Python (Boto3)*.
+ [CriarDBInstance](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/CreateDBInstance)
+ [Criar DBParameter grupo](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/CreateDBParameterGroup)
+ [CriarDBSnapshot](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/CreateDBSnapshot)
+ [ExcluirDBInstance](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/DeleteDBInstance)
+ [Excluir DBParameter grupo](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/DeleteDBParameterGroup)
+ [Descreva DBEngine as versões](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/DescribeDBEngineVersions)
+ [DescreverDBInstances](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/DescribeDBInstances)
+ [Descrever DBParameter grupos](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/DescribeDBParameterGroups)
+ [DescreverDBParameters](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/DescribeDBParameters)
+ [DescreverDBSnapshots](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/DescribeDBSnapshots)
+ [DescribeOrderableDBInstanceOpções](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/DescribeOrderableDBInstanceOptions)
+ [Modificar DBParameter grupo](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/ModifyDBParameterGroup)
## Ações
### `CreateDBInstance`
O código de exemplo a seguir mostra como usar `CreateDBInstance`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte Referência da API [Create DBInstance](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/CreateDBInstance) in *AWS SDK for Python (Boto3*).
### `CreateDBParameterGroup`
O código de exemplo a seguir mostra como usar `CreateDBParameterGroup`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte Referência da API [Create DBParameter Group](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/CreateDBParameterGroup) in *AWS SDK for Python (Boto3*).
### `CreateDBSnapshot`
O código de exemplo a seguir mostra como usar `CreateDBSnapshot`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte Referência da API [Create DBSnapshot](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/CreateDBSnapshot) in *AWS SDK for Python (Boto3*).
### `DeleteDBInstance`
O código de exemplo a seguir mostra como usar `DeleteDBInstance`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a Referência da API [Excluir DBInstance](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/DeleteDBInstance) no *AWS SDK for Python (Boto3*).
### `DeleteDBParameterGroup`
O código de exemplo a seguir mostra como usar `DeleteDBParameterGroup`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a Referência da API [Excluir DBParameter grupo](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/DeleteDBParameterGroup) no *AWS SDK for Python (Boto3*).
### `DescribeDBEngineVersions`
O código de exemplo a seguir mostra como usar `DescribeDBEngineVersions`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte [Descrição das DBEngine versões](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/DescribeDBEngineVersions) na referência da API *AWS SDK for Python (Boto3*).
### `DescribeDBInstances`
O código de exemplo a seguir mostra como usar `DescribeDBInstances`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a Referência da API [Descrever DBInstances](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/DescribeDBInstances) no *AWS SDK for Python (Boto3*).
### `DescribeDBParameterGroups`
O código de exemplo a seguir mostra como usar `DescribeDBParameterGroups`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a Referência da API [Descrever DBParameter grupos](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/DescribeDBParameterGroups) no *AWS SDK for Python (Boto3*).
### `DescribeDBParameters`
O código de exemplo a seguir mostra como usar `DescribeDBParameters`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a Referência da API [Descrever DBParameters](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/DescribeDBParameters) no *AWS SDK for Python (Boto3*).
### `DescribeDBSnapshots`
O código de exemplo a seguir mostra como usar `DescribeDBSnapshots`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a Referência da API [Descrever DBSnapshots](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/DescribeDBSnapshots) no *AWS SDK for Python (Boto3*).
### `DescribeOrderableDBInstanceOptions`
O código de exemplo a seguir mostra como usar `DescribeOrderableDBInstanceOptions`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte [DescribeOrderableDBInstanceReferência da API Opções](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/DescribeOrderableDBInstanceOptions) no *AWS SDK for Python (Boto3*).
### `ModifyDBParameterGroup`
O código de exemplo a seguir mostra como usar `ModifyDBParameterGroup`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte Referência da API [Modificar DBParameter grupo](https://docs.aws.amazon.com/goto/boto3/rds-2014-10-31/ModifyDBParameterGroup) no *AWS SDK for Python (Boto3*).
## Cenários
### Crie um rastreador de itens de trabalho do Aurora Sem Servidor
O exemplo de código a seguir mostra como criar uma aplicação Web que rastreia os itens de trabalho em um banco de dados do Amazon Aurora Sem Servidor e usa o Amazon Simple Email Service (Amazon SES) para enviar relatórios.
**SDK para Python (Boto3)**
Mostra como usar o AWS SDK para Python (Boto3) para criar um serviço REST que rastreia itens de trabalho em um banco de dados Amazon Aurora Serverless e envia relatórios por e-mail usando o Amazon Simple Email Service (Amazon SES). Este exemplo usa a estrutura web Flask para lidar com o roteamento HTTP e se integra a uma página da Web do React para apresentar uma aplicação Web totalmente funcional.
+ Crie um serviço Flask REST que se integre com o. Serviços da AWS
+ Leia, grave e atualize itens de trabalho armazenados em um banco de dados do Aurora Sem Servidor.
+ Crie um AWS Secrets Manager segredo que contenha as credenciais do banco de dados e use-o para autenticar chamadas para o banco de dados.
+ Use o Amazon SES para enviar relatórios por e-mail de itens de trabalho.
Para obter o código-fonte completo e instruções sobre como configurar e executar, veja o exemplo completo em [GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/aurora_item_tracker).
**Serviços usados neste exemplo**
+ Aurora
+ Amazon RDS
+ Serviços de dados do Amazon RDS
+ Amazon SES
## Exemplos sem servidor
### Como se conectar a um banco de dados do Amazon RDS em uma função do Lambda
O exemplo de código a seguir mostra como implementar uma função do Lambda que se conecte a um banco de dados do RDS. A função faz uma solicitação simples ao banco de dados e exibe o resultado.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no repositório dos [Exemplos sem servidor](https://github.com/aws-samples/serverless-snippets/tree/main/lambda-function-connect-rds-iam).
Conectar-se a um banco de dados do Amazon RDS em uma função do Lambda usando Python.
```
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
```
# Exemplos do Amazon RDS Data Service usando o SDK para Python (Boto3)
Os exemplos de código a seguir mostram como realizar ações e implementar cenários comuns usando o AWS SDK para Python (Boto3) Amazon RDS Data Service.
*Cenários* são exemplos de código que mostram como realizar tarefas específicas chamando várias funções dentro de um serviço ou combinadas com outros Serviços da AWS.
Cada exemplo inclui um link para o código-fonte completo, em que você pode encontrar instruções sobre como configurar e executar o código.
**Topics**
+ [Cenários](#scenarios)
## Cenários
### Crie um rastreador de itens de trabalho do Aurora Sem Servidor
O exemplo de código a seguir mostra como criar uma aplicação Web que rastreia os itens de trabalho em um banco de dados do Amazon Aurora Sem Servidor e usa o Amazon Simple Email Service (Amazon SES) para enviar relatórios.
**SDK para Python (Boto3)**
Mostra como usar o AWS SDK para Python (Boto3) para criar um serviço REST que rastreia itens de trabalho em um banco de dados Amazon Aurora Serverless e envia relatórios por e-mail usando o Amazon Simple Email Service (Amazon SES). Este exemplo usa a estrutura web Flask para lidar com o roteamento HTTP e se integra a uma página da Web do React para apresentar uma aplicação Web totalmente funcional.
+ Crie um serviço Flask REST que se integre com o. Serviços da AWS
+ Leia, grave e atualize itens de trabalho armazenados em um banco de dados do Aurora Sem Servidor.
+ Crie um AWS Secrets Manager segredo que contenha as credenciais do banco de dados e use-o para autenticar chamadas para o banco de dados.
+ Use o Amazon SES para enviar relatórios por e-mail de itens de trabalho.
Para obter o código-fonte completo e instruções sobre como configurar e executar, veja o exemplo completo em [GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/aurora_item_tracker).
**Serviços usados neste exemplo**
+ Aurora
+ Amazon RDS
+ Serviços de dados do Amazon RDS
+ Amazon SES
# Exemplos do Amazon Redshift usando o SDK para Python (Boto3)
Os exemplos de código a seguir mostram como realizar ações e implementar cenários comuns usando o AWS SDK para Python (Boto3) com o Amazon Redshift.
As *noções básicas* são exemplos de código que mostram como realizar as operações essenciais em um serviço.
*Ações* são trechos de código de programas maiores e devem ser executadas em contexto. Embora as ações mostrem como chamar perfis de serviço individuais, você pode ver as ações no contexto em seus cenários relacionados.
Cada exemplo inclui um link para o código-fonte completo, em que você pode encontrar instruções sobre como configurar e executar o código.
**Topics**
+ [Conceitos básicos](#get_started)
+ [Conceitos básicos](#basics)
+ [Ações](#actions)
## Conceitos básicos
### Olá, Amazon Redshift
O exemplo de código a seguir mostra como começar a usar o Amazon Redshift.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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"))
```
+ Para obter detalhes da API, consulte a [DescribeClusters](https://docs.aws.amazon.com/goto/boto3/redshift-2012-12-01/DescribeClusters)Referência da API *AWS SDK for Python (Boto3*).
## Conceitos básicos
### Conheça os conceitos básicos
O exemplo de código a seguir mostra como:
+ Criar um cluster do Redshift.
+ Listar bancos de dados no cluster.
+ Criar uma tabela chamada Filmes.
+ Preencher a tabela Filmes.
+ Consultar a tabela Filmes por ano.
+ Modificar o cluster do Redshift.
+ Excluir o cluster do Amazon Redshift.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
Função principal mostrando a implementação do cenário.
```
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"
)
```
As funções wrapper usadas no cenário.
```
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
```
+ Para ver detalhes da API, consulte os tópicos a seguir em *AWS SDK for Python (Boto3) API Reference*.
+ [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)
## Ações
### `CreateCluster`
O código de exemplo a seguir mostra como usar `CreateCluster`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
O código a seguir instancia o RedshiftWrapper objeto.
```
client = boto3.client("redshift")
redhift_wrapper = RedshiftWrapper(client)
```
+ Para obter detalhes da API, consulte a [CreateCluster](https://docs.aws.amazon.com/goto/boto3/redshift-2012-12-01/CreateCluster)Referência da API *AWS SDK for Python (Boto3*).
### `DeleteCluster`
O código de exemplo a seguir mostra como usar `DeleteCluster`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
O código a seguir instancia o RedshiftWrapper objeto.
```
client = boto3.client("redshift")
redhift_wrapper = RedshiftWrapper(client)
```
+ Para obter detalhes da API, consulte a [DeleteCluster](https://docs.aws.amazon.com/goto/boto3/redshift-2012-12-01/DeleteCluster)Referência da API *AWS SDK for Python (Boto3*).
### `DescribeClusters`
O código de exemplo a seguir mostra como usar `DescribeClusters`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
O código a seguir instancia o RedshiftWrapper objeto.
```
client = boto3.client("redshift")
redhift_wrapper = RedshiftWrapper(client)
```
+ Para obter detalhes da API, consulte a [DescribeClusters](https://docs.aws.amazon.com/goto/boto3/redshift-2012-12-01/DescribeClusters)Referência da API *AWS SDK for Python (Boto3*).
### `DescribeStatement`
O código de exemplo a seguir mostra como usar `DescribeStatement`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
O código a seguir instancia o RedshiftDataWrapper objeto.
```
client = boto3.client("redshift-data")
redshift_data_wrapper = RedshiftDataWrapper(client)
```
+ Para obter detalhes da API, consulte a [DescribeStatement](https://docs.aws.amazon.com/goto/boto3/redshift-2012-12-01/DescribeStatement)Referência da API *AWS SDK for Python (Boto3*).
### `GetStatementResult`
O código de exemplo a seguir mostra como usar `GetStatementResult`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
O código a seguir instancia o RedshiftDataWrapper objeto.
```
client = boto3.client("redshift-data")
redshift_data_wrapper = RedshiftDataWrapper(client)
```
+ Para obter detalhes da API, consulte a [GetStatementResult](https://docs.aws.amazon.com/goto/boto3/redshift-2012-12-01/GetStatementResult)Referência da API *AWS SDK for Python (Boto3*).
### `ModifyCluster`
O código de exemplo a seguir mostra como usar `ModifyCluster`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
O código a seguir instancia o RedshiftWrapper objeto.
```
client = boto3.client("redshift")
redhift_wrapper = RedshiftWrapper(client)
```
+ Para obter detalhes da API, consulte a [ModifyCluster](https://docs.aws.amazon.com/goto/boto3/redshift-2012-12-01/ModifyCluster)Referência da API *AWS SDK for Python (Boto3*).
# Exemplos do Amazon Rekognition usando o SDK para Python (Boto3)
Os exemplos de código a seguir mostram como realizar ações e implementar cenários comuns usando o AWS SDK para Python (Boto3) com o Amazon Rekognition.
*Ações* são trechos de código de programas maiores e devem ser executadas em contexto. Embora as ações mostrem como chamar perfis de serviço individuais, você pode ver as ações no contexto em seus cenários relacionados.
*Cenários* são exemplos de código que mostram como realizar tarefas específicas chamando várias funções dentro de um serviço ou combinadas com outros Serviços da AWS.
Cada exemplo inclui um link para o código-fonte completo, em que você pode encontrar instruções sobre como configurar e executar o código.
**Topics**
+ [Ações](#actions)
+ [Cenários](#scenarios)
## Ações
### `CompareFaces`
O código de exemplo a seguir mostra como usar `CompareFaces`.
Para obter mais informações, consulte [Comparação de faces em imagens](https://docs.aws.amazon.com/rekognition/latest/dg/faces-comparefaces.html).
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [CompareFaces](https://docs.aws.amazon.com/goto/boto3/rekognition-2016-06-27/CompareFaces)Referência da API *AWS SDK for Python (Boto3*).
### `CreateCollection`
O código de exemplo a seguir mostra como usar `CreateCollection`.
Para obter mais informações, consulte [Criar uma coleção](https://docs.aws.amazon.com/rekognition/latest/dg/create-collection-procedure.html).
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [CreateCollection](https://docs.aws.amazon.com/goto/boto3/rekognition-2016-06-27/CreateCollection)Referência da API *AWS SDK for Python (Boto3*).
### `DeleteCollection`
O código de exemplo a seguir mostra como usar `DeleteCollection`.
Para obter mais informações, consulte [Excluir uma coleção](https://docs.aws.amazon.com/rekognition/latest/dg/delete-collection-procedure.html).
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DeleteCollection](https://docs.aws.amazon.com/goto/boto3/rekognition-2016-06-27/DeleteCollection)Referência da API *AWS SDK for Python (Boto3*).
### `DeleteFaces`
O código de exemplo a seguir mostra como usar `DeleteFaces`.
Para obter mais informações, consulte [Excluir faces de uma coleção](https://docs.aws.amazon.com/rekognition/latest/dg/delete-faces-procedure.html).
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DeleteFaces](https://docs.aws.amazon.com/goto/boto3/rekognition-2016-06-27/DeleteFaces)Referência da API *AWS SDK for Python (Boto3*).
### `DescribeCollection`
O código de exemplo a seguir mostra como usar `DescribeCollection`.
Para obter mais informações, consulte [Descrever uma coleção](https://docs.aws.amazon.com/rekognition/latest/dg/describe-collection-procedure.html).
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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()
```
+ Para obter detalhes da API, consulte a [DescribeCollection](https://docs.aws.amazon.com/goto/boto3/rekognition-2016-06-27/DescribeCollection)Referência da API *AWS SDK for Python (Boto3*).
### `DetectFaces`
O código de exemplo a seguir mostra como usar `DetectFaces`.
Para obter mais informações, consulte [Detectar faces em uma imagem](https://docs.aws.amazon.com/rekognition/latest/dg/faces-detect-images.html).
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DetectFaces](https://docs.aws.amazon.com/goto/boto3/rekognition-2016-06-27/DetectFaces)Referência da API *AWS SDK for Python (Boto3*).
### `DetectLabels`
O código de exemplo a seguir mostra como usar `DetectLabels`.
Para obter mais informações, consulte [Detectar rótulos em uma imagem](https://docs.aws.amazon.com/rekognition/latest/dg/labels-detect-labels-image.html).
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DetectLabels](https://docs.aws.amazon.com/goto/boto3/rekognition-2016-06-27/DetectLabels)Referência da API *AWS SDK for Python (Boto3*).
### `DetectModerationLabels`
O código de exemplo a seguir mostra como usar `DetectModerationLabels`.
Para obter mais informações, consulte [Detectar imagens impróprias](https://docs.aws.amazon.com/rekognition/latest/dg/procedure-moderate-images.html).
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DetectModerationLabels](https://docs.aws.amazon.com/goto/boto3/rekognition-2016-06-27/DetectModerationLabels)Referência da API *AWS SDK for Python (Boto3*).
### `DetectText`
O código de exemplo a seguir mostra como usar `DetectText`.
Para obter mais informações, consulte [Detectar texto em uma imagem](https://docs.aws.amazon.com/rekognition/latest/dg/text-detecting-text-procedure.html).
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DetectText](https://docs.aws.amazon.com/goto/boto3/rekognition-2016-06-27/DetectText)Referência da API *AWS SDK for Python (Boto3*).
### `IndexFaces`
O código de exemplo a seguir mostra como usar `IndexFaces`.
Para obter mais informações, consulte [Adicionar faces a uma coleção](https://docs.aws.amazon.com/rekognition/latest/dg/add-faces-to-collection-procedure.html).
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [IndexFaces](https://docs.aws.amazon.com/goto/boto3/rekognition-2016-06-27/IndexFaces)Referência da API *AWS SDK for Python (Boto3*).
### `ListCollections`
O código de exemplo a seguir mostra como usar `ListCollections`.
Para obter mais informações, consulte [Listar coleções](https://docs.aws.amazon.com/rekognition/latest/dg/list-collection-procedure.html).
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [ListCollections](https://docs.aws.amazon.com/goto/boto3/rekognition-2016-06-27/ListCollections)Referência da API *AWS SDK for Python (Boto3*).
### `ListFaces`
O código de exemplo a seguir mostra como usar `ListFaces`.
Para obter mais informações, consulte [Listar faces em uma coleção](https://docs.aws.amazon.com/rekognition/latest/dg/list-faces-in-collection-procedure.html).
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [ListFaces](https://docs.aws.amazon.com/goto/boto3/rekognition-2016-06-27/ListFaces)Referência da API *AWS SDK for Python (Boto3*).
### `RecognizeCelebrities`
O código de exemplo a seguir mostra como usar `RecognizeCelebrities`.
Para obter mais informações, consulte [Reconhecer celebridades em uma imagem](https://docs.aws.amazon.com/rekognition/latest/dg/celebrities-procedure-image.html).
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [RecognizeCelebrities](https://docs.aws.amazon.com/goto/boto3/rekognition-2016-06-27/RecognizeCelebrities)Referência da API *AWS SDK for Python (Boto3*).
### `SearchFaces`
O código de exemplo a seguir mostra como usar `SearchFaces`.
Para obter mais informações, consulte [Pesquisar uma face (face ID)](https://docs.aws.amazon.com/rekognition/latest/dg/search-face-with-id-procedure.html).
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [SearchFaces](https://docs.aws.amazon.com/goto/boto3/rekognition-2016-06-27/SearchFaces)Referência da API *AWS SDK for Python (Boto3*).
### `SearchFacesByImage`
O código de exemplo a seguir mostra como usar `SearchFacesByImage`.
Para obter mais informações, consulte [Pesquisar uma face (imagem)](https://docs.aws.amazon.com/rekognition/latest/dg/search-face-with-image-procedure.html).
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [SearchFacesByImage](https://docs.aws.amazon.com/goto/boto3/rekognition-2016-06-27/SearchFacesByImage)Referência da API *AWS SDK for Python (Boto3*).
## Cenários
### Criar uma coleção e encontrar faces nela
O exemplo de código a seguir mostra como:
+ Criar uma coleção do Amazon Rekognition.
+ Adicionar imagens à coleção e detectar faces nela.
+ Pesquisar na coleção faces que correspondam a uma imagem de referência.
+ Excluir uma coleção.
Para obter mais informações, consulte [Pesquisar faces em uma coleção](https://docs.aws.amazon.com/rekognition/latest/dg/collections.html).
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rekognition#code-examples).
Criar classes que envolvam as funções do 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
```
Use as classes wrapper para criar uma coleção de faces a partir de um conjunto de imagens e, em seguida, pesquisar faces na coleção.
```
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)
```
### Detectar e exibir elementos em imagens
O exemplo de código a seguir mostra como:
+ Detectar elementos em imagens usando o Amazon Rekognition.
+ Exibir imagens e desenhar caixas delimitadoras ao redor dos elementos detectados.
Para obter mais informações, consulte [Exibir caixas delimitadoras](https://docs.aws.amazon.com/rekognition/latest/dg/images-displaying-bounding-boxes.html).
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rekognition#code-examples).
Criar classes para agrupar as funções do 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
```
Criar funções auxiliares para desenhar caixas delimitadoras e polígonos.
```
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()
```
Criar classes para analisar objetos retornados pelo 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
```
Use as classes wrapper para detectar elementos em imagens e exibir suas caixas delimitadoras. As imagens usadas neste exemplo podem ser encontradas GitHub junto com instruções e mais códigos.
```
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)
```
### Detectar objetos em imagens
O exemplo de código a seguir mostra como construir uma aplicação que usa o Amazon Rekognition para detectar objetos por categoria em imagens.
**SDK para Python (Boto3)**
Mostra como usar o AWS SDK para Python (Boto3) para criar um aplicativo web que permite fazer o seguinte:
+ Carregar fotos em um bucket do Amazon Simple Storage Service (Amazon S3).
+ Usar o Amazon Rekognition para analisar e rotular as fotos.
+ Usar o Amazon Simple Email Service (Amazon SES) para enviar relatórios de análise da imagem por e-mail.
Este exemplo contém dois componentes principais: uma página da Web criada com React e um serviço REST escrito em Python que é construído com Flask-. JavaScript RESTful
Você pode usar a página da Web do React para:
+ Exibir uma lista de imagens que estão armazenadas no bucket do S3.
+ Carregar imagens do computador para o bucket do S3.
+ Exibir imagens e rótulos que identificam os itens detectados na imagem.
+ Obter um relatório de todas as imagens no bucket do S3 e enviar um relatório por e-mail.
A página da Web chama o serviço REST. O serviço envia solicitações à AWS para realizar as seguintes ações:
+ Obter e filtrar a lista de imagens no bucket do S3.
+ Carregar fotos no bucket do S3.
+ Usar o Amazon Rekognition para analisar fotos individuais e obter uma lista dos rótulos que identifiquem os itens detectados nas fotos.
+ Analisar todas as fotos no bucket do S3 e usar o Amazon SES para enviar um relatório por e-mail.
Para obter o código-fonte completo e instruções sobre como configurar e executar, veja o exemplo completo em [GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/photo_analyzer).
**Serviços usados neste exemplo**
+ Amazon Rekognition
+ Amazon S3
+ Amazon SES
### Detectar pessoas e objetos em um vídeo
O exemplo de código a seguir mostra como detectar pessoas e objetos em um vídeo com o Amazon Rekognition.
**SDK para Python (Boto3)**
Use o Amazon Rekognition para detectar faces, objetos e pessoas em vídeos iniciando trabalhos de detecção assíncrona. Este exemplo também configura o Amazon Rekognition para notificar um tópico do Amazon Simple Notification Service (Amazon SNS) quando os trabalhos são concluídos e inscreve uma fila do Amazon Simple Queue Service (Amazon SQS) no tópico. Quando a fila recebe uma mensagem sobre um trabalho, o trabalho é recuperado e os resultados são apresentados.
Este exemplo é melhor visualizado em GitHub. Para obter o código-fonte completo e instruções sobre como configurar e executar, veja o exemplo completo em [GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rekognition).
**Serviços usados neste exemplo**
+ Amazon Rekognition
+ Amazon S3
+ Amazon SES
+ Amazon SNS
+ Amazon SQS
# Exemplos do Amazon S3 usando o SDK para Python (Boto3)
Os exemplos de código a seguir mostram como realizar ações e implementar cenários comuns usando o AWS SDK para Python (Boto3) com o Amazon S3.
As *noções básicas* são exemplos de código que mostram como realizar as operações essenciais em um serviço.
*Ações* são trechos de código de programas maiores e devem ser executadas em contexto. Embora as ações mostrem como chamar perfis de serviço individuais, você pode ver as ações no contexto em seus cenários relacionados.
*Cenários* são exemplos de código que mostram como realizar tarefas específicas chamando várias funções dentro de um serviço ou combinadas com outros Serviços da AWS.
Cada exemplo inclui um link para o código-fonte completo, em que você pode encontrar instruções sobre como configurar e executar o código.
**Topics**
+ [Conceitos básicos](#get_started)
+ [Conceitos básicos](#basics)
+ [Ações](#actions)
+ [Cenários](#scenarios)
+ [Exemplos sem servidor](#serverless_examples)
## Conceitos básicos
### Olá, Amazon S3
O exemplo de código a seguir mostra como começar a usar o Amazon S3.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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()
```
+ Para obter detalhes da API, consulte a [ListBuckets](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/ListBuckets)Referência da API *AWS SDK for Python (Boto3*).
## Conceitos básicos
### Conheça os conceitos básicos
O exemplo de código a seguir mostra como:
+ Criar um bucket e fazer upload de um arquivo para ele.
+ Baixar um objeto de um bucket.
+ Copiar um objeto em uma subpasta em um bucket.
+ Listar os objetos em um bucket.
+ Exclua os objetos do bucket e o bucket.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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"))
```
+ Para obter detalhes da API, consulte os tópicos a seguir na *Referência da API AWS SDK para Python (Boto3)*.
+ [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)
## Ações
### `CopyObject`
O código de exemplo a seguir mostra como usar `CopyObject`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
Copie um objeto usando uma solicitação condicional.
```
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
```
+ Para obter detalhes da API, consulte a [CopyObject](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/CopyObject)Referência da API *AWS SDK for Python (Boto3*).
### `CreateBucket`
O código de exemplo a seguir mostra como usar `CreateBucket`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/s3_basics#code-examples).
Crie um bucket com as configurações padrão.
```
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
```
Crie um bucket versionado com uma configuração de ciclo de vida.
```
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
```
+ Para obter detalhes da API, consulte a [CreateBucket](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/CreateBucket)Referência da API *AWS SDK for Python (Boto3*).
### `DeleteBucket`
O código de exemplo a seguir mostra como usar `DeleteBucket`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DeleteBucket](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/DeleteBucket)Referência da API *AWS SDK for Python (Boto3*).
### `DeleteBucketCors`
O código de exemplo a seguir mostra como usar `DeleteBucketCors`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DeleteBucketCors](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/DeleteBucketCors)Referência da API *AWS SDK for Python (Boto3*).
### `DeleteBucketLifecycle`
O código de exemplo a seguir mostra como usar `DeleteBucketLifecycle`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DeleteBucketLifecycle](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/DeleteBucketLifecycle)Referência da API *AWS SDK for Python (Boto3*).
### `DeleteBucketPolicy`
O código de exemplo a seguir mostra como usar `DeleteBucketPolicy`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DeleteBucketPolicy](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/DeleteBucketPolicy)Referência da API *AWS SDK for Python (Boto3*).
### `DeleteObject`
O código de exemplo a seguir mostra como usar `DeleteObject`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/s3_basics#code-examples).
Exclua um objeto.
```
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
```
Reverta um objeto para uma versão anterior excluindo versões posteriores do objeto.
```
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}."
)
```
Restaure um objeto excluído removendo o marcador de exclusão ativo do objeto.
```
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)
```
Crie um manipulador do Lambda que remova um marcador de exclusão de um objeto do S3. Esse manipulador pode ser usado para limpar com eficiência marcadores de exclusão estranhos em um bucket versionado.
```
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,
}
```
+ Para obter detalhes da API, consulte a [DeleteObject](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/DeleteObject)Referência da API *AWS SDK for Python (Boto3*).
### `DeleteObjects`
O código de exemplo a seguir mostra como usar `DeleteObjects`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/s3_basics#code-examples).
Exclua um conjunto de objetos de uma lista de chaves.
```
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
```
Exclua todos os objetos em um bucket.
```
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
```
Exclua permanentemente um objeto versionado excluindo todas as suas versões.
```
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
```
+ Para obter detalhes da API, consulte a [DeleteObjects](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/DeleteObjects)Referência da API *AWS SDK for Python (Boto3*).
### `GetBucketAcl`
O código de exemplo a seguir mostra como usar `GetBucketAcl`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [GetBucketAcl](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/GetBucketAcl)Referência da API *AWS SDK for Python (Boto3*).
### `GetBucketCors`
O código de exemplo a seguir mostra como usar `GetBucketCors`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [GetBucketCors](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/GetBucketCors)Referência da API *AWS SDK for Python (Boto3*).
### `GetBucketLifecycleConfiguration`
O código de exemplo a seguir mostra como usar `GetBucketLifecycleConfiguration`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [GetBucketLifecycleConfiguration](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/GetBucketLifecycleConfiguration)Referência da API *AWS SDK for Python (Boto3*).
### `GetBucketPolicy`
O código de exemplo a seguir mostra como usar `GetBucketPolicy`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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)
```
+ Para obter detalhes da API, consulte a [GetBucketPolicy](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/GetBucketPolicy)Referência da API *AWS SDK for Python (Boto3*).
### `GetObject`
O código de exemplo a seguir mostra como usar `GetObject`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
Obtenha um objeto usando uma solicitação condicional.
```
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
```
+ Para obter detalhes da API, consulte a [GetObject](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/GetObject)Referência da API *AWS SDK for Python (Boto3*).
### `GetObjectAcl`
O código de exemplo a seguir mostra como usar `GetObjectAcl`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [GetObjectAcl](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/GetObjectAcl)Referência da API *AWS SDK for Python (Boto3*).
### `GetObjectLegalHold`
O código de exemplo a seguir mostra como usar `GetObjectLegalHold`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/scenarios/object-locking#code-examples).
Defina a retenção legal de objetos.
```
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,
)
```
+ Para obter detalhes da API, consulte a [GetObjectLegalHold](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/GetObjectLegalHold)Referência da API *AWS SDK for Python (Boto3*).
### `GetObjectLockConfiguration`
O código de exemplo a seguir mostra como usar `GetObjectLockConfiguration`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/scenarios/object-locking#code-examples).
Defina a configuração de bloqueio de objetos.
```
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
```
+ Para obter detalhes da API, consulte a [GetObjectLockConfiguration](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/GetObjectLockConfiguration)Referência da API *AWS SDK for Python (Boto3*).
### `HeadBucket`
O código de exemplo a seguir mostra como usar `HeadBucket`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [HeadBucket](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/HeadBucket)Referência da API *AWS SDK for Python (Boto3*).
### `ListBuckets`
O código de exemplo a seguir mostra como usar `ListBuckets`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [ListBuckets](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/ListBuckets)Referência da API *AWS SDK for Python (Boto3*).
### `ListObjectsV2`
O código de exemplo a seguir mostra como usar `ListObjectsV2`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte Referência da API [ListObjectsV2](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/ListObjectsV2) no *AWS SDK for Python (Boto3)*.
### `PutBucketAcl`
O código de exemplo a seguir mostra como usar `PutBucketAcl`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [PutBucketAcl](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/PutBucketAcl)Referência da API *AWS SDK for Python (Boto3*).
### `PutBucketCors`
O código de exemplo a seguir mostra como usar `PutBucketCors`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [PutBucketCors](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/PutBucketCors)Referência da API *AWS SDK for Python (Boto3*).
### `PutBucketLifecycleConfiguration`
O código de exemplo a seguir mostra como usar `PutBucketLifecycleConfiguration`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [PutBucketLifecycleConfiguration](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/PutBucketLifecycleConfiguration)Referência da API *AWS SDK for Python (Boto3*).
### `PutBucketPolicy`
O código de exemplo a seguir mostra como usar `PutBucketPolicy`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [PutBucketPolicy](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/PutBucketPolicy)Referência da API *AWS SDK for Python (Boto3*).
### `PutObject`
O código de exemplo a seguir mostra como usar `PutObject`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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()
```
Faça upload de um objeto usando uma solicitação condicional.
```
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
```
+ Para obter detalhes da API, consulte a [PutObject](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/PutObject)Referência da API *AWS SDK for Python (Boto3*).
### `PutObjectAcl`
O código de exemplo a seguir mostra como usar `PutObjectAcl`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [PutObjectAcl](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/PutObjectAcl)Referência da API *AWS SDK for Python (Boto3*).
### `PutObjectLegalHold`
O código de exemplo a seguir mostra como usar `PutObjectLegalHold`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/scenarios/object-locking#code-examples).
Defina a retenção legal de objetos.
```
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
)
```
+ Para obter detalhes da API, consulte a [PutObjectLegalHold](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/PutObjectLegalHold)Referência da API *AWS SDK for Python (Boto3*).
### `PutObjectLockConfiguration`
O código de exemplo a seguir mostra como usar `PutObjectLockConfiguration`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/scenarios/object-locking#code-examples).
Defina a configuração de bloqueio de objetos.
```
s3_client.put_object_lock_configuration(
Bucket=bucket,
ObjectLockConfiguration={"ObjectLockEnabled": "Disabled", "Rule": {}},
)
```
+ Para obter detalhes da API, consulte a [PutObjectLockConfiguration](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/PutObjectLockConfiguration)Referência da API *AWS SDK for Python (Boto3*).
### `PutObjectRetention`
O código de exemplo a seguir mostra como usar `PutObjectRetention`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/scenarios/object-locking#code-examples).
Defina uma retenção de objetos.
```
s3_client.put_object_retention(
Bucket=bucket,
Key=key,
VersionId=version_id,
Retention={"Mode": "GOVERNANCE", "RetainUntilDate": far_future_date},
BypassGovernanceRetention=True,
)
```
+ Para obter detalhes da API, consulte a [PutObjectRetention](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/PutObjectRetention)Referência da API *AWS SDK for Python (Boto3*).
## Cenários
### Criar um URL pré-assinado
O exemplo de código a seguir mostra como criar um URL pré-assinado para o Amazon S3 e fazer upload de um objeto.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/s3_basics#code-examples).
Gere um URL pré-assinado que possa realizar uma ação do S3 por tempo limitado. Use o pacote Requests para fazer uma solicitação com o 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()
```
Gere uma solicitação POST pré-assinada para carregar um arquivo.
```
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
```
### Criar uma aplicação de exploração do Amazon Textract
O exemplo de código a seguir mostra como explorar a saída do Amazon Textract por meio de uma aplicação interativa.
**SDK para Python (Boto3)**
Mostra como usar o AWS SDK para Python (Boto3) com o Amazon Textract para detectar elementos de texto, formulário e tabela em uma imagem de documento. A imagem de entrada e a saída do Amazon Textract são mostradas em um aplicativo Tkinter que permite explorar os elementos detectados.
+ Envie uma imagem de documento para o Amazon Textract e explore a saída dos elementos detectados.
+ Envie imagens diretamente para o Amazon Textract ou por meio de um bucket do Amazon Simple Storage Service (Amazon S3).
+ Use o modo assíncrono APIs para iniciar um trabalho que publica uma notificação em um tópico do Amazon Simple Notification Service (Amazon SNS) quando o trabalho for concluído.
+ Faça uma pesquisa em uma fila do Amazon Simple Queue Service (Amazon SQS) para obter uma mensagem de conclusão do trabalho e exiba os resultados.
Para obter o código-fonte completo e instruções sobre como configurar e executar, veja o exemplo completo em [GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/textract_explorer).
**Serviços usados neste exemplo**
+ Identidade do Amazon Cognito
+ Amazon S3
+ Amazon SNS
+ Amazon SQS
+ Amazon Textract
### Detectar entidades em texto extraído de uma imagem
O exemplo de código a seguir mostra como usar o Amazon Comprehend para detectar entidades em texto extraído pelo Amazon Textract de uma imagem armazenada no Amazon S3.
**SDK para Python (Boto3)**
Mostra como usar o AWS SDK para Python (Boto3) em um notebook Jupyter para detectar entidades no texto extraído de uma imagem. Este exemplo usa o Amazon Textract para extrair texto de uma imagem armazenada no Amazon Simple Storage Service (Amazon S3) e no Amazon Comprehend para detectar entidades no texto extraído.
Este exemplo é um caderno Jupyter e deve ser executado em um ambiente que possa hospedar blocos de anotações. Para obter instruções sobre como executar o exemplo usando o Amazon SageMaker AI, consulte as instruções em [TextractAndComprehendNotebook.ipynb](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/textract_comprehend_notebook/TextractAndComprehendNotebook.ipynb).
Para obter o código-fonte completo e instruções sobre como configurar e executar, veja o exemplo completo em [GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/textract_comprehend_notebook#readme).
**Serviços usados neste exemplo**
+ Amazon Comprehend
+ Amazon S3
+ Amazon Textract
### Detectar objetos em imagens
O exemplo de código a seguir mostra como construir uma aplicação que usa o Amazon Rekognition para detectar objetos por categoria em imagens.
**SDK para Python (Boto3)**
Mostra como usar o AWS SDK para Python (Boto3) para criar um aplicativo web que permite fazer o seguinte:
+ Carregar fotos em um bucket do Amazon Simple Storage Service (Amazon S3).
+ Usar o Amazon Rekognition para analisar e rotular as fotos.
+ Usar o Amazon Simple Email Service (Amazon SES) para enviar relatórios de análise da imagem por e-mail.
Este exemplo contém dois componentes principais: uma página da Web criada com React e um serviço REST escrito em Python que é construído com Flask-. JavaScript RESTful
Você pode usar a página da Web do React para:
+ Exibir uma lista de imagens que estão armazenadas no bucket do S3.
+ Carregar imagens do computador para o bucket do S3.
+ Exibir imagens e rótulos que identificam os itens detectados na imagem.
+ Obter um relatório de todas as imagens no bucket do S3 e enviar um relatório por e-mail.
A página da Web chama o serviço REST. O serviço envia solicitações à AWS para realizar as seguintes ações:
+ Obter e filtrar a lista de imagens no bucket do S3.
+ Carregar fotos no bucket do S3.
+ Usar o Amazon Rekognition para analisar fotos individuais e obter uma lista dos rótulos que identifiquem os itens detectados nas fotos.
+ Analisar todas as fotos no bucket do S3 e usar o Amazon SES para enviar um relatório por e-mail.
Para obter o código-fonte completo e instruções sobre como configurar e executar, veja o exemplo completo em [GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/photo_analyzer).
**Serviços usados neste exemplo**
+ Amazon Rekognition
+ Amazon S3
+ Amazon SES
### Detectar pessoas e objetos em um vídeo
O exemplo de código a seguir mostra como detectar pessoas e objetos em um vídeo com o Amazon Rekognition.
**SDK para Python (Boto3)**
Use o Amazon Rekognition para detectar faces, objetos e pessoas em vídeos iniciando trabalhos de detecção assíncrona. Este exemplo também configura o Amazon Rekognition para notificar um tópico do Amazon Simple Notification Service (Amazon SNS) quando os trabalhos são concluídos e inscreve uma fila do Amazon Simple Queue Service (Amazon SQS) no tópico. Quando a fila recebe uma mensagem sobre um trabalho, o trabalho é recuperado e os resultados são apresentados.
Este exemplo é melhor visualizado em GitHub. Para obter o código-fonte completo e instruções sobre como configurar e executar, veja o exemplo completo em [GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rekognition).
**Serviços usados neste exemplo**
+ Amazon Rekognition
+ Amazon S3
+ Amazon SES
+ Amazon SNS
+ Amazon SQS
### Fazer solicitações condicionais
O exemplo de código a seguir mostra como adicionar pré-condições a solicitações do Amazon S3.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/scenarios/conditional_requests#code-examples).
Execute um cenário interativo que demonstre as solicitações condicionais do 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()
```
Uma classe de wrapper que define as operações de solicitação condicional.
```
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
```
+ Para ver detalhes da API, consulte os tópicos a seguir na *Referência da API do SDK da AWS para Python (Boto3)*.
+ [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)
### Gerenciar objetos versionados em lotes com uma função do Lambda
O exemplo de código a seguir mostra como gerenciar objetos do S3 versionados em lotes com uma função do Lambda.
**SDK para Python (Boto3)**
Mostra como manipular objetos versionados do Amazon Simple Storage Service (Amazon S3) em lotes criando trabalhos que chamam funções para realizar o processamento. AWS Lambda Este exemplo cria um bucket habilitado para versão, carrega as estrofes do poema *Você é velho, padre William*, de Lewis Carroll, e usa trabalhos em lote do Amazon S3 para distorcer o poema de várias maneiras.
**Aprenda como:**
+ Criar funções do Lambda que operam em objetos versionados.
+ Criar um manifesto de objetos para atualizar.
+ Cria trabalhos em lote que invocam funções do Lambda para atualizar objetos.
+ Excluir funções do Lambda.
+ Esvaziar e excluir um bucket versionado.
Este exemplo é melhor visualizado em GitHub. Para obter o código-fonte completo e instruções sobre como configurar e executar, veja o exemplo completo em [GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/s3_versioning#batch-operation-demo).
**Serviços usados neste exemplo**
+ Amazon S3
### Fazer upload ou download de arquivos grandes
O exemplo de código a seguir mostra como fazer upload ou download de arquivos grandes de e para o Amazon S3.
Para obter mais informações, consulte [Carregar um objeto usando carregamento fracionado](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpu-upload-object.html).
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/file_transfer#code-examples).
Crie funções que transfiram arquivos usando várias configurações do gerenciador de transferências disponíveis. Use uma classe de retorno de chamada para gravar o andamento do retorno de chamada durante a transferência de arquivos.
```
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
```
Demonstre as funções do gerenciador de transferências e relate resultados.
```
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."
)
```
### Trabalhar com objetos versionados
O exemplo de código a seguir mostra como:
+ Criar um bucket do S3 versionado.
+ Obter todas as versões de um objeto.
+ Reverter um objeto para uma versão anterior.
+ Excluir e restaurar um objeto versionado.
+ Excluir, permanentemente, todas as versões de um objeto.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/s3_versioning#code-examples).
Crie funções que envolvam ações do 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
```
Carregue uma estrofe de poema para um objeto versionado e realize uma série de ações nela.
```
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!")
```
+ Para obter detalhes da API, consulte os tópicos a seguir na *Referência da API AWS SDK para Python (Boto3)*.
+ [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)
## Exemplos sem servidor
### Invocar uma função do Lambda em um acionador do Amazon S3
O exemplo de código a seguir mostra como implementar uma função do Lambda que recebe um evento acionado pelo upload de um objeto para um bucket do S3. A função recupera o nome do bucket do S3 e a chave do objeto do parâmetro de evento e chama a API do Amazon S3 para recuperar e registrar em log o tipo de conteúdo do objeto.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no repositório dos [Exemplos sem servidor](https://github.com/aws-samples/serverless-snippets/tree/main/integration-s3-to-lambda).
Consumir um evento do S3 com o Lambda usando Python.
```
# 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
```
# Exemplos de controle do Amazon S3 usando SDK para Python (Boto3)
Os exemplos de código a seguir mostram como realizar ações e implementar cenários comuns usando o controle do AWS SDK para Python (Boto3) Amazon S3.
As *noções básicas* são exemplos de código que mostram como realizar as operações essenciais em um serviço.
*Ações* são trechos de código de programas maiores e devem ser executadas em contexto. Embora as ações mostrem como chamar perfis de serviço individuais, você pode ver as ações no contexto em seus cenários relacionados.
Cada exemplo inclui um link para o código-fonte completo, em que você pode encontrar instruções sobre como configurar e executar o código.
**Topics**
+ [Conceitos básicos](#get_started)
+ [Conceitos básicos](#basics)
+ [Ações](#actions)
## Conceitos básicos
### Olá, Amazon S3 Control
O exemplo de código a seguir mostra como começar a usar o Amazon S3 Control.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [ListJobs](https://docs.aws.amazon.com/goto/boto3/s3control-2018-08-20/ListJobs)Referência da API *AWS SDK for Python (Boto3*).
## Conceitos básicos
### Conheça os conceitos básicos
O exemplo de código a seguir mostra como aprender as principais operações do Amazon S3 Control.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3/scenarios/batch#code-examples).
Conheça o cenário básico do S3 Batch.
```
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
```
+ Para ver detalhes da API, consulte os tópicos a seguir na *Referência da API do SDK da AWS para Python (Boto3)*.
+ [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)
## Ações
### `CreateJob`
O código de exemplo a seguir mostra como usar `CreateJob`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [CreateJob](https://docs.aws.amazon.com/goto/boto3/s3control-2018-08-20/CreateJob)Referência da API *AWS SDK for Python (Boto3*).
### `DeleteJobTagging`
O código de exemplo a seguir mostra como usar `DeleteJobTagging`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DeleteJobTagging](https://docs.aws.amazon.com/goto/boto3/s3control-2018-08-20/DeleteJobTagging)Referência da API *AWS SDK for Python (Boto3*).
### `DescribeJob`
O código de exemplo a seguir mostra como usar `DescribeJob`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DescribeJob](https://docs.aws.amazon.com/goto/boto3/s3control-2018-08-20/DescribeJob)Referência da API *AWS SDK for Python (Boto3*).
### `GetJobTagging`
O código de exemplo a seguir mostra como usar `GetJobTagging`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [GetJobTagging](https://docs.aws.amazon.com/goto/boto3/s3control-2018-08-20/GetJobTagging)Referência da API *AWS SDK for Python (Boto3*).
### `PutJobTagging`
O código de exemplo a seguir mostra como usar `PutJobTagging`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [PutJobTagging](https://docs.aws.amazon.com/goto/boto3/s3control-2018-08-20/PutJobTagging)Referência da API *AWS SDK for Python (Boto3*).
### `UpdateJobPriority`
O código de exemplo a seguir mostra como usar `UpdateJobPriority`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [UpdateJobPriority](https://docs.aws.amazon.com/goto/boto3/s3control-2018-08-20/UpdateJobPriority)Referência da API *AWS SDK for Python (Boto3*).
### `UpdateJobStatus`
O código de exemplo a seguir mostra como usar `UpdateJobStatus`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [UpdateJobStatus](https://docs.aws.amazon.com/goto/boto3/s3control-2018-08-20/UpdateJobStatus)Referência da API *AWS SDK for Python (Boto3*).
# Exemplos de buckets de diretório do S3 usando o SDK para Python (Boto3)
Os exemplos de código a seguir mostram como realizar ações e implementar cenários comuns usando o AWS SDK para Python (Boto3) com S3 Directory Buckets.
As *noções básicas* são exemplos de código que mostram como realizar as operações essenciais em um serviço.
*Ações* são trechos de código de programas maiores e devem ser executadas em contexto. Embora as ações mostrem como chamar perfis de serviço individuais, você pode ver as ações no contexto em seus cenários relacionados.
Cada exemplo inclui um link para o código-fonte completo, em que você pode encontrar instruções sobre como configurar e executar o código.
**Topics**
+ [Conceitos básicos](#basics)
+ [Ações](#actions)
## Conceitos básicos
### Conheça os conceitos básicos
O exemplo de código a seguir mostra como:
+ Configure uma VPC e um endpoint da VPC.
+ Configure as políticas, os perfis e o usuário para trabalhar com os buckets de diretório do S3 e a classe de armazenamento S3 Express One Zone.
+ Crie dois clientes do S3.
+ Crie dois buckets.
+ Crie um objeto e copie-o.
+ Demonstre a diferença de desempenho.
+ Preencha os buckets para mostrar a diferença lexicográfica.
+ Confirme se o usuário deseja limpar os recursos.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3-directory-buckets/#code-examples).
Execute um cenário demonstrando os conceitos básicos sobre os buckets de diretório do Amazon S3 e a classe 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"],
)
```
Uma classe de wrapper para funções de SDK do Amazon S3 Express.
```
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
```
+ Para ver detalhes da API, consulte os tópicos a seguir na *Referência da API do SDK da AWS para Python (Boto3)*.
+ [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)
## Ações
### `CreateSession`
O código de exemplo a seguir mostra como usar `CreateSession`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [CreateSession](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/CreateSession)Referência da API *AWS SDK for Python (Boto3*).
# Exemplos do Secrets Manager usando o SDK para Python (Boto3)
Os exemplos de código a seguir mostram como realizar ações e implementar cenários comuns usando o AWS SDK para Python (Boto3) with Secrets Manager.
*Ações* são trechos de código de programas maiores e devem ser executadas em contexto. Embora as ações mostrem como chamar perfis de serviço individuais, você pode ver as ações no contexto em seus cenários relacionados.
*Cenários* são exemplos de código que mostram como realizar tarefas específicas chamando várias funções dentro de um serviço ou combinadas com outros Serviços da AWS.
Cada exemplo inclui um link para o código-fonte completo, em que você pode encontrar instruções sobre como configurar e executar o código.
**Topics**
+ [Ações](#actions)
+ [Cenários](#scenarios)
## Ações
### `BatchGetSecretValue`
O código de exemplo a seguir mostra como usar `BatchGetSecretValue`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [BatchGetSecretValue](https://docs.aws.amazon.com/goto/boto3/secretsmanager-2017-10-17/BatchGetSecretValue)Referência da API *AWS SDK for Python (Boto3*).
### `GetSecretValue`
O código de exemplo a seguir mostra como usar `GetSecretValue`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [GetSecretValue](https://docs.aws.amazon.com/goto/boto3/secretsmanager-2017-10-17/GetSecretValue)Referência da API *AWS SDK for Python (Boto3*).
## Cenários
### Criar uma API REST de biblioteca de empréstimos
O exemplo de código abaixo mostra como criar uma biblioteca de empréstimos na qual os clientes possam pegar e devolver livros emprestados usando uma API REST com suporte por um banco de dados do Amazon Aurora.
**SDK para Python (Boto3)**
Mostra como usar o AWS SDK para Python (Boto3) com a API do Amazon Relational Database Service (Amazon RDS) e o AWS Chalice para criar uma API REST apoiada por um banco de dados Amazon Aurora. O serviço da Web é uma tecnologia sem servidor e representa uma biblioteca de empréstimos simples, na qual os clientes podem pegar e devolver livros emprestados. Aprenda como:
+ Crie e gerencie um cluster de banco de dados Aurora com tecnologia sem servidor.
+ Use AWS Secrets Manager para gerenciar as credenciais do banco de dados.
+ Implemente uma camada de armazenamento de dados que use o Amazon RDS para mover dados para dentro e fora do banco de dados.
+ Use o AWS Chalice para implantar uma API REST sem servidor no Amazon API Gateway e. AWS Lambda
+ Use o pacote Requests para enviar solicitações ao serviço Web.
Para obter o código-fonte completo e instruções sobre como configurar e executar, veja o exemplo completo em [GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/aurora_rest_lending_library).
**Serviços usados neste exemplo**
+ API Gateway
+ Aurora
+ Lambda
+ Secrets Manager
# Exemplos do Amazon SES usando o SDK para Python (Boto3)
Os exemplos de código a seguir mostram como realizar ações e implementar cenários comuns usando o AWS SDK para Python (Boto3) com o Amazon SES.
*Ações* são trechos de código de programas maiores e devem ser executadas em contexto. Embora as ações mostrem como chamar perfis de serviço individuais, você pode ver as ações no contexto em seus cenários relacionados.
*Cenários* são exemplos de código que mostram como realizar tarefas específicas chamando várias funções dentro de um serviço ou combinadas com outros Serviços da AWS.
Cada exemplo inclui um link para o código-fonte completo, em que você pode encontrar instruções sobre como configurar e executar o código.
**Topics**
+ [Ações](#actions)
+ [Cenários](#scenarios)
## Ações
### `CreateReceiptFilter`
O código de exemplo a seguir mostra como usar `CreateReceiptFilter`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [CreateReceiptFilter](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/CreateReceiptFilter)Referência da API *AWS SDK for Python (Boto3*).
### `CreateReceiptRule`
O código de exemplo a seguir mostra como usar `CreateReceiptRule`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ses#code-examples).
Crie um bucket do Amazon S3 no qual o Amazon SES possa colocar cópias de e-mails recebidos e crie uma regra que copia para o bucket os e-mails recebidos de uma lista específica de destinatários.
```
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
```
+ Para obter detalhes da API, consulte a [CreateReceiptRule](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/CreateReceiptRule)Referência da API *AWS SDK for Python (Boto3*).
### `CreateReceiptRuleSet`
O código de exemplo a seguir mostra como usar `CreateReceiptRuleSet`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [CreateReceiptRuleSet](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/CreateReceiptRuleSet)Referência da API *AWS SDK for Python (Boto3*).
### `CreateTemplate`
O código de exemplo a seguir mostra como usar `CreateTemplate`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [CreateTemplate](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/CreateTemplate)Referência da API *AWS SDK for Python (Boto3*).
### `DeleteIdentity`
O código de exemplo a seguir mostra como usar `DeleteIdentity`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DeleteIdentity](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/DeleteIdentity)Referência da API *AWS SDK for Python (Boto3*).
### `DeleteReceiptFilter`
O código de exemplo a seguir mostra como usar `DeleteReceiptFilter`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DeleteReceiptFilter](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/DeleteReceiptFilter)Referência da API *AWS SDK for Python (Boto3*).
### `DeleteReceiptRule`
O código de exemplo a seguir mostra como usar `DeleteReceiptRule`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DeleteReceiptRule](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/DeleteReceiptRule)Referência da API *AWS SDK for Python (Boto3*).
### `DeleteReceiptRuleSet`
O código de exemplo a seguir mostra como usar `DeleteReceiptRuleSet`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DeleteReceiptRuleSet](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/DeleteReceiptRuleSet)Referência da API *AWS SDK for Python (Boto3*).
### `DeleteTemplate`
O código de exemplo a seguir mostra como usar `DeleteTemplate`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DeleteTemplate](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/DeleteTemplate)Referência da API *AWS SDK for Python (Boto3*).
### `DescribeReceiptRuleSet`
O código de exemplo a seguir mostra como usar `DescribeReceiptRuleSet`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DescribeReceiptRuleSet](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/DescribeReceiptRuleSet)Referência da API *AWS SDK for Python (Boto3*).
### `GetIdentityVerificationAttributes`
O código de exemplo a seguir mostra como usar `GetIdentityVerificationAttributes`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [GetIdentityVerificationAttributes](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/GetIdentityVerificationAttributes)Referência da API *AWS SDK for Python (Boto3*).
### `GetTemplate`
O código de exemplo a seguir mostra como usar `GetTemplate`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [GetTemplate](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/GetTemplate)Referência da API *AWS SDK for Python (Boto3*).
### `ListIdentities`
O código de exemplo a seguir mostra como usar `ListIdentities`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [ListIdentities](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/ListIdentities)Referência da API *AWS SDK for Python (Boto3*).
### `ListReceiptFilters`
O código de exemplo a seguir mostra como usar `ListReceiptFilters`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [ListReceiptFilters](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/ListReceiptFilters)Referência da API *AWS SDK for Python (Boto3*).
### `ListTemplates`
O código de exemplo a seguir mostra como usar `ListTemplates`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [ListTemplates](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/ListTemplates)Referência da API *AWS SDK for Python (Boto3*).
### `SendEmail`
O código de exemplo a seguir mostra como usar `SendEmail`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [SendEmail](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/SendEmail)Referência da API *AWS SDK for Python (Boto3*).
### `SendTemplatedEmail`
O código de exemplo a seguir mostra como usar `SendTemplatedEmail`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [SendTemplatedEmail](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/SendTemplatedEmail)Referência da API *AWS SDK for Python (Boto3*).
### `UpdateTemplate`
O código de exemplo a seguir mostra como usar `UpdateTemplate`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [UpdateTemplate](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/UpdateTemplate)Referência da API *AWS SDK for Python (Boto3*).
### `VerifyDomainIdentity`
O código de exemplo a seguir mostra como usar `VerifyDomainIdentity`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [VerifyDomainIdentity](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/VerifyDomainIdentity)Referência da API *AWS SDK for Python (Boto3*).
### `VerifyEmailIdentity`
O código de exemplo a seguir mostra como usar `VerifyEmailIdentity`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [VerifyEmailIdentity](https://docs.aws.amazon.com/goto/boto3/email-2010-12-01/VerifyEmailIdentity)Referência da API *AWS SDK for Python (Boto3*).
## Cenários
### Copiar identidades de domínio e e-mail entre regiões
O exemplo de código a seguir mostra como copiar as identidades de e-mail e domínio do Amazon SES de uma AWS região para outra. Quando as identidades de domínio são gerenciadas pelo Route 53, os registros de verificação são copiados para o domínio da região de destino.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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()
```
+ Para obter detalhes da API, consulte os tópicos a seguir na *Referência da API AWS SDK para Python (Boto3)*.
+ [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)
### Criar uma aplicação Web para monitorar dados do DynamoDB
O exemplo de código a seguir mostra como criar uma aplicação Web que monitora itens de trabalho em uma tabela do Amazon DynamoDB e usa o Amazon Simple Email Service (Amazon SES) para enviar relatórios.
**SDK para Python (Boto3)**
Mostra como usar o AWS SDK para Python (Boto3) para criar um serviço REST que rastreia itens de trabalho no Amazon DynamoDB e envia relatórios por e-mail usando o Amazon Simple Email Service (Amazon SES). Este exemplo usa a estrutura web Flask para lidar com o roteamento HTTP e se integra a uma página da Web do React para apresentar uma aplicação Web totalmente funcional.
+ Crie um serviço Flask REST que se integre com o. Serviços da AWS
+ Leia, grave e atualize itens de trabalho armazenados em uma tabela do DynamoDB.
+ Use o Amazon SES para enviar relatórios por e-mail de itens de trabalho.
Para obter o código-fonte completo e instruções sobre como configurar e executar, veja o exemplo completo no [Repositório de exemplos de AWS código](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/dynamodb_item_tracker) em GitHub.
**Serviços usados neste exemplo**
+ DynamoDB
+ Amazon SES
### Crie um rastreador de itens de trabalho do Aurora Sem Servidor
O exemplo de código a seguir mostra como criar uma aplicação Web que rastreia os itens de trabalho em um banco de dados do Amazon Aurora Sem Servidor e usa o Amazon Simple Email Service (Amazon SES) para enviar relatórios.
**SDK para Python (Boto3)**
Mostra como usar o AWS SDK para Python (Boto3) para criar um serviço REST que rastreia itens de trabalho em um banco de dados Amazon Aurora Serverless e envia relatórios por e-mail usando o Amazon Simple Email Service (Amazon SES). Este exemplo usa a estrutura web Flask para lidar com o roteamento HTTP e se integra a uma página da Web do React para apresentar uma aplicação Web totalmente funcional.
+ Crie um serviço Flask REST que se integre com o. Serviços da AWS
+ Leia, grave e atualize itens de trabalho armazenados em um banco de dados do Aurora Sem Servidor.
+ Crie um AWS Secrets Manager segredo que contenha as credenciais do banco de dados e use-o para autenticar chamadas para o banco de dados.
+ Use o Amazon SES para enviar relatórios por e-mail de itens de trabalho.
Para obter o código-fonte completo e instruções sobre como configurar e executar, veja o exemplo completo em [GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/aurora_item_tracker).
**Serviços usados neste exemplo**
+ Aurora
+ Amazon RDS
+ Serviços de dados do Amazon RDS
+ Amazon SES
### Detectar objetos em imagens
O exemplo de código a seguir mostra como construir uma aplicação que usa o Amazon Rekognition para detectar objetos por categoria em imagens.
**SDK para Python (Boto3)**
Mostra como usar o AWS SDK para Python (Boto3) para criar um aplicativo web que permite fazer o seguinte:
+ Carregar fotos em um bucket do Amazon Simple Storage Service (Amazon S3).
+ Usar o Amazon Rekognition para analisar e rotular as fotos.
+ Usar o Amazon Simple Email Service (Amazon SES) para enviar relatórios de análise da imagem por e-mail.
Este exemplo contém dois componentes principais: uma página da Web criada com React e um serviço REST escrito em Python que é construído com Flask-. JavaScript RESTful
Você pode usar a página da Web do React para:
+ Exibir uma lista de imagens que estão armazenadas no bucket do S3.
+ Carregar imagens do computador para o bucket do S3.
+ Exibir imagens e rótulos que identificam os itens detectados na imagem.
+ Obter um relatório de todas as imagens no bucket do S3 e enviar um relatório por e-mail.
A página da Web chama o serviço REST. O serviço envia solicitações à AWS para realizar as seguintes ações:
+ Obter e filtrar a lista de imagens no bucket do S3.
+ Carregar fotos no bucket do S3.
+ Usar o Amazon Rekognition para analisar fotos individuais e obter uma lista dos rótulos que identifiquem os itens detectados nas fotos.
+ Analisar todas as fotos no bucket do S3 e usar o Amazon SES para enviar um relatório por e-mail.
Para obter o código-fonte completo e instruções sobre como configurar e executar, veja o exemplo completo em [GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/photo_analyzer).
**Serviços usados neste exemplo**
+ Amazon Rekognition
+ Amazon S3
+ Amazon SES
### Detectar pessoas e objetos em um vídeo
O exemplo de código a seguir mostra como detectar pessoas e objetos em um vídeo com o Amazon Rekognition.
**SDK para Python (Boto3)**
Use o Amazon Rekognition para detectar faces, objetos e pessoas em vídeos iniciando trabalhos de detecção assíncrona. Este exemplo também configura o Amazon Rekognition para notificar um tópico do Amazon Simple Notification Service (Amazon SNS) quando os trabalhos são concluídos e inscreve uma fila do Amazon Simple Queue Service (Amazon SQS) no tópico. Quando a fila recebe uma mensagem sobre um trabalho, o trabalho é recuperado e os resultados são apresentados.
Este exemplo é melhor visualizado em GitHub. Para obter o código-fonte completo e instruções sobre como configurar e executar, veja o exemplo completo em [GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rekognition).
**Serviços usados neste exemplo**
+ Amazon Rekognition
+ Amazon S3
+ Amazon SES
+ Amazon SNS
+ Amazon SQS
### Gerar credenciais para estabelecer conexão com um endpoint SMTP
O exemplo de código a seguir mostra como gerar credenciais para estabelecer conexão com um endpoint SMTP do Amazon SES.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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()
```
### Verificar uma identidade de e-mail e enviar mensagens
O exemplo de código a seguir mostra como:
+ Adicionar e verificar um endereço de e-mail com o Amazon SES.
+ Enviar uma mensagem de e-mail padrão.
+ Criar um modelo e envie uma mensagem de e-mail com modelo.
+ Enviar uma mensagem usando um servidor SMTP do Amazon SES.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ses#code-examples).
Verifique um endereço de e-mail com o Amazon SES e envie mensagens.
```
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)
```
Crie funções para encapsular ações de identidade do Amazon SES.
```
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
```
Crie funções para encapsular ações com modelo do 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
```
Crie funções para encapsular ações de e-mail do Amazon SES.
```
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
```
+ Para obter detalhes da API, consulte os tópicos a seguir na *Referência da API AWS SDK para Python (Boto3)*.
+ [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)
# Exemplos da API v2 do Amazon SES usando o SDK para Python (Boto3)
Os exemplos de código a seguir mostram como realizar ações e implementar cenários comuns usando a AWS SDK para Python (Boto3) API v2 do Amazon SES.
*Ações* são trechos de código de programas maiores e devem ser executadas em contexto. Embora as ações mostrem como chamar perfis de serviço individuais, você pode ver as ações no contexto em seus cenários relacionados.
*Cenários* são exemplos de código que mostram como realizar tarefas específicas chamando várias funções dentro de um serviço ou combinadas com outros Serviços da AWS.
Cada exemplo inclui um link para o código-fonte completo, em que você pode encontrar instruções sobre como configurar e executar o código.
**Topics**
+ [Ações](#actions)
+ [Cenários](#scenarios)
## Ações
### `CreateContact`
O código de exemplo a seguir mostra como usar `CreateContact`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [CreateContact](https://docs.aws.amazon.com/goto/boto3/sesv2-2019-09-27/CreateContact)Referência da API *AWS SDK for Python (Boto3*).
### `CreateContactList`
O código de exemplo a seguir mostra como usar `CreateContactList`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [CreateContactList](https://docs.aws.amazon.com/goto/boto3/sesv2-2019-09-27/CreateContactList)Referência da API *AWS SDK for Python (Boto3*).
### `CreateEmailIdentity`
O código de exemplo a seguir mostra como usar `CreateEmailIdentity`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [CreateEmailIdentity](https://docs.aws.amazon.com/goto/boto3/sesv2-2019-09-27/CreateEmailIdentity)Referência da API *AWS SDK for Python (Boto3*).
### `CreateEmailTemplate`
O código de exemplo a seguir mostra como usar `CreateEmailTemplate`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [CreateEmailTemplate](https://docs.aws.amazon.com/goto/boto3/sesv2-2019-09-27/CreateEmailTemplate)Referência da API *AWS SDK for Python (Boto3*).
### `DeleteContactList`
O código de exemplo a seguir mostra como usar `DeleteContactList`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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)
```
+ Para obter detalhes da API, consulte a [DeleteContactList](https://docs.aws.amazon.com/goto/boto3/sesv2-2019-09-27/DeleteContactList)Referência da API *AWS SDK for Python (Boto3*).
### `DeleteEmailIdentity`
O código de exemplo a seguir mostra como usar `DeleteEmailIdentity`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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)
```
+ Para obter detalhes da API, consulte a [DeleteEmailIdentity](https://docs.aws.amazon.com/goto/boto3/sesv2-2019-09-27/DeleteEmailIdentity)Referência da API *AWS SDK for Python (Boto3*).
### `DeleteEmailTemplate`
O código de exemplo a seguir mostra como usar `DeleteEmailTemplate`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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)
```
+ Para obter detalhes da API, consulte a [DeleteEmailTemplate](https://docs.aws.amazon.com/goto/boto3/sesv2-2019-09-27/DeleteEmailTemplate)Referência da API *AWS SDK for Python (Boto3*).
### `ListContacts`
O código de exemplo a seguir mostra como usar `ListContacts`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [ListContacts](https://docs.aws.amazon.com/goto/boto3/sesv2-2019-09-27/ListContacts)Referência da API *AWS SDK for Python (Boto3*).
### `SendEmail`
O código de exemplo a seguir mostra como usar `SendEmail`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sesv2#code-examples).
Envia uma mensagem a todos os membros da lista de contatos.
```
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}'.")
```
Envia uma mensagem a todos os membros da lista de contatos usando um modelo.
```
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},
)
```
+ Para obter detalhes da API, consulte a [SendEmail](https://docs.aws.amazon.com/goto/boto3/sesv2-2019-09-27/SendEmail)Referência da API *AWS SDK for Python (Boto3*).
## Cenários
### Cenário de boletim informativo
O exemplo de código a seguir mostra como executar o cenário do boletim informativo da API v2 do Amazon SES.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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)
```
+ Para obter detalhes da API, consulte os tópicos a seguir na *Referência da API AWS SDK para Python (Boto3)*.
+ [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.simples](https://docs.aws.amazon.com/goto/boto3/sesv2-2019-09-27/SendEmail.simple)
+ [SendEmail.modelo](https://docs.aws.amazon.com/goto/boto3/sesv2-2019-09-27/SendEmail.template)
# Exemplos do Amazon SNS usando o SDK para Python (Boto3)
Os exemplos de código a seguir mostram como realizar ações e implementar cenários comuns usando o AWS SDK para Python (Boto3) com o Amazon SNS.
*Ações* são trechos de código de programas maiores e devem ser executadas em contexto. Embora as ações mostrem como chamar perfis de serviço individuais, você pode ver as ações no contexto em seus cenários relacionados.
*Cenários* são exemplos de código que mostram como realizar tarefas específicas chamando várias funções dentro de um serviço ou combinadas com outros Serviços da AWS.
Cada exemplo inclui um link para o código-fonte completo, em que você pode encontrar instruções sobre como configurar e executar o código.
**Topics**
+ [Ações](#actions)
+ [Cenários](#scenarios)
+ [Exemplos sem servidor](#serverless_examples)
## Ações
### `CreateTopic`
O código de exemplo a seguir mostra como usar `CreateTopic`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [CreateTopic](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/CreateTopic)Referência da API *AWS SDK for Python (Boto3*).
### `DeleteTopic`
O código de exemplo a seguir mostra como usar `DeleteTopic`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DeleteTopic](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/DeleteTopic)Referência da API *AWS SDK for Python (Boto3*).
### `ListSubscriptions`
O código de exemplo a seguir mostra como usar `ListSubscriptions`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [ListSubscriptions](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/ListSubscriptions)Referência da API *AWS SDK for Python (Boto3*).
### `ListTopics`
O código de exemplo a seguir mostra como usar `ListTopics`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [ListTopics](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/ListTopics)Referência da API *AWS SDK for Python (Boto3*).
### `Publish`
O código de exemplo a seguir mostra como usar `Publish`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sns#code-examples).
Publique uma mensagem com atributos para que uma assinatura possa filtrar com base em atributos.
```
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
```
Publique uma mensagem que assume diferentes formas com base no protocolo do assinante.
```
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
```
+ Consulte detalhes da API em [Publish](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/Publish) na *Referência da API AWS SDK for Python (Boto3)*.
### `SetSubscriptionAttributes`
O código de exemplo a seguir mostra como usar `SetSubscriptionAttributes`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [SetSubscriptionAttributes](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/SetSubscriptionAttributes)Referência da API *AWS SDK for Python (Boto3*).
### `Subscribe`
O código de exemplo a seguir mostra como usar `Subscribe`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sns#code-examples).
Inscrever um endereço de e-mail em um tópico.
```
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
```
Inscreva uma fila em um tópico com filtros opcionais.
```
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
```
+ Consulte detalhes da API em [Subscribe](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/Subscribe) na *Referência da API do AWS SDK for Python (Boto3)*.
### `Unsubscribe`
O código de exemplo a seguir mostra como usar `Unsubscribe`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Consulte detalhes da API em [Unsubscribe](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/Unsubscribe) na *Referência da API AWS SDK for Python (Boto3)*.
## Cenários
### Criar uma aplicação de exploração do Amazon Textract
O exemplo de código a seguir mostra como explorar a saída do Amazon Textract por meio de uma aplicação interativa.
**SDK para Python (Boto3)**
Mostra como usar o AWS SDK para Python (Boto3) com o Amazon Textract para detectar elementos de texto, formulário e tabela em uma imagem de documento. A imagem de entrada e a saída do Amazon Textract são mostradas em um aplicativo Tkinter que permite explorar os elementos detectados.
+ Envie uma imagem de documento para o Amazon Textract e explore a saída dos elementos detectados.
+ Envie imagens diretamente para o Amazon Textract ou por meio de um bucket do Amazon Simple Storage Service (Amazon S3).
+ Use o modo assíncrono APIs para iniciar um trabalho que publica uma notificação em um tópico do Amazon Simple Notification Service (Amazon SNS) quando o trabalho for concluído.
+ Faça uma pesquisa em uma fila do Amazon Simple Queue Service (Amazon SQS) para obter uma mensagem de conclusão do trabalho e exiba os resultados.
Para obter o código-fonte completo e instruções sobre como configurar e executar, veja o exemplo completo em [GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/textract_explorer).
**Serviços usados neste exemplo**
+ Identidade do Amazon Cognito
+ Amazon S3
+ Amazon SNS
+ Amazon SQS
+ Amazon Textract
### Criar e publicar em um tópico FIFO
O exemplo de código a seguir mostra como criar e publicar em um tópico FIFO do Amazon SNS.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sns#code-examples).
Crie um tópico FIFO do Amazon SNS, inscreva filas padrão e FIFO do Amazon SQS no tópico e publique uma mensagem no tópico.
```
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
```
+ Para obter detalhes da API, consulte os tópicos a seguir na *Referência da API AWS SDK para Python (Boto3)*.
+ [CreateTopic](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/CreateTopic)
+ [Publicar](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/Publish)
+ [Assinar](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/Subscribe)
### Detectar pessoas e objetos em um vídeo
O exemplo de código a seguir mostra como detectar pessoas e objetos em um vídeo com o Amazon Rekognition.
**SDK para Python (Boto3)**
Use o Amazon Rekognition para detectar faces, objetos e pessoas em vídeos iniciando trabalhos de detecção assíncrona. Este exemplo também configura o Amazon Rekognition para notificar um tópico do Amazon Simple Notification Service (Amazon SNS) quando os trabalhos são concluídos e inscreve uma fila do Amazon Simple Queue Service (Amazon SQS) no tópico. Quando a fila recebe uma mensagem sobre um trabalho, o trabalho é recuperado e os resultados são apresentados.
Este exemplo é melhor visualizado em GitHub. Para obter o código-fonte completo e instruções sobre como configurar e executar, veja o exemplo completo em [GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rekognition).
**Serviços usados neste exemplo**
+ Amazon Rekognition
+ Amazon S3
+ Amazon SES
+ Amazon SNS
+ Amazon SQS
### Publicar uma mensagem de texto SMS
O exemplo de código a seguir mostra como publicar mensagens SMS usando o Amazon SNS.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Consulte detalhes da API em [Publish](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/Publish) na *Referência da API AWS SDK for Python (Boto3)*.
### Publicar mensagens em filas
O exemplo de código a seguir mostra como:
+ Criar um tópico (FIFO ou não FIFO).
+ Assinar várias filas no tópico com a opção de aplicar um filtro.
+ Publicar mensagens no tópico.
+ Pesquise as filas para ver as mensagens recebidas.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/topics_and_queues#code-examples).
Execute um cenário interativo em um prompt de comando.
```
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.")
```
Crie classes que envolvam as operações do Amazon SNS e do Amazon SQS para uso no cenário.
```
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
```
+ Para ver detalhes da API, consulte os tópicos a seguir na *Referência da API do SDK da AWS para Python (Boto3)*.
+ [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)
+ [Publicar](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)
+ [Assinar](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/Subscribe)
+ [Cancelar assinatura](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/Unsubscribe)
### Usar o API Gateway para invocar uma função do Lambda
O exemplo de código a seguir mostra como criar uma AWS Lambda função invocada pelo Amazon API Gateway.
**SDK para Python (Boto3)**
Este exemplo mostra como criar e usar uma API REST do Amazon API Gateway cujo alvo é uma função do AWS Lambda . O manipulador do Lambda mostra como rotear com base em métodos HTTP; como obter dados da string de consulta, do cabeçalho e do corpo e como retornar uma resposta JSON.
+ Implante uma função do Lambda.
+ Crie uma API REST do API Gateway.
+ Criar um recurso REST cujo alvo seja a função do Lambda.
+ Conceda permissão para que o API Gateway possa invocar a função do Lambda.
+ Use o pacote Requests para enviar solicitações à API REST.
+ Limpe todos os recursos criados durante a demonstração.
Este exemplo é melhor visualizado em GitHub. Para obter o código-fonte completo e instruções sobre como configurar e executar, veja o exemplo completo em [GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/lambda#readme).
**Serviços usados neste exemplo**
+ API Gateway
+ DynamoDB
+ Lambda
+ Amazon SNS
### Usar eventos programados para chamar uma função do Lambda
O exemplo de código a seguir mostra como criar uma AWS Lambda função invocada por um evento EventBridge agendado pela Amazon.
**SDK para Python (Boto3)**
Este exemplo mostra como registrar uma AWS Lambda função como alvo de um EventBridge evento programado da Amazon. O manipulador do Lambda grava uma mensagem amigável e os dados completos do evento no Amazon CloudWatch Logs para recuperação posterior.
+ Implanta uma função do Lambda.
+ Cria um evento EventBridge agendado e torna a função Lambda o alvo.
+ Concede permissão para permitir a EventBridge invocação da função Lambda.
+ Imprime os dados mais recentes do CloudWatch Logs para mostrar o resultado das invocações programadas.
+ Limpa todos os recursos criados durante a demonstração.
Este exemplo é melhor visualizado em GitHub. Para obter o código-fonte completo e instruções sobre como configurar e executar, veja o exemplo completo em [GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/lambda#readme).
**Serviços usados neste exemplo**
+ CloudWatch Registros
+ DynamoDB
+ EventBridge
+ Lambda
+ Amazon SNS
## Exemplos sem servidor
### Invocar uma função do Lambda em um acionador do Amazon SNS
O exemplo de código a seguir mostra como implementar uma função do Lambda que recebe um evento acionado pelo recebimento de mensagens de um tópico do SNS. A função recupera as mensagens do parâmetro event e registra o conteúdo de cada mensagem.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no repositório dos [Exemplos sem servidor](https://github.com/aws-samples/serverless-snippets/tree/main/integration-sns-to-lambda).
Consumir um evento do SNS com o Lambda usando Python.
```
# 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
```
# Exemplos do Amazon SQS usando o SDK para Python (Boto3)
Os exemplos de código a seguir mostram como realizar ações e implementar cenários comuns usando o AWS SDK para Python (Boto3) com o Amazon SQS.
*Ações* são trechos de código de programas maiores e devem ser executadas em contexto. Embora as ações mostrem como chamar perfis de serviço individuais, você pode ver as ações no contexto em seus cenários relacionados.
*Cenários* são exemplos de código que mostram como realizar tarefas específicas chamando várias funções dentro de um serviço ou combinadas com outros Serviços da AWS.
Cada exemplo inclui um link para o código-fonte completo, em que você pode encontrar instruções sobre como configurar e executar o código.
**Topics**
+ [Ações](#actions)
+ [Cenários](#scenarios)
+ [Exemplos sem servidor](#serverless_examples)
## Ações
### `CreateQueue`
O código de exemplo a seguir mostra como usar `CreateQueue`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [CreateQueue](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/CreateQueue)Referência da API *AWS SDK for Python (Boto3*).
### `DeleteMessage`
O código de exemplo a seguir mostra como usar `DeleteMessage`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DeleteMessage](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/DeleteMessage)Referência da API *AWS SDK for Python (Boto3*).
### `DeleteMessageBatch`
O código de exemplo a seguir mostra como usar `DeleteMessageBatch`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DeleteMessageBatch](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/DeleteMessageBatch)Referência da API *AWS SDK for Python (Boto3*).
### `DeleteQueue`
O código de exemplo a seguir mostra como usar `DeleteQueue`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DeleteQueue](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/DeleteQueue)Referência da API *AWS SDK for Python (Boto3*).
### `GetQueueAttributes`
O código de exemplo a seguir mostra como usar `GetQueueAttributes`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [GetQueueAttributes](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/GetQueueAttributes)Referência da API *AWS SDK for Python (Boto3*).
### `GetQueueUrl`
O código de exemplo a seguir mostra como usar `GetQueueUrl`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [GetQueueUrl](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/GetQueueUrl)Referência da API *AWS SDK for Python (Boto3*).
### `ListQueues`
O código de exemplo a seguir mostra como usar `ListQueues`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [ListQueues](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/ListQueues)Referência da API *AWS SDK for Python (Boto3*).
### `ReceiveMessage`
O código de exemplo a seguir mostra como usar `ReceiveMessage`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [ReceiveMessage](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/ReceiveMessage)Referência da API *AWS SDK for Python (Boto3*).
### `SendMessage`
O código de exemplo a seguir mostra como usar `SendMessage`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [SendMessage](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/SendMessage)Referência da API *AWS SDK for Python (Boto3*).
### `SendMessageBatch`
O código de exemplo a seguir mostra como usar `SendMessageBatch`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [SendMessageBatch](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/SendMessageBatch)Referência da API *AWS SDK for Python (Boto3*).
### `SetQueueAttributes`
O código de exemplo a seguir mostra como usar `SetQueueAttributes`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/topics_and_queues#code-examples).
Definir o atributo de política de uma fila para um tópico.
```
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
```
+ Para obter detalhes da API, consulte a [SetQueueAttributes](https://docs.aws.amazon.com/goto/boto3/sqs-2012-11-05/SetQueueAttributes)Referência da API *AWS SDK for Python (Boto3*).
## Cenários
### Criar uma aplicação de mensageiro
O exemplo de código a seguir mostra como criar um aplicativo de AWS Step Functions mensagens que recupera registros de mensagens de uma tabela de banco de dados.
**SDK para Python (Boto3)**
Mostra como usar o AWS SDK para Python (Boto3) with AWS Step Functions para criar um aplicativo de mensagens que recupera registros de mensagens de uma tabela do Amazon DynamoDB e os envia com o Amazon Simple Queue Service (Amazon SQS). A máquina de estado se integra a uma AWS Lambda função para verificar o banco de dados em busca de mensagens não enviadas.
+ Crie uma máquina de estado que recupere e atualize registros de mensagens de uma tabela do Amazon DynamoDB.
+ Atualize a definição de máquina de estado para enviar mensagens ao Amazon Simple Queue Service (Amazon SQS).
+ Inicie e interrompa execuções da máquina de estado.
+ Conecte-se ao Lambda, ao DynamoDB e ao Amazon SQS por meio de uma máquina de estado usando integrações de serviço.
Para obter o código-fonte completo e instruções sobre como configurar e executar, veja o exemplo completo em [GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/stepfunctions_messenger).
**Serviços usados neste exemplo**
+ DynamoDB
+ Lambda
+ Amazon SQS
+ Step Functions
### Criar uma aplicação de exploração do Amazon Textract
O exemplo de código a seguir mostra como explorar a saída do Amazon Textract por meio de uma aplicação interativa.
**SDK para Python (Boto3)**
Mostra como usar o AWS SDK para Python (Boto3) com o Amazon Textract para detectar elementos de texto, formulário e tabela em uma imagem de documento. A imagem de entrada e a saída do Amazon Textract são mostradas em um aplicativo Tkinter que permite explorar os elementos detectados.
+ Envie uma imagem de documento para o Amazon Textract e explore a saída dos elementos detectados.
+ Envie imagens diretamente para o Amazon Textract ou por meio de um bucket do Amazon Simple Storage Service (Amazon S3).
+ Use o modo assíncrono APIs para iniciar um trabalho que publica uma notificação em um tópico do Amazon Simple Notification Service (Amazon SNS) quando o trabalho for concluído.
+ Faça uma pesquisa em uma fila do Amazon Simple Queue Service (Amazon SQS) para obter uma mensagem de conclusão do trabalho e exiba os resultados.
Para obter o código-fonte completo e instruções sobre como configurar e executar, veja o exemplo completo em [GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/textract_explorer).
**Serviços usados neste exemplo**
+ Identidade do Amazon Cognito
+ Amazon S3
+ Amazon SNS
+ Amazon SQS
+ Amazon Textract
### Criar e publicar em um tópico FIFO
O exemplo de código a seguir mostra como criar e publicar em um tópico FIFO do Amazon SNS.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sns#code-examples).
Crie um tópico FIFO do Amazon SNS, inscreva filas padrão e FIFO do Amazon SQS no tópico e publique uma mensagem no tópico.
```
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
```
+ Para obter detalhes da API, consulte os tópicos a seguir na *Referência da API AWS SDK para Python (Boto3)*.
+ [CreateTopic](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/CreateTopic)
+ [Publicar](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/Publish)
+ [Assinar](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/Subscribe)
### Detectar pessoas e objetos em um vídeo
O exemplo de código a seguir mostra como detectar pessoas e objetos em um vídeo com o Amazon Rekognition.
**SDK para Python (Boto3)**
Use o Amazon Rekognition para detectar faces, objetos e pessoas em vídeos iniciando trabalhos de detecção assíncrona. Este exemplo também configura o Amazon Rekognition para notificar um tópico do Amazon Simple Notification Service (Amazon SNS) quando os trabalhos são concluídos e inscreve uma fila do Amazon Simple Queue Service (Amazon SQS) no tópico. Quando a fila recebe uma mensagem sobre um trabalho, o trabalho é recuperado e os resultados são apresentados.
Este exemplo é melhor visualizado em GitHub. Para obter o código-fonte completo e instruções sobre como configurar e executar, veja o exemplo completo em [GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/rekognition).
**Serviços usados neste exemplo**
+ Amazon Rekognition
+ Amazon S3
+ Amazon SES
+ Amazon SNS
+ Amazon SQS
### Publicar mensagens em filas
O exemplo de código a seguir mostra como:
+ Criar um tópico (FIFO ou não FIFO).
+ Assinar várias filas no tópico com a opção de aplicar um filtro.
+ Publicar mensagens no tópico.
+ Pesquise as filas para ver as mensagens recebidas.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/topics_and_queues#code-examples).
Execute um cenário interativo em um prompt de comando.
```
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.")
```
Crie classes que envolvam as operações do Amazon SNS e do Amazon SQS para uso no cenário.
```
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
```
+ Para ver detalhes da API, consulte os tópicos a seguir na *Referência da API do SDK da AWS para Python (Boto3)*.
+ [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)
+ [Publicar](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)
+ [Assinar](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/Subscribe)
+ [Cancelar assinatura](https://docs.aws.amazon.com/goto/boto3/sns-2010-03-31/Unsubscribe)
### Enviar e receber lotes de mensagens
O exemplo de código a seguir mostra como:
+ Criar uma fila do Amazon SQS.
+ Enviar lotes de mensagens para a fila.
+ Receber lotes de mensagens de uma fila.
+ Excluir lotes de mensagens de uma fila.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sqs#code-examples).
Criar funções para encapsular funções de mensagem do 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
```
Use as funções de wrapper para enviar e receber mensagens em lotes.
```
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)
```
+ Para obter detalhes da API, consulte os tópicos a seguir na *Referência da API AWS SDK para Python (Boto3)*.
+ [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)
## Exemplos sem servidor
### Invocar uma função do Lambda em um trigger do Amazon SQS
O exemplo de código a seguir mostra como implementar uma função do Lambda que recebe um evento acionado pelo recebimento de mensagens de uma fila do SQS. A função recupera as mensagens do parâmetro event e registra o conteúdo de cada mensagem.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no repositório dos [Exemplos sem servidor](https://github.com/aws-samples/serverless-snippets/tree/main/integration-sqs-to-lambda).
Consumir um evento do SQS com o Lambda usando Python.
```
# 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
```
### Relatar falhas de itens em lote para funções do Lambda com um trigger do Amazon SQS
O exemplo de código a seguir mostra como implementar uma resposta parcial em lote para funções do Lambda que recebem eventos de uma fila do SQS. A função relata as falhas do item em lote na resposta, sinalizando para o Lambda tentar novamente essas mensagens posteriormente.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no repositório dos [Exemplos sem servidor](https://github.com/aws-samples/serverless-snippets/tree/main/lambda-function-sqs-report-batch-item-failures).
Relatar falhas de itens em lote do SQS com o Lambda usando Python.
```
# 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
```
# Exemplos do Step Functions usando o SDK para Python (Boto3)
Os exemplos de código a seguir mostram como realizar ações e implementar cenários comuns usando o AWS SDK para Python (Boto3) with Step Functions.
As *noções básicas* são exemplos de código que mostram como realizar as operações essenciais em um serviço.
*Ações* são trechos de código de programas maiores e devem ser executadas em contexto. Embora as ações mostrem como chamar perfis de serviço individuais, você pode ver as ações no contexto em seus cenários relacionados.
*Cenários* são exemplos de código que mostram como realizar tarefas específicas chamando várias funções dentro de um serviço ou combinadas com outros Serviços da AWS.
Cada exemplo inclui um link para o código-fonte completo, em que você pode encontrar instruções sobre como configurar e executar o código.
**Topics**
+ [Conceitos básicos](#get_started)
+ [Conceitos básicos](#basics)
+ [Ações](#actions)
+ [Cenários](#scenarios)
## Conceitos básicos
### Olá, Step Functions
O exemplo de código a seguir mostra como começar a usar o Step Functions.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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"))
```
+ Para obter detalhes da API, consulte a [ListStateMachines](https://docs.aws.amazon.com/goto/boto3/states-2016-11-23/ListStateMachines)Referência da API *AWS SDK for Python (Boto3*).
## Conceitos básicos
### Conheça os conceitos básicos
O exemplo de código a seguir mostra como:
+ Criar uma atividade.
+ Criar uma máquina de estado a partir de uma definição da Amazon States Language que contenha a atividade criada anteriormente como uma etapa.
+ Executar a máquina de estado e responder à atividade com entrada do usuário.
+ Obter o status e a saída finais após a conclusão da execução e, em seguida, limpar os recursos.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/stepfunctions#code-examples).
Execute um cenário interativo em um prompt de comando.
```
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.")
```
Defina uma classe que envolva ações de máquina de estado.
```
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
```
Defina uma classe que envolva ações de atividade.
```
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
```
+ Para obter detalhes da API, consulte os tópicos a seguir na *Referência da API AWS SDK para Python (Boto3)*.
+ [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)
## Ações
### `CreateActivity`
O código de exemplo a seguir mostra como usar `CreateActivity`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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"]
```
+ Para obter detalhes da API, consulte a [CreateActivity](https://docs.aws.amazon.com/goto/boto3/states-2016-11-23/CreateActivity)Referência da API *AWS SDK for Python (Boto3*).
### `CreateStateMachine`
O código de exemplo a seguir mostra como usar `CreateStateMachine`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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"]
```
+ Para obter detalhes da API, consulte a [CreateStateMachine](https://docs.aws.amazon.com/goto/boto3/states-2016-11-23/CreateStateMachine)Referência da API *AWS SDK for Python (Boto3*).
### `DeleteActivity`
O código de exemplo a seguir mostra como usar `DeleteActivity`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DeleteActivity](https://docs.aws.amazon.com/goto/boto3/states-2016-11-23/DeleteActivity)Referência da API *AWS SDK for Python (Boto3*).
### `DeleteStateMachine`
O código de exemplo a seguir mostra como usar `DeleteStateMachine`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DeleteStateMachine](https://docs.aws.amazon.com/goto/boto3/states-2016-11-23/DeleteStateMachine)Referência da API *AWS SDK for Python (Boto3*).
### `DescribeExecution`
O código de exemplo a seguir mostra como usar `DescribeExecution`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DescribeExecution](https://docs.aws.amazon.com/goto/boto3/states-2016-11-23/DescribeExecution)Referência da API *AWS SDK for Python (Boto3*).
### `DescribeStateMachine`
O código de exemplo a seguir mostra como usar `DescribeStateMachine`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DescribeStateMachine](https://docs.aws.amazon.com/goto/boto3/states-2016-11-23/DescribeStateMachine)Referência da API *AWS SDK for Python (Boto3*).
### `GetActivityTask`
O código de exemplo a seguir mostra como usar `GetActivityTask`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [GetActivityTask](https://docs.aws.amazon.com/goto/boto3/states-2016-11-23/GetActivityTask)Referência da API *AWS SDK for Python (Boto3*).
### `ListActivities`
O código de exemplo a seguir mostra como usar `ListActivities`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [ListActivities](https://docs.aws.amazon.com/goto/boto3/states-2016-11-23/ListActivities)Referência da API *AWS SDK for Python (Boto3*).
### `ListStateMachines`
O código de exemplo a seguir mostra como usar `ListStateMachines`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/stepfunctions#code-examples).
Encontre uma máquina de estado pelo nome pesquisando a lista de máquinas de estado da conta.
```
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
```
+ Para obter detalhes da API, consulte a [ListStateMachines](https://docs.aws.amazon.com/goto/boto3/states-2016-11-23/ListStateMachines)Referência da API *AWS SDK for Python (Boto3*).
### `SendTaskSuccess`
O código de exemplo a seguir mostra como usar `SendTaskSuccess`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [SendTaskSuccess](https://docs.aws.amazon.com/goto/boto3/states-2016-11-23/SendTaskSuccess)Referência da API *AWS SDK for Python (Boto3*).
### `StartExecution`
O código de exemplo a seguir mostra como usar `StartExecution`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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"]
```
+ Para obter detalhes da API, consulte a [StartExecution](https://docs.aws.amazon.com/goto/boto3/states-2016-11-23/StartExecution)Referência da API *AWS SDK for Python (Boto3*).
## Cenários
### Criar uma aplicação de mensageiro
O exemplo de código a seguir mostra como criar um aplicativo de AWS Step Functions mensagens que recupera registros de mensagens de uma tabela de banco de dados.
**SDK para Python (Boto3)**
Mostra como usar o AWS SDK para Python (Boto3) with AWS Step Functions para criar um aplicativo de mensagens que recupera registros de mensagens de uma tabela do Amazon DynamoDB e os envia com o Amazon Simple Queue Service (Amazon SQS). A máquina de estado se integra a uma AWS Lambda função para verificar o banco de dados em busca de mensagens não enviadas.
+ Crie uma máquina de estado que recupere e atualize registros de mensagens de uma tabela do Amazon DynamoDB.
+ Atualize a definição de máquina de estado para enviar mensagens ao Amazon Simple Queue Service (Amazon SQS).
+ Inicie e interrompa execuções da máquina de estado.
+ Conecte-se ao Lambda, ao DynamoDB e ao Amazon SQS por meio de uma máquina de estado usando integrações de serviço.
Para obter o código-fonte completo e instruções sobre como configurar e executar, veja o exemplo completo em [GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/stepfunctions_messenger).
**Serviços usados neste exemplo**
+ DynamoDB
+ Lambda
+ Amazon SQS
+ Step Functions
### Orquestrar aplicações de IA generativa com o Step Functions
O exemplo de código a seguir mostra como criar e orquestrar aplicações de IA generativa com o Amazon Bedrock e o Step Functions.
**SDK para Python (Boto3)**
O cenário de encadeamento de prompts do Amazon Bedrock Sem Servidor demonstra como o [AWS Step Functions](https://docs.aws.amazon.com/step-functions/latest/dg/welcome.html), o [Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/what-is-bedrock.html) e a documentação [https://docs.aws.amazon.com/bedrock/latest/userguide/agents.html](https://docs.aws.amazon.com/bedrock/latest/userguide/agents.html) podem ser usados para criar e orquestrar aplicações de IA generativa complexas, sem servidor e altamente escaláveis. Ele contém os seguintes exemplos de trabalho:
+ Escrever uma análise de um determinado romance para um blog de literatura. Este exemplo ilustra uma cadeia de prompts simples e sequencial.
+ Gerar uma história curta sobre um determinado tópico. Este exemplo ilustra como a IA pode processar uma lista de itens gerada anteriormente de forma iterativa.
+ Criar um itinerário para férias de fim de semana em um determinado destino. Este exemplo ilustra como paralelizar vários prompts distintos.
+ Lançar ideias de filmes para um usuário humano que atua como produtor de filmes. Este exemplo ilustra como paralelizar o mesmo prompt com diferentes parâmetros de inferência, como voltar a uma etapa anterior na cadeia e como incluir a entrada humana como parte do fluxo de trabalho.
+ Planejar uma refeição com base nos ingredientes que o usuário tem em mãos. Este exemplo ilustra como as cadeias de prompts podem incorporar duas conversas distintas de IA, com duas personas de IA participando de um debate entre si para melhorar o resultado final.
+ Encontre e resuma o repositório mais popular GitHub da atualidade. Este exemplo ilustra o encadeamento de vários agentes de IA que interagem com agentes externos. APIs
Para obter o código-fonte completo e as instruções de configuração e execução, consulte o projeto completo em [GitHub](https://github.com/aws-samples/amazon-bedrock-serverless-prompt-chaining).
**Serviços usados neste exemplo**
+ Amazon Bedrock
+ Amazon Bedrock Runtime
+ Amazon Bedrock Agents
+ Amazon Bedrock Agents Runtime
+ Step Functions
# AWS STS exemplos usando SDK para Python (Boto3)
Os exemplos de código a seguir mostram como realizar ações e implementar cenários comuns usando o AWS SDK para Python (Boto3) with AWS STS.
*Ações* são trechos de código de programas maiores e devem ser executadas em contexto. Embora as ações mostrem como chamar perfis de serviço individuais, você pode ver as ações no contexto em seus cenários relacionados.
*Cenários* são exemplos de código que mostram como realizar tarefas específicas chamando várias funções dentro de um serviço ou combinadas com outros Serviços da AWS.
Cada exemplo inclui um link para o código-fonte completo, em que você pode encontrar instruções sobre como configurar e executar o código.
**Topics**
+ [Ações](#actions)
+ [Cenários](#scenarios)
## Ações
### `AssumeRole`
O código de exemplo a seguir mostra como usar `AssumeRole`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sts#code-examples).
Assuma um perfil do IAM que exija um token de MFA e use credenciais temporárias para listar os buckets do Amazon S3 para a conta.
```
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)
```
+ Para obter detalhes da API, consulte a [AssumeRole](https://docs.aws.amazon.com/goto/boto3/sts-2011-06-15/AssumeRole)Referência da API *AWS SDK for Python (Boto3*).
### `GetSessionToken`
O código de exemplo a seguir mostra como usar `GetSessionToken`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sts#code-examples).
Obtenha um token de sessão passando um token de MFA e use-o para listar os buckets do Amazon S3 para a conta.
```
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)
```
+ Para obter detalhes da API, consulte a [GetSessionToken](https://docs.aws.amazon.com/goto/boto3/sts-2011-06-15/GetSessionToken)Referência da API *AWS SDK for Python (Boto3*).
## Cenários
### Assumir um perfil do IAM que exija um token de MFA
O exemplo de código a seguir mostra como assumir um perfil que exige um token de MFA.
**Atenção**
Para evitar riscos de segurança, não use usuários do IAM para autenticação ao desenvolver software com propósito específico ou trabalhar com dados reais. Em vez disso, use federação com um provedor de identidade, como [Centro de Identidade do AWS IAM](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html).
+ Criar um perfil do IAM que conceda permissão para listar os buckets do Amazon S3.
+ Criar um usuário do IAM que tenha permissão para assumir o perfil somente quando as credenciais de MFA forem fornecidas.
+ Registrar um dispositivo MFA para o usuário.
+ Assumir o perfil e usar credenciais temporárias para listar os buckets do S3.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sts#code-examples).
Crie um usuário do IAM, registre um dispositivo de MFA e crie um perfil que conceda permissão para listar os buckets do Amazon S3. O usuário só tem direitos para assumir a função.
```
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
```
Mostre que não é permitido assumir uma função sem um token de 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
```
Assuma o perfil que concede permissão para listar os buckets do S3 passando o token de MFA necessário e mostre que os buckets podem ser listados.
```
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)
```
Destrua os recursos criados para a demonstração.
```
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}.")
```
Execute esse cenário usando a funções definidas anteriormente.
```
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!")
```
+ Para obter detalhes da API, consulte a [AssumeRole](https://docs.aws.amazon.com/goto/boto3/sts-2011-06-15/AssumeRole)Referência da API *AWS SDK for Python (Boto3*).
### Criar um URL para usuários federados usando
O exemplo de código a seguir mostra como:
+ Criar um perfil do IAM que conceda acesso somente leitura aos recursos do Amazon S3 da conta atual.
+ Obtenha um token de segurança do endpoint da AWS federação.
+ Criar um URL que possa ser usado para acessar o console com credenciais federadas.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sts#code-examples).
Crie um perfil que conceda acesso somente leitura aos recursos do S3 da conta atual.
```
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
```
Obtenha um token de segurança do endpoint da AWS federação e crie uma URL que possa ser usada para acessar o console com credenciais federadas.
```
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
```
Destrua os recursos criados para a demonstração.
```
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}.")
```
Execute esse cenário usando a funções definidas anteriormente.
```
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!")
```
+ Para obter detalhes da API, consulte a [AssumeRole](https://docs.aws.amazon.com/goto/boto3/sts-2011-06-15/AssumeRole)Referência da API *AWS SDK for Python (Boto3*).
### Obtenha um token de sessão que requeira um token de MFA
O exemplo de código a seguir mostra como obter um token de sessão que exige um token de MFA.
**Atenção**
Para evitar riscos de segurança, não use usuários do IAM para autenticação ao desenvolver software com propósito específico ou trabalhar com dados reais. Em vez disso, use federação com um provedor de identidade, como [Centro de Identidade do AWS IAM](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html).
+ Criar um perfil do IAM que conceda permissão para listar os buckets do Amazon S3.
+ Criar um usuário do IAM que tenha permissão para assumir o perfil somente quando as credenciais de MFA forem fornecidas.
+ Registrar um dispositivo MFA para o usuário.
+ Forneça credenciais de MFA para obter um token de sessão e use credenciais temporárias para listar os buckets do S3.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sts#code-examples).
Crie um usuário do IAM, registre um dispositivo de MFA e crie um perfil que conceda permissão para deixar o usuário listar os buckets do S3 somente quando credenciais de MFA forem usadas.
```
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
```
Obtenha credenciais de sessão temporárias passando um token de MFA e use-as para listar os buckets do S3 para a conta.
```
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)
```
Destrua os recursos criados para a demonstração.
```
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}.")
```
Execute esse cenário usando a funções definidas anteriormente.
```
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!")
```
+ Para obter detalhes da API, consulte a [GetSessionToken](https://docs.aws.amazon.com/goto/boto3/sts-2011-06-15/GetSessionToken)Referência da API *AWS SDK for Python (Boto3*).
# Suporte exemplos usando SDK para Python (Boto3)
Os exemplos de código a seguir mostram como realizar ações e implementar cenários comuns usando o AWS SDK para Python (Boto3) with Suporte.
As *noções básicas* são exemplos de código que mostram como realizar as operações essenciais em um serviço.
*Ações* são trechos de código de programas maiores e devem ser executadas em contexto. Embora as ações mostrem como chamar perfis de serviço individuais, você pode ver as ações no contexto em seus cenários relacionados.
Cada exemplo inclui um link para o código-fonte completo, em que você pode encontrar instruções sobre como configurar e executar o código.
**Topics**
+ [Conceitos básicos](#get_started)
+ [Conceitos básicos](#basics)
+ [Ações](#actions)
## Conceitos básicos
### Olá Suporte
O exemplo de código a seguir mostra como começar a usar o Suporte.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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"))
```
+ Para obter detalhes da API, consulte a [DescribeServices](https://docs.aws.amazon.com/goto/boto3/support-2013-04-15/DescribeServices)Referência da API *AWS SDK for Python (Boto3*).
## Conceitos básicos
### Conheça os conceitos básicos
O exemplo de código a seguir mostra como:
+ Obter e exibir os serviços disponíveis e os níveis de gravidade dos casos.
+ Criar um caso de suporte usando um serviço, uma categoria e um nível de gravidade selecionados.
+ Obter e exibir uma lista de casos em aberto para o dia atual.
+ Adicionar um conjunto de anexos e uma comunicação ao novo caso.
+ Descrever o novo anexo e a comunicação para o caso.
+ Resolver o caso.
+ Obtenha e exiba uma lista de casos resolvidos para o dia atual.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/support#code-examples).
Execute um cenário interativo em um prompt de comando.
```
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.")
```
Defina uma classe que envolva ações de suporte ao cliente.
```
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
```
+ Para obter detalhes da API, consulte os tópicos a seguir na *Referência da API AWS SDK para Python (Boto3)*.
+ [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)
## Ações
### `AddAttachmentsToSet`
O código de exemplo a seguir mostra como usar `AddAttachmentsToSet`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [AddAttachmentsToSet](https://docs.aws.amazon.com/goto/boto3/support-2013-04-15/AddAttachmentsToSet)Referência da API *AWS SDK for Python (Boto3*).
### `AddCommunicationToCase`
O código de exemplo a seguir mostra como usar `AddCommunicationToCase`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [AddCommunicationToCase](https://docs.aws.amazon.com/goto/boto3/support-2013-04-15/AddCommunicationToCase)Referência da API *AWS SDK for Python (Boto3*).
### `CreateCase`
O código de exemplo a seguir mostra como usar `CreateCase`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [CreateCase](https://docs.aws.amazon.com/goto/boto3/support-2013-04-15/CreateCase)Referência da API *AWS SDK for Python (Boto3*).
### `DescribeAttachment`
O código de exemplo a seguir mostra como usar `DescribeAttachment`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DescribeAttachment](https://docs.aws.amazon.com/goto/boto3/support-2013-04-15/DescribeAttachment)Referência da API *AWS SDK for Python (Boto3*).
### `DescribeCases`
O código de exemplo a seguir mostra como usar `DescribeCases`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DescribeCases](https://docs.aws.amazon.com/goto/boto3/support-2013-04-15/DescribeCases)Referência da API *AWS SDK for Python (Boto3*).
### `DescribeCommunications`
O código de exemplo a seguir mostra como usar `DescribeCommunications`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DescribeCommunications](https://docs.aws.amazon.com/goto/boto3/support-2013-04-15/DescribeCommunications)Referência da API *AWS SDK for Python (Boto3*).
### `DescribeServices`
O código de exemplo a seguir mostra como usar `DescribeServices`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DescribeServices](https://docs.aws.amazon.com/goto/boto3/support-2013-04-15/DescribeServices)Referência da API *AWS SDK for Python (Boto3*).
### `DescribeSeverityLevels`
O código de exemplo a seguir mostra como usar `DescribeSeverityLevels`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DescribeSeverityLevels](https://docs.aws.amazon.com/goto/boto3/support-2013-04-15/DescribeSeverityLevels)Referência da API *AWS SDK for Python (Boto3*).
### `ResolveCase`
O código de exemplo a seguir mostra como usar `ResolveCase`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [ResolveCase](https://docs.aws.amazon.com/goto/boto3/support-2013-04-15/ResolveCase)Referência da API *AWS SDK for Python (Boto3*).
# Exemplos do Systems Manager usando o SDK para Python (Boto3)
Os exemplos de código a seguir mostram como realizar ações e implementar cenários comuns usando o AWS SDK para Python (Boto3) with Systems Manager.
As *noções básicas* são exemplos de código que mostram como realizar as operações essenciais em um serviço.
*Ações* são trechos de código de programas maiores e devem ser executadas em contexto. Embora as ações mostrem como chamar perfis de serviço individuais, você pode ver as ações no contexto em seus cenários relacionados.
Cada exemplo inclui um link para o código-fonte completo, em que você pode encontrar instruções sobre como configurar e executar o código.
**Topics**
+ [Conceitos básicos](#get_started)
+ [Conceitos básicos](#basics)
+ [Ações](#actions)
## Conceitos básicos
### Hello Systems Manager
O exemplo de código a seguir mostra como começar a usar o Systems Manager.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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"])
```
+ Para obter detalhes da API, consulte a [ListDocuments](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/ListDocuments)Referência da API *AWS SDK for Python (Boto3*).
## Conceitos básicos
### Conheça os conceitos básicos
O exemplo de código a seguir mostra como:
+ Criar uma janela de manutenção.
+ Modificar a programação da janela de manutenção.
+ Criar um documento.
+ Enviar um comando para uma instância do EC2 especificada.
+ Crie um OpsItem.
+ Atualize e resolva OpsItem o.
+ Exclua a janela de manutenção OpsItem e o documento.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ssm#code-examples).
Execute um cenário interativo em um prompt de comando.
```
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.")
```
Defina uma classe que englobe as ações de documentos e comandos.
```
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
```
Defina uma classe que englobe as ações de itens de operação.
```
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
```
Defina uma classe que englobe as ações de janelas de manutenção.
```
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
```
+ Para ver detalhes da API, consulte os tópicos a seguir na *Referência da API do SDK da AWS para Python (Boto3)*.
+ [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)
## Ações
### `CreateDocument`
O código de exemplo a seguir mostra como usar `CreateDocument`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [CreateDocument](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/CreateDocument)Referência da API *AWS SDK for Python (Boto3*).
### `CreateMaintenanceWindow`
O código de exemplo a seguir mostra como usar `CreateMaintenanceWindow`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [CreateMaintenanceWindow](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/CreateMaintenanceWindow)Referência da API *AWS SDK for Python (Boto3*).
### `CreateOpsItem`
O código de exemplo a seguir mostra como usar `CreateOpsItem`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [CreateOpsItem](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/CreateOpsItem)Referência da API *AWS SDK for Python (Boto3*).
### `DeleteDocument`
O código de exemplo a seguir mostra como usar `DeleteDocument`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DeleteDocument](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/DeleteDocument)Referência da API *AWS SDK for Python (Boto3*).
### `DeleteMaintenanceWindow`
O código de exemplo a seguir mostra como usar `DeleteMaintenanceWindow`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DeleteMaintenanceWindow](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/DeleteMaintenanceWindow)Referência da API *AWS SDK for Python (Boto3*).
### `DeleteOpsItem`
O código de exemplo a seguir mostra como usar `DeleteOpsItem`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DeleteOpsItem](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/DeleteOpsItem)Referência da API *AWS SDK for Python (Boto3*).
### `DescribeOpsItems`
O código de exemplo a seguir mostra como usar `DescribeOpsItems`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DescribeOpsItems](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/DescribeOpsItems)Referência da API *AWS SDK for Python (Boto3*).
### `ListCommandInvocations`
O código de exemplo a seguir mostra como usar `ListCommandInvocations`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [ListCommandInvocations](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/ListCommandInvocations)Referência da API *AWS SDK for Python (Boto3*).
### `SendCommand`
O código de exemplo a seguir mostra como usar `SendCommand`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [SendCommand](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/SendCommand)Referência da API *AWS SDK for Python (Boto3*).
### `UpdateMaintenanceWindow`
O código de exemplo a seguir mostra como usar `UpdateMaintenanceWindow`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [UpdateMaintenanceWindow](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/UpdateMaintenanceWindow)Referência da API *AWS SDK for Python (Boto3*).
### `UpdateOpsItem`
O código de exemplo a seguir mostra como usar `UpdateOpsItem`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [UpdateOpsItem](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/UpdateOpsItem)Referência da API *AWS SDK for Python (Boto3*).
# Exemplos do Amazon Textract usando o SDK para Python (Boto3)
Os exemplos de código a seguir mostram como realizar ações e implementar cenários comuns usando o AWS SDK para Python (Boto3) com o Amazon Textract.
*Ações* são trechos de código de programas maiores e devem ser executadas em contexto. Embora as ações mostrem como chamar perfis de serviço individuais, você pode ver as ações no contexto em seus cenários relacionados.
*Cenários* são exemplos de código que mostram como realizar tarefas específicas chamando várias funções dentro de um serviço ou combinadas com outros Serviços da AWS.
Cada exemplo inclui um link para o código-fonte completo, em que você pode encontrar instruções sobre como configurar e executar o código.
**Topics**
+ [Ações](#actions)
+ [Cenários](#scenarios)
## Ações
### `AnalyzeDocument`
O código de exemplo a seguir mostra como usar `AnalyzeDocument`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [AnalyzeDocument](https://docs.aws.amazon.com/goto/boto3/textract-2018-06-27/AnalyzeDocument)Referência da API *AWS SDK for Python (Boto3*).
### `DetectDocumentText`
O código de exemplo a seguir mostra como usar `DetectDocumentText`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DetectDocumentText](https://docs.aws.amazon.com/goto/boto3/textract-2018-06-27/DetectDocumentText)Referência da API *AWS SDK for Python (Boto3*).
### `GetDocumentAnalysis`
O código de exemplo a seguir mostra como usar `GetDocumentAnalysis`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [GetDocumentAnalysis](https://docs.aws.amazon.com/goto/boto3/textract-2018-06-27/GetDocumentAnalysis)Referência da API *AWS SDK for Python (Boto3*).
### `StartDocumentAnalysis`
O código de exemplo a seguir mostra como usar `StartDocumentAnalysis`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/textract#code-examples).
Iniciar um trabalho assíncrono para analisar um documento.
```
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
```
+ Para obter detalhes da API, consulte a [StartDocumentAnalysis](https://docs.aws.amazon.com/goto/boto3/textract-2018-06-27/StartDocumentAnalysis)Referência da API *AWS SDK for Python (Boto3*).
### `StartDocumentTextDetection`
O código de exemplo a seguir mostra como usar `StartDocumentTextDetection`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/textract#code-examples).
Iniciar um trabalho assíncrono para detectar texto em um documento.
```
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
```
+ Para obter detalhes da API, consulte a [StartDocumentTextDetection](https://docs.aws.amazon.com/goto/boto3/textract-2018-06-27/StartDocumentTextDetection)Referência da API *AWS SDK for Python (Boto3*).
## Cenários
### Criar uma aplicação de exploração do Amazon Textract
O exemplo de código a seguir mostra como explorar a saída do Amazon Textract por meio de uma aplicação interativa.
**SDK para Python (Boto3)**
Mostra como usar o AWS SDK para Python (Boto3) com o Amazon Textract para detectar elementos de texto, formulário e tabela em uma imagem de documento. A imagem de entrada e a saída do Amazon Textract são mostradas em um aplicativo Tkinter que permite explorar os elementos detectados.
+ Envie uma imagem de documento para o Amazon Textract e explore a saída dos elementos detectados.
+ Envie imagens diretamente para o Amazon Textract ou por meio de um bucket do Amazon Simple Storage Service (Amazon S3).
+ Use o modo assíncrono APIs para iniciar um trabalho que publica uma notificação em um tópico do Amazon Simple Notification Service (Amazon SNS) quando o trabalho for concluído.
+ Faça uma pesquisa em uma fila do Amazon Simple Queue Service (Amazon SQS) para obter uma mensagem de conclusão do trabalho e exiba os resultados.
Para obter o código-fonte completo e instruções sobre como configurar e executar, veja o exemplo completo em [GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/textract_explorer).
**Serviços usados neste exemplo**
+ Identidade do Amazon Cognito
+ Amazon S3
+ Amazon SNS
+ Amazon SQS
+ Amazon Textract
### Detectar entidades em texto extraído de uma imagem
O exemplo de código a seguir mostra como usar o Amazon Comprehend para detectar entidades em texto extraído pelo Amazon Textract de uma imagem armazenada no Amazon S3.
**SDK para Python (Boto3)**
Mostra como usar o AWS SDK para Python (Boto3) em um notebook Jupyter para detectar entidades no texto extraído de uma imagem. Este exemplo usa o Amazon Textract para extrair texto de uma imagem armazenada no Amazon Simple Storage Service (Amazon S3) e no Amazon Comprehend para detectar entidades no texto extraído.
Este exemplo é um caderno Jupyter e deve ser executado em um ambiente que possa hospedar blocos de anotações. Para obter instruções sobre como executar o exemplo usando o Amazon SageMaker AI, consulte as instruções em [TextractAndComprehendNotebook.ipynb](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/textract_comprehend_notebook/TextractAndComprehendNotebook.ipynb).
Para obter o código-fonte completo e instruções sobre como configurar e executar, veja o exemplo completo em [GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/cross_service/textract_comprehend_notebook#readme).
**Serviços usados neste exemplo**
+ Amazon Comprehend
+ Amazon S3
+ Amazon Textract
# Exemplos do Amazon Transcribe usando o SDK para Python (Boto3)
Os exemplos de código a seguir mostram como realizar ações e implementar cenários comuns usando o AWS SDK para Python (Boto3) com o Amazon Transcribe.
*Ações* são trechos de código de programas maiores e devem ser executadas em contexto. Embora as ações mostrem como chamar perfis de serviço individuais, você pode ver as ações no contexto em seus cenários relacionados.
*Cenários* são exemplos de código que mostram como realizar tarefas específicas chamando várias funções dentro de um serviço ou combinadas com outros Serviços da AWS.
Cada exemplo inclui um link para o código-fonte completo, em que você pode encontrar instruções sobre como configurar e executar o código.
**Topics**
+ [Ações](#actions)
+ [Cenários](#scenarios)
## Ações
### `CreateVocabulary`
O código de exemplo a seguir mostra como usar `CreateVocabulary`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [CreateVocabulary](https://docs.aws.amazon.com/goto/boto3/transcribe-2017-10-26/CreateVocabulary)Referência da API *AWS SDK for Python (Boto3*).
### `DeleteTranscriptionJob`
O código de exemplo a seguir mostra como usar `DeleteTranscriptionJob`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DeleteTranscriptionJob](https://docs.aws.amazon.com/goto/boto3/transcribe-2017-10-26/DeleteTranscriptionJob)Referência da API *AWS SDK for Python (Boto3*).
### `DeleteVocabulary`
O código de exemplo a seguir mostra como usar `DeleteVocabulary`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [DeleteVocabulary](https://docs.aws.amazon.com/goto/boto3/transcribe-2017-10-26/DeleteVocabulary)Referência da API *AWS SDK for Python (Boto3*).
### `GetTranscriptionJob`
O código de exemplo a seguir mostra como usar `GetTranscriptionJob`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [GetTranscriptionJob](https://docs.aws.amazon.com/goto/boto3/transcribe-2017-10-26/GetTranscriptionJob)Referência da API *AWS SDK for Python (Boto3*).
### `GetVocabulary`
O código de exemplo a seguir mostra como usar `GetVocabulary`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [GetVocabulary](https://docs.aws.amazon.com/goto/boto3/transcribe-2017-10-26/GetVocabulary)Referência da API *AWS SDK for Python (Boto3*).
### `ListTranscriptionJobs`
O código de exemplo a seguir mostra como usar `ListTranscriptionJobs`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [ListTranscriptionJobs](https://docs.aws.amazon.com/goto/boto3/transcribe-2017-10-26/ListTranscriptionJobs)Referência da API *AWS SDK for Python (Boto3*).
### `ListVocabularies`
O código de exemplo a seguir mostra como usar `ListVocabularies`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [ListVocabularies](https://docs.aws.amazon.com/goto/boto3/transcribe-2017-10-26/ListVocabularies)Referência da API *AWS SDK for Python (Boto3*).
### `StartTranscriptionJob`
O código de exemplo a seguir mostra como usar `StartTranscriptionJob`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [StartTranscriptionJob](https://docs.aws.amazon.com/goto/boto3/transcribe-2017-10-26/StartTranscriptionJob)Referência da API *AWS SDK for Python (Boto3*).
### `UpdateVocabulary`
O código de exemplo a seguir mostra como usar `UpdateVocabulary`.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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
```
+ Para obter detalhes da API, consulte a [UpdateVocabulary](https://docs.aws.amazon.com/goto/boto3/transcribe-2017-10-26/UpdateVocabulary)Referência da API *AWS SDK for Python (Boto3*).
## Cenários
### Criar e refinar um vocabulário personalizado
O exemplo de código a seguir mostra como:
+ Fazer upload de um arquivo de áudio para o Amazon S3.
+ Executar um trabalho do Amazon Transcribe para transcrever o arquivo e obter os resultados.
+ Criar e refinar um vocabulário personalizado para melhorar a precisão da transcrição.
+ Executar trabalhos com vocabulários personalizados e obter os resultados.
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/transcribe#code-examples).
Transcreva um arquivo de áudio que contenha uma leitura de Jabberwocky de Lewis Carroll. Comece criando funções que envolvam as ações do 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
```
Chame as funções do wrapper para transcrever áudio sem um vocabulário personalizado e, em seguida, com diferentes versões de um vocabulário personalizado para ver os melhores resultados.
```
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!")
```
+ Para obter detalhes da API, consulte os tópicos a seguir na *Referência da API AWS SDK para Python (Boto3)*.
+ [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)
### Transcrever áudio e obter dados do trabalho
O exemplo de código a seguir mostra como:
+ Iniciar um trabalho de transcrição com o Amazon Transcribe.
+ Aguardar a conclusão do trabalho.
+ Obter o URI em que a transcrição está armazenada.
Para obter mais informações, consulte [Começar a usar o Amazon Transcribe](https://docs.aws.amazon.com/transcribe/latest/dg/getting-started.html).
**SDK para Python (Boto3)**
Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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()
```
+ Para obter detalhes da API, consulte os tópicos a seguir na *Referência da API AWS SDK para Python (Boto3)*.
+ [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)