aws sdk para · 2020-06-05 · usar bancos de dados nosql do amazon dynamodb ... toolkit for azure...
TRANSCRIPT
AWS SDK para .NETGuia do desenvolvedor
AWS SDK para .NET: Guia do desenvolvedorCopyright © 2020 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
AWS SDK para .NET Guia do desenvolvedor
Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's,in any manner that is likely to cause confusion among customers, or in any manner that disparages or discreditsAmazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may notbe affiliated with, connected to, or sponsored by Amazon.
AWS SDK para .NET Guia do desenvolvedor
Table of ContentsO que é o AWS SDK para .NET? ......................................................................................................... 1
Ferramentas da AWS relacionadas ao SDK ................................................................................... 1Tools para Windows PowerShell e Ferramentas para PowerShell Core ....................................... 1Toolkit para VS Code .......................................................................................................... 1Toolkit for Visual Studio ....................................................................................................... 1Toolkit for Azure DevOps ..................................................................................................... 2
Versão 3.5 do AWS SDK para .NET ............................................................................................. 2Como usar este guia .................................................................................................................. 2Serviços compatíveis e histórico de revisão .................................................................................... 3
Início rápido ....................................................................................................................................... 4Aplicativo simples para várias plataformas ...................................................................................... 4
Etapas .............................................................................................................................. 4Configurar este tutorial ........................................................................................................ 4Criar o projeto .................................................................................................................... 5Criar o código .................................................................................................................... 6Execute o aplicativo ............................................................................................................ 8Limpar .............................................................................................................................. 8Próximo... .......................................................................................................................... 8
Aplicativo simples baseado no Windows ........................................................................................ 9Etapas .............................................................................................................................. 9Configurar este tutorial ........................................................................................................ 9Criar o projeto .................................................................................................................. 10Criar o código .................................................................................................................. 11Execute o aplicativo .......................................................................................................... 12Limpar ............................................................................................................................. 13Próximo... ........................................................................................................................ 13
Próximas etapas ....................................................................................................................... 13Configuração .................................................................................................................................... 14
Criar uma conta da AWS e credenciais ........................................................................................ 14Configurar o ambiente de desenvolvimento .NET ........................................................................... 14Instalar os conjuntos do AWSSDK .............................................................................................. 15
Instalação de conjuntos de AWSSDK com NuGet .................................................................. 15Instalar o AWS SDK para .NET no Windows ......................................................................... 17
Iniciar um novo projeto .............................................................................................................. 17Plataformas que oferecem suporte ao AWS SDK para .NET ............................................................ 17
.NET Core ....................................................................................................................... 17
.NET Framework 4.5 ......................................................................................................... 18
.NET Framework 3.5 ......................................................................................................... 18Biblioteca de classe portátil ................................................................................................ 18Suporte de unidade ........................................................................................................... 18Mais informações .............................................................................................................. 18
Programação com o SDK .................................................................................................................. 19Configurar seu aplicativo ............................................................................................................ 19
Configurar o AWS SDK para .NET com .NET Core ................................................................ 20Configurar as credenciais da AWS ...................................................................................... 23Seleção da região da AWS ................................................................................................ 32Configuração de outros parâmetros do aplicativo ................................................................... 33Referência dos arquivos de configuração para o AWS SDK para .NET ...................................... 39Habilitar o Métricas do SDK .............................................................................................. 47
APIs assíncronas ...................................................................................................................... 51API assíncrona para .NET Framework 4.5, Windows Store e Windows Phone 8 .......................... 51API assíncrona para .NET Framework 3.5 ............................................................................ 52
Tentativas e tempos limite .......................................................................................................... 59Tentativas ........................................................................................................................ 59
iii
AWS SDK para .NET Guia do desenvolvedor
Tempo limite atingido ........................................................................................................ 60Exemplo .......................................................................................................................... 60
Migrar para a versão 3 .............................................................................................................. 60Sobre as versões do AWS SDK para .NET ........................................................................... 61Redefinição da arquitetura para o SDK ................................................................................ 61Últimas alterações ............................................................................................................. 61
Migrar para a versão 3.5 ........................................................................................................... 62O que mudou na versão 3.5 ............................................................................................... 62Migrar código síncrono ...................................................................................................... 63
Migração do .NET Standard 1.3 .................................................................................................. 64Exemplos de código .......................................................................................................................... 66
Listar recursos da AWS usando o AWS CloudFormation ................................................................ 66Autenticar usuários com o Amazon Cognito .................................................................................. 67
Provedor de credenciais do Amazon Cognito ....................................................................... 67Exemplo da biblioteca de extensões Amazon CognitoAuthentication ......................................... 69
Usar bancos de dados NoSQL do Amazon DynamoDB .................................................................. 72Modelo de baixo nível ....................................................................................................... 73Modelo de documento ....................................................................................................... 75Modelo de persistência de objeto ........................................................................................ 76Mais informações .............................................................................................................. 78Usar expressões com Amazon DynamoDB e AWS SDK para .NET .......................................... 78Suporte a JSON no Amazon DynamoDB com o AWS SDK para .NET ....................................... 88Gerenciamento do estado da sessão ASP.NET com o Amazon DynamoDB .............................. 90
Implantar aplicativos usando o Amazon EC2 ................................................................................. 93Exemplos de instâncias do Amazon EC2 ............................................................................. 93Exemplos de instância spot do Amazon EC2 ....................................................................... 111
Armazenar dados de arquivamento usando o Amazon S3 Glacier ................................................... 119Modelos de programação ................................................................................................. 119
Como gerenciar usuários com o AWS IAM ................................................................................. 122Como gerenciar aliases do IAM ........................................................................................ 123Gerenciar usuários do IAM .............................................................................................. 125Gerenciar chaves de acesso do IAM ................................................................................. 127Trabalhar com políticas do IAM ........................................................................................ 131Trabalhar com certificados de servidor do IAM ................................................................... 135Listar informações da conta do IAM ................................................................................... 137Como conceder acesso usando uma função do IAM ............................................................ 138
Usar chaves do AWS KMS com o AmazonS3EncryptionClient no AWS SDK para .NET ...................... 142Gerenciar recursos do Domain Name System (DNS) usando o Amazon Route 53 ............................. 144Usar o armazenamento na Internet do Amazon Simple Storage Service .......................................... 149Enviar notificações da nuvem usando o Amazon Simple Notification Service ..................................... 149
Listar os tópicos do Amazon SNS ..................................................................................... 149Enviar uma mensagem para um tópico do Amazon SNS ....................................................... 150Enviar uma mensagem SMS para um número de telefone ..................................................... 151
Enviar mensagens usando o Amazon SQS ................................................................................. 152Criação de um cliente do Amazon SQS ............................................................................ 153Criação de uma fila do Amazon SQS ................................................................................ 154Construção de URLs de fila do Amazon SQS ..................................................................... 154Envio de uma mensagem do Amazon SQS ....................................................................... 155Envio de um lote de mensagens do Amazon SQS .............................................................. 155Recebendo uma mensagem de uma fila do Amazon SQS .................................................... 156Exclusão de uma mensagem de uma fila do Amazon SQS ................................................... 157Habilitar sondagem longa no Amazon SQS ........................................................................ 158Usando filas do Amazon SQS .......................................................................................... 159Usar Amazon SQS fila de mensagens mortas .................................................................... 160
Monitoramento de seus recursos da AWS usando o Amazon CloudWatch ....................................... 161Descrição, criação e exclusão de alarmes no Amazon CloudWatch ........................................ 162Uso de alarmes no Amazon CloudWatch ........................................................................... 164
iv
AWS SDK para .NET Guia do desenvolvedor
Obtenção de métricas do Amazon CloudWatch .................................................................. 165Envio de eventos para Amazon CloudWatch Events ............................................................. 167Uso de filtros de assinatura no Amazon CloudWatch Logs .................................................... 170
Programar o AWS OpsWorks para trabalhar com pilhas e aplicativos .............................................. 172Programar suporte para serviços da AWS adicionais .................................................................... 173
Segurança ...................................................................................................................................... 174Proteção de dados .................................................................................................................. 174Identity and Access Management .............................................................................................. 175Compliance Validation .............................................................................................................. 175Resilience .............................................................................................................................. 176Infrastructure Security .............................................................................................................. 176Impor o TLS 1.2 ..................................................................................................................... 177
.NET Core ...................................................................................................................... 177
.NET Framework ............................................................................................................. 177AWS Tools para PowerShell ............................................................................................. 178Xamarin ......................................................................................................................... 178Unity ............................................................................................................................. 179Navegador (para Blazor WebAssembly) .............................................................................. 179
Recursos adicionais ......................................................................................................................... 180Histórico do documento .................................................................................................................... 181
v
AWS SDK para .NET Guia do desenvolvedorFerramentas da AWS relacionadas ao SDK
O que é o AWS SDK para .NET?O AWS SDK para .NET facilita a criação de aplicativos .NET que exploram serviços econômicos,escaláveis e confiáveis da AWS, como Amazon Simple Storage Service (Amazon S3) e Amazon ElasticCompute Cloud (Amazon EC2). O AWS SDK para .NET oferece suporte ao NET Framework 3.5, .NETFramework 4.5, .NET Standard 2.0, Portable Class Library, Xamarin e ao Unity.
A menos que haja indicação em contrário, as informações deste guia se aplicam a todos os destinoscompatíveis.
(OK, entendi! Estou pronto para um tutorial (p. 4) ou para começar a configurar (p. 14).)
Ferramentas da AWS relacionadas ao SDKTools para Windows PowerShell e Ferramentas paraPowerShell CoreO AWS Tools para Windows PowerShell e o Ferramentas da AWS para PowerShell Core são módulos doPowerShell criados com base na funcionalidade exposta pelo AWS SDK para .NET. O AWS PowerShellTools permite que você execute scripts para operações em seus recursos da AWS usando a linha decomando do PowerShell. Embora os cmdlets sejam implementados usando os clientes de serviços e osmétodos do SDK, os cmdlets proporcionam uma experiência idiomática do PowerShell para especificarparâmetros e lidar com os resultados.
Para começar a usar, consulte AWS Tools for Windows PowerShell.
Toolkit para VS CodeO Toolkit da AWS para Visual Studio Code é um plug-in para o editor Visual Studio Code (VS Code). Otoolkit facilita o desenvolvimento, a depuração e a implantação de aplicativos que usam a AWS. Com otoolkit, é possível fazer o seguinte:
• Criar aplicativos sem servidor que contenham funções do AWS Lambda e implantá-los em uma pilha doAWS CloudFormation.
• Trabalhar com esquemas do Amazon EventBridge.• Usar o IntelliSense ao trabalhar com arquivos de definição de tarefa do Amazon ECS.• Visualizar um aplicativo do Kit de desenvolvimento da Nuvem AWS (AWS CDK).
Toolkit for Visual StudioO AWS Toolkit for Visual Studio é um plug-in do IDE do Visual Studio que facilita o desenvolvimento, adepuração e a implantação de aplicativos .NET que usam a Amazon Web Services. O Toolkit for VisualStudio fornece modelos do Visual Studio para serviços, como o Lambda, e assistentes de implantaçãopara aplicativos web e aplicativos sem servidor. Use o AWS Explorer para gerenciar instâncias do AmazonEC2, trabalhar com tabelas do Amazon DynamoDB, publicar mensagens para as filas do Amazon SimpleNotification Service (Amazon SNS) e muito mais, tudo no Visual Studio.
É possível implantar rapidamente um aplicativo web existente usando o Toolkit for Visual Studio. ConsulteImplantar aplicativos web usando o Visual Studio.
1
AWS SDK para .NET Guia do desenvolvedorToolkit for Azure DevOps
Para começar, consulte Configurar o AWS Toolkit for Visual Studio.
Toolkit for Azure DevOpsO AWS Toolkit for Microsoft Azure DevOps adiciona tarefas para habilitar facilmente pipelines decompilação e lançamento no Azure DevOps e no Azure DevOps Server para trabalhar com serviços daAWS. É possível trabalhar com Amazon S3, AWS Elastic Beanstalk, AWS CodeDeploy, Lambda, AWSCloudFormation, Amazon Simple Queue Service (Amazon SQS) e Amazon SNS. Também é possívelexecutar comandos usando o módulo do Windows PowerShell e a AWS Command Line Interface (AWSCLI).
Para começar a usar o AWS Toolkit for Azure DevOps, consulte AWS Toolkit for Microsoft Azure DevOpsUser Guide.
Versão 3.5 do AWS SDK para .NETThis is prerelease documentation for a feature in preview release. It is subject to change.
A versão 3.5 do AWS SDK para .NET padroniza ainda mais a experiência do .NET fazendo a transição dosuporte para todas as variações que não sejam do Framework do SDK para o .NET Standard 2.0.
Dependendo do ambiente e da base de código, para aproveitar os recursos da versão 3.5, talvez sejanecessário executar certos trabalhos de migração. Para obter detalhes sobre a versão 3.5 e os possíveistrabalhos de migração, consulte Migrar para a versão 3.5 do AWS SDK para .NET (p. 62).
Como usar este guiaO Guia do desenvolvedor do AWS SDK para .NET descreve como implementar aplicativos para a AWSusando o AWS SDK para .NET e inclui as tarefas e recursos a seguir.
Comece a usar o AWS SDK para .NET com rapidez (p. 4)
Tutoriais básicos que mostram alguns cenários comuns, bem como uma configuração mínima paradar suporte a eles, para quem não está familiarizado com o desenvolvimento .NET na AWS.
Configurar o AWS SDK para .NET (p. 14)
Como instalar e configurar o AWS SDK para .NET. Se você não tiver usado o AWS SDK para .NETantes ou estiver enfrentando dificuldades com a configuração, comece por aqui.
Programação com o AWS SDK para .NET (p. 19)
Os conceitos básicos de como executar aplicativos com o AWS SDK para .NET que se aplicam atodos os serviços da AWS. Esta seção também inclui informações sobre como migrar o código para aversão mais recente do AWS SDK para .NET e descreve as diferenças entre a versão mais recente eesta.
Exemplos de código (p. 66)
Uma série de tutoriais, demonstrações e exemplos que mostram como usar o AWS SDK para .NETpara criar aplicativos para determinados serviços da AWS. É possível procurar os exemplos do AWSSDK para .NET no Catálogo de exemplos de código da AWS.
A AWS SDK for .NET API Reference, fornece uma descrição detalhada de cada namespace e classe.
2
AWS SDK para .NET Guia do desenvolvedorServiços compatíveis e histórico de revisão
Recursos adicionais (p. 180)
Mais recursos fora deste guia que fornecem informações valiosas sobre a AWS e o AWS SDKpara .NET. Se você não estiver familiarizado com os serviços da AWS, consulte a Visão geral daAmazon Web Services.
Serviços compatíveis e histórico de revisãoO AWS SDK para .NET oferece suporte à maioria dos produtos de infraestrutura da AWS e mais serviçossão adicionados com frequência. Para obter uma lista de serviços da AWS compatíveis com o SDK,consulte o arquivo SDK README.
Para ver o que mudou em determinada versão, consulte o log de alterações do SDK.
3
AWS SDK para .NET Guia do desenvolvedorAplicativo simples para várias plataformas
Comece a usar o AWS SDKpara .NET com rapidez
Essa seção inclui a configuração básica e tutoriais destinados a desenvolvedores que não estãofamiliarizados com o AWS SDK para .NET.
Para obter mais informações avançadas, consulte Exemplos de código (p. 66) eConfiguração (p. 14).
Tópicos• Aplicativo simples para várias plataformas usando o AWS SDK para .NET (p. 4)• Aplicativo simples baseado no Windows usando o AWS SDK para .NET (p. 9)• Próximas etapas (p. 13)
Aplicativo simples para várias plataformas usando oAWS SDK para .NET
Esse tutorial usa o AWS SDK para .NET juntamente com o .NET Core para o desenvolvimento em váriasplataformas. O tutorial mostra como usar o SDK para listar os buckets do Amazon S3 que você possui ecriar um novo bucket de forma opcional.
Etapas• Configurar este tutorial (p. 4)• Criar o projeto (p. 5)• Criar o código (p. 6)• Execute o aplicativo (p. 8)• Limpar (p. 8)
Configurar este tutorialThis section provides the minimal setup needed to complete this tutorial. You shouldn't consider this to be afull setup. For that, see Configurar o AWS SDK para .NET (p. 14).
Note
If you've already completed any of the following steps through other tutorials or existingconfiguration, skip those steps.
Criar uma conta da AWSTo create an AWS account, see How do I create and activate a new Amazon Web Services account?.
Criar credenciais e um perfil da AWSPara executar esses tutoriais, é necessário criar um usuário do IAM e obter credenciais para esse usuário.Depois de ter essas credenciais, disponibilize-as para o SDK em seu ambiente de desenvolvimento. Vejacomo.
4
AWS SDK para .NET Guia do desenvolvedorCriar o projeto
Como criar e usar credenciais
1. Faça login no Console de gerenciamento da AWS e abra o console da IAM em https://console.aws.amazon.com/iam/.
2. Escolha Users (Usuários) e Add user (Adicionar usuário).3. Forneça um nome de usuário. Para este tutorial, usaremos Dotnet-Tutorial-User.4. Em Select AWS access type (Selecionar o tipo de acesso da AWS), selecione Programmatic access
(Acesso programático) e selecione Next: Permissions (Próximo: permissões).5. Selecione Attach existing policies directly.6. No campo Search (Pesquisar) digite “s3" e selecione AmazonS3FullAccess.7. Selecione Next: Tags (Próximo: Tags), Next: Review (Próximo: Revisar) e Create user (Criar usuário).8. Registre as credenciais para Dotnet-Tutorial-User. Para isso, faça download do arquivo .csv ou copie
e cole o ID de chave de acesso e a chave de acesso secreta.
Warning
Use medidas de segurança apropriadas para manter essas credenciais seguras e alternadas.9. Crie ou abra o arquivo de credenciais compartilhado da AWS. Este arquivo é ~/.aws/credentials
em sistemas Linux e macOS e %HOME%\.aws\credentials no Windows.10. Adicione o texto a seguir ao arquivo de credenciais compartilhado da AWS, mas substitua o ID de
exemplo e a chave de exemplo pelos obtidos anteriormente. Lembre-se de salvar o arquivo.
[dotnet-tutorials]aws_access_key_id = AKIAIOSFODNN7EXAMPLEaws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
O procedimento anterior é a mais simples de várias possibilidades de autenticação e autorização. Paraobter informações completas, consulte o tópico Configurar as credenciais da AWS (p. 23).
Instalar outras ferramentas
Você executará este tutorial usando ferramentas para várias plataforma, como a interface de linha decomando (CLI) do .NET. Para outras maneiras de configurar seu ambiente de desenvolvimento, consulte otópico Configurar o ambiente de desenvolvimento .NET (p. 14).
Necessário para desenvolvimento .NET para várias plataformas no Windows, no Linux ou nomacOS:
• Microsoft .NET Core SDK, versão 2.1, 3.1 ou posterior, que inclua a interface de linha de comando (CLI)do .NET (dotnet) e o tempo de execução do .NET Core.
• Um editor de código ou IDE (Integrated Development Environment – ambiente de desenvolvimentointegrado) apropriado para seu sistema operacional e requisitos. Geralmente, um que forneça algumsuporte ao .NET Core.
Exemplos incluem Microsoft Visual Studio Code (VS Code), JetBrains Rider e Microsoft Visual Studio.
Criar o projeto1. Abra a linha de comando ou o terminal. Localize ou crie uma pasta do sistema operacional na qual
você pode criar um projeto .NET.2. Nessa pasta, execute o comando a seguir para criar o projeto .NET.
5
AWS SDK para .NET Guia do desenvolvedorCriar o código
dotnet new console --name S3CreateAndList
3. Vá para a pasta recém-criada S3CreateAndList e execute o comando a seguir.
dotnet add package AWSSDK.S3
O comando anterior instala o pacote AWSSDK.S3 NuGet do gerenciador de pacotes NuGet. Comosabemos exatamente quais pacotes NuGet precisamos para esse tutorial, podemos executaresta etapa agora. Também é bastante comum conhecer os pacotes necessários durante odesenvolvimento. Quando isso acontece, um comando semelhante pode ser executado nessemomento.
4. Adicione as variáveis de ambiente temporárias a seguir ao ambiente.
No Linux ou macOS:
AWS_PROFILE='dotnet-tutorials'AWS_REGION='us-west-2'
No Windows:
set AWS_PROFILE=dotnet-tutorialsset AWS_REGION=us-west-2
Criar o código1. Na pasta S3CreateAndList, localize e abra Program.cs no editor de código.2. Substitua o conteúdo pelo código a seguir e salve o arquivo.
using System;using System.Threading.Tasks;
// To interact with Amazon S3.using Amazon.S3;using Amazon.S3.Model;
namespace S3CreateAndList{ class Program { // Function Main static async Task Main(string[] args) { // Before running this app, credentials must be specified either in the [default] profile // or in another profile and then by setting the AWS_PROFILE environment variable. // A region must be specified either in the [default] profile or by setting the AWS_REGION environment variable.
// Create an S3 client object. var client = new AmazonS3Client();
// Parse the command line arguments for the bucket name. // If a bucket name was supplied, create the bucket. if(GetBucketName(args, out String bucketName)) {
6
AWS SDK para .NET Guia do desenvolvedorCriar o código
try { Console.WriteLine(); Console.WriteLine($"Creating bucket {bucketName}..."); var response = await client.PutBucketAsync(bucketName); Console.WriteLine($"Result: {response.HttpStatusCode.ToString()}"); } catch(Exception e) { Console.WriteLine("Caught exception when creating a bucket:"); Console.WriteLine(e.Message); } }
// List the buckets owned by the user. try { Console.WriteLine(); Console.WriteLine("Getting a list of your buckets..."); var response = await client.ListBucketsAsync(); Console.WriteLine($"Number of buckets: {response.Buckets.Count}"); foreach(S3Bucket b in response.Buckets) { Console.WriteLine(b.BucketName); } } catch(Exception e) { Console.WriteLine("Caught exception when getting the list of buckets:"); Console.WriteLine(e.Message); } }
// Function GetBucketName. // Parses the command line arguments to find the bucket name. private static Boolean GetBucketName(string[] args, out String bucketName) { Boolean retval = false; bucketName = String.Empty; if(args.Length == 0) { Console.WriteLine(); Console.WriteLine("No arguments specified. Will simply list your Amazon S3 buckets."); Console.WriteLine("If you wish to create a bucket, supply a valid, globally unique bucket name."); bucketName = String.Empty; retval = false; } else if(args.Length == 1) { bucketName = args[0]; retval = true; } else { Console.WriteLine(); Console.WriteLine("Too many arguments specified."); Console.WriteLine(); Console.WriteLine("dotnet_tutorials - A utility to list your Amazon S3 buckets and optionally create a new one."); Console.WriteLine(); Console.WriteLine("Usage: S3CreateAndList [bucket_name]"); Console.WriteLine(" - bucket_name, if supplied, must be a valid, globally unique bucket name");
7
AWS SDK para .NET Guia do desenvolvedorExecute o aplicativo
Console.WriteLine(" - If bucket_name is not supplied, this utility will simply list your buckets."); Environment.Exit(1); }
return retval; } }}
Execute o aplicativo1. Execute o seguinte comando.
dotnet run
2. Examine a saída para ver o número de buckets do Amazon S3 que você possui e seus nomes, sehouver.
3. Escolha um nome para um novo bucket do Amazon S3. Use "dotnet-quickstart-s3-1-cross-" comobase e adicione algo exclusivo a ele, como um GUID ou seu nome etc. Certifique-se de seguir asregras para nomes de bucket, conforme descrito em Regras para nomeação de bucket no Guia dodesenvolvedor do Amazon Simple Storage Service.
4. Execute o comando a seguir, substituindo BUCKET-NAME pelo nome do bucket escolhido.
dotnet run BUCKET-NAME
5. Examine a saída para ver o novo bucket que foi criado.
LimparAo executar este tutorial, você criou alguns recursos que pode escolher para limpar neste momento.
• Se você não quiser manter o bucket que o aplicativo criou em uma etapa anterior, será possível excluí-lousando o console do Amazon S3 em https://console.aws.amazon.com/s3/.
• Se você não quiser manter o usuário criado durante a configuração do tutorial anteriormente nestetópico, será possível excluí-lo usando o console do IAM em https://console.aws.amazon.com/iam/home#/users.
Se você optar por excluir o usuário, também será necessário remover o perfil dotnet-tutorialscriado no arquivo de credenciais compartilhado da AWS. Você criou este perfil durante a configuraçãodo tutorial anteriormente neste tópico.
• Se você não quiser manter seu projeto .NET, remova a pasta S3CreateAndList do seu ambiente dedesenvolvimento.
Próximo...Volte para o menu de início rápido (p. 4) ou vá direto para o final deste início rápido (p. 13).
8
AWS SDK para .NET Guia do desenvolvedorAplicativo simples baseado no Windows
Aplicativo simples baseado no Windows usando oAWS SDK para .NET
Este tutorial usa o AWS SDK para .NET no Windows juntamente com o Visual Studio e o .NET Core. Otutorial mostra como usar o SDK para listar os buckets do Amazon S3 que você possui e criar um novobucket de forma opcional.
Etapas• Configurar este tutorial (p. 9)• Criar o projeto (p. 10)• Criar o código (p. 11)• Execute o aplicativo (p. 12)• Limpar (p. 13)
Configurar este tutorialThis section provides the minimal setup needed to complete this tutorial. You shouldn't consider this to be afull setup. For that, see Configurar o AWS SDK para .NET (p. 14).
Note
If you've already completed any of the following steps through other tutorials or existingconfiguration, skip those steps.
Criar uma conta da AWSTo create an AWS account, see How do I create and activate a new Amazon Web Services account?.
Criar credenciais e um perfil da AWSPara executar esses tutoriais, é necessário criar um usuário do IAM e obter credenciais para esse usuário.Depois de ter essas credenciais, disponibilize-as para o SDK em seu ambiente de desenvolvimento. Vejacomo.
Como criar e usar credenciais
1. Faça login no Console de gerenciamento da AWS e abra o console da IAM em https://console.aws.amazon.com/iam/.
2. Escolha Users (Usuários) e Add user (Adicionar usuário).3. Forneça um nome de usuário. Para este tutorial, usaremos Dotnet-Tutorial-User.4. Em Select AWS access type (Selecionar o tipo de acesso da AWS), selecione Programmatic access
(Acesso programático) e selecione Next: Permissions (Próximo: permissões).5. Selecione Attach existing policies directly.6. No campo Search (Pesquisar) digite “s3" e selecione AmazonS3FullAccess.7. Selecione Next: Tags (Próximo: Tags), Next: Review (Próximo: Revisar) e Create user (Criar usuário).8. Registre as credenciais para Dotnet-Tutorial-User. Para isso, faça download do arquivo .csv ou copie
e cole o ID de chave de acesso e a chave de acesso secreta.Warning
Use medidas de segurança apropriadas para manter essas credenciais seguras e alternadas.
9
AWS SDK para .NET Guia do desenvolvedorCriar o projeto
9. Crie ou abra o arquivo de credenciais compartilhado da AWS. Este arquivo é ~/.aws/credentialsem sistemas Linux e macOS e %HOME%\.aws\credentials no Windows.
10. Adicione o texto a seguir ao arquivo de credenciais compartilhado da AWS, mas substitua o ID deexemplo e a chave de exemplo pelos obtidos anteriormente. Lembre-se de salvar o arquivo.
[dotnet-tutorials]aws_access_key_id = AKIAIOSFODNN7EXAMPLEaws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
O procedimento anterior é a mais simples de várias possibilidades de autenticação e autorização. Paraobter informações completas, consulte o tópico Configurar as credenciais da AWS (p. 23).
Instalar outras ferramentas
Você executará este tutorial no Windows usando o Visual Studio e o .NET Core. Para outrasmaneiras de configurar seu ambiente de desenvolvimento, consulte o tópico Configurar o ambiente dedesenvolvimento .NET (p. 14).
Para desenvolvimento no Windows com Visual Studio e .NET Core:
• Microsoft Visual Studio• Microsoft .NET Core 2.1, 3.1 ou posterior
Isso geralmente é incluído por padrão ao instalar uma versão moderna do Visual Studio.
Criar o projeto1. Abra o Visual Studio e crie um novo projeto que use a versão C# do modelo do Console App (.NET
Core) (Aplicativo de console [.NET Core]). Nomeie o projeto S3CreateAndList.2. Com o projeto recém-criado carregado, abra Tools (Ferramentas), NuGet Package Manager
(Gerenciador de pacotes NuGet), Manage NuGet Packages for Solution (Gerenciar pacotes NuGetpara a solução).
3. Procure o pacote AWSSDK.S3 NuGet e instale-o no projeto.
Esse processo instala o pacote AWSSDK.S3 NuGet do gerenciador de pacotes NuGet. Comosabemos exatamente quais pacotes NuGet precisamos para esse tutorial, podemos executaresta etapa agora. Também é bastante comum conhecer os pacotes necessários durante odesenvolvimento. Quando isso acontecer, siga um processo semelhante para instalá-los nessemomento.
4. Se você pretende executar o aplicativo na linha de comando, abra uma linha de comando agorae navegue até a pasta que conterá a saída de compilação. Normalmente, isso é algo comoS3CreateAndList\S3CreateAndList\bin\Debug\netcoreapp3.1, mas dependerá do nossoambiente.
5. Adicione as variáveis de ambiente temporárias a seguir ao ambiente.
Na linha de comando:
set AWS_PROFILE=dotnet-tutorialsset AWS_REGION=us-west-2
Ou, se você pretende executar o aplicativo no IDE, vá para Project (Projeto), S3CreateAndListProperties (Propriedades S3CreateAndList), Debug (Depurar) e defina-o lá.
10
AWS SDK para .NET Guia do desenvolvedorCriar o código
Criar o código1. No projeto S3CreateAndList, localize e abra Program.cs no IDE.2. Substitua o conteúdo pelo código a seguir e salve o arquivo.
using System;using System.Threading.Tasks;
// To interact with Amazon S3.using Amazon.S3;using Amazon.S3.Model;
namespace S3CreateAndList{ class Program { // Function Main static async Task Main(string[] args) { // Before running this app, credentials must be specified either in the [default] profile // or in another profile and then by setting the AWS_PROFILE environment variable. // A region must be specified either in the [default] profile or by setting the AWS_REGION environment variable.
// Create an S3 client object. var client = new AmazonS3Client();
// Parse the command line arguments for the bucket name. // If a bucket name was supplied, create the bucket. if(GetBucketName(args, out String bucketName)) { try { Console.WriteLine(); Console.WriteLine($"Creating bucket {bucketName}..."); var response = await client.PutBucketAsync(bucketName); Console.WriteLine($"Result: {response.HttpStatusCode.ToString()}"); } catch(Exception e) { Console.WriteLine("Caught exception when creating a bucket:"); Console.WriteLine(e.Message); } }
// List the buckets owned by the user. try { Console.WriteLine(); Console.WriteLine("Getting a list of your buckets..."); var response = await client.ListBucketsAsync(); Console.WriteLine($"Number of buckets: {response.Buckets.Count}"); foreach(S3Bucket b in response.Buckets) { Console.WriteLine(b.BucketName); } } catch(Exception e) { Console.WriteLine("Caught exception when getting the list of buckets:");
11
AWS SDK para .NET Guia do desenvolvedorExecute o aplicativo
Console.WriteLine(e.Message); } }
// Function GetBucketName. // Parses the command line arguments to find the bucket name. private static Boolean GetBucketName(string[] args, out String bucketName) { Boolean retval = false; bucketName = String.Empty; if(args.Length == 0) { Console.WriteLine(); Console.WriteLine("No arguments specified. Will simply list your Amazon S3 buckets."); Console.WriteLine("If you wish to create a bucket, supply a valid, globally unique bucket name."); bucketName = String.Empty; retval = false; } else if(args.Length == 1) { bucketName = args[0]; retval = true; } else { Console.WriteLine(); Console.WriteLine("Too many arguments specified."); Console.WriteLine(); Console.WriteLine("dotnet_tutorials - A utility to list your Amazon S3 buckets and optionally create a new one."); Console.WriteLine(); Console.WriteLine("Usage: S3CreateAndList [bucket_name]"); Console.WriteLine(" - bucket_name, if supplied, must be a valid, globally unique bucket name"); Console.WriteLine(" - If bucket_name is not supplied, this utility will simply list your buckets."); Environment.Exit(1); }
return retval; } }}
3. Compile o aplicativo.
Execute o aplicativo1. Execute o aplicativo sem argumentos de linha de comando. Faça isso na linha de comando (se você
abriu uma anteriormente) ou no IDE.2. Examine a saída para ver o número de buckets do Amazon S3 que você possui e seus nomes, se
houver.3. Escolha um nome para um novo bucket do Amazon S3. Use "dotnet-quickstart-s3-1-winvs-" como
base e adicione algo exclusivo a ele, como um GUID ou seu nome etc. Certifique-se de seguir asregras para nomes de bucket, conforme descrito em Regras para nomeação de bucket no Guia dodesenvolvedor do Amazon Simple Storage Service.
4. Execute o aplicativo novamente, desta vez fornecendo o nome do bucket.
Na linha de comando, substitua BUCKET-NAME no comando a seguir pelo nome do bucket escolhido:
12
AWS SDK para .NET Guia do desenvolvedorLimpar
S3CreateAndList BUCKET-NAME
Ou, se você estiver executando o aplicativo no IDE, vá para Project (Projeto), S3CreateAndListProperties (Propriedades S3CreateAndList), Debug (Depurar) e insira o nome do bucket lá.
5. Examine a saída para ver o novo bucket que foi criado.
LimparAo executar este tutorial, você criou alguns recursos que pode escolher para limpar neste momento.
• Se você não quiser manter o bucket que o aplicativo criou em uma etapa anterior, será possível excluí-lousando o console do Amazon S3 em https://console.aws.amazon.com/s3/.
• Se você não quiser manter o usuário criado durante a configuração do tutorial anteriormente nestetópico, será possível excluí-lo usando o console do IAM em https://console.aws.amazon.com/iam/home#/users.
Se você optar por excluir o usuário, também será necessário remover o perfil dotnet-tutorialscriado no arquivo de credenciais compartilhado da AWS. Você criou este perfil durante a configuraçãodo tutorial anteriormente neste tópico.
• Se você não quiser manter seu projeto .NET, remova a pasta S3CreateAndList do seu ambiente dedesenvolvimento.
Próximo...Volte para o menu de início rápido (p. 4) ou vá direto para o final deste início rápido (p. 13).
Próximas etapasCertifique-se de limpar todos os recursos criados durante a execução desses tutoriais. Eles podem serrecursos da AWS ou recursos em seu ambiente de desenvolvimento, como arquivos e pastas.
Agora que você visitou o AWS SDK para .NET, talvez queira examinar a configuração maisavançada (p. 14).
13
AWS SDK para .NET Guia do desenvolvedorCriar uma conta da AWS e credenciais
Configurar o AWS SDK para .NETEsse tópico mostra como configurar totalmente o AWS SDK para .NET.
Se você não está familiarizado com o desenvolvimento .NET na AWS, ou pelo menos com o AWS SDKpara .NET, confira o tópico Início rápido (p. 4) primeiro. Ele fornece uma introdução simples ao SDK.
Tópicos• Criar uma conta da AWS e credenciais (p. 14)• Configurar o ambiente de desenvolvimento .NET (p. 14)• Instalar os conjuntos do AWSSDK (p. 15)• Iniciar um novo projeto (p. 17)• Plataformas que oferecem suporte ao AWS SDK para .NET (p. 17)
Criar uma conta da AWS e credenciaisPara usar o AWS SDK para .NET a fim de acessar serviços da AWS, é necessário ter uma conta ecredenciais da AWS. Para aumentar a segurança da conta da AWS, recomendamos usar um usuário doIAM para fornecer credenciais de acesso, em vez de usar as credenciais de conta raiz.
• Para criar uma conta da AWS, consulte Como criar e ativar uma conta da Amazon Web Services?.• Evite usar a conta de usuário raiz (a conta inicial criada) para acessar serviços. Em vez disso, crie
uma conta de usuário administrativo, conforme explicado em Criação do primeiro grupo e usuárioadministrador do IAM. Depois que criar a conta de usuário administrativo e registrar os detalhes de login,saia da conta de usuário raiz e entre novamente usando a conta administrativa.
• Para executar muitas das tarefas e exemplos neste guia, será necessário ter chaves de acesso parauma conta de usuário para que possa acessar os serviços da AWS de forma programática. Para criarchaves de acesso para um usuário existente, consulte Gerenciar chaves de Acesso (Console). Comoalternativa, é possível criar chaves de acesso durante a criação de um usuário. Ao criar o usuário,escolha um Access type (Tipo de Acesso) de Programmatic access (Acesso programático) em vez de(ou além de) AWS Management Console access (Acesso do Console de Gerenciamento da AWS).
• Para fechar a conta da AWS, consulte Fechar uma conta.
Para obter informações adicionais sobre como lidar com certificados e segurança, consulte Melhorespráticas e casos de uso do IAM no Guia do usuário do IAM
Configurar o ambiente de desenvolvimento .NETPara usar o AWS SDK para .NET, é necessário ter os seguintes itens instalados:
Note
Se você executou o início rápido do SDK (p. 4), é possível que já tenha algumas dessasferramentas instaladas. Se você não fez o início rápido e não está familiarizado com o
14
AWS SDK para .NET Guia do desenvolvedorInstalar os conjuntos do AWSSDK
desenvolvimento .NET na AWS, considere fazer isso primeiro para obter uma introdução simplesao AWS SDK para .NET.
Necessário para desenvolvimento .NET para várias plataformas no Windows, no Linux ou nomacOS:
• Microsoft .NET Core SDK, versão 2.1, 3.1 ou posterior, que inclua a interface de linha de comando (CLI)do .NET (dotnet) e o tempo de execução do .NET Core.
• Um editor de código ou IDE (Integrated Development Environment – ambiente de desenvolvimentointegrado) apropriado para seu sistema operacional e requisitos. Geralmente, um que forneça algumsuporte ao .NET Core.
Exemplos incluem Microsoft Visual Studio Code (VS Code), JetBrains Rider e Microsoft Visual Studio.
Necessário para desenvolvimento no Windows com o Visual Studio e o .NET Core:
• Microsoft Visual Studio• Microsoft .NET Core 2.1, 3.1 ou posterior
Isso geralmente é incluído por padrão ao instalar uma versão moderna do Visual Studio.• (Opcional) O AWS Toolkit for Visual Studio, que é um plug-in que fornece uma interface de usuário
para gerenciar seus recursos da AWS e perfis locais no Visual Studio. Para instalar o toolkit, consulteConfigurar o AWS Toolkit for Visual Studio.
Para obter mais informações, consulte o Guia do usuário do AWS Toolkit for Visual Studio.
Instalar os conjuntos do AWSSDKOs conjuntos do AWSSDK estão disponíveis no NuGet ou por meio de um pacote de instalação doWindows. O AWS SDK para .NET também está disponível no repositório aws/aws-sdk-net no GitHub. Porfim, é possível encontrar muitas informações sobre o AWS .NET no repositório aws/dotnet no GitHub.
Instalação de conjuntos de AWSSDK com NuGetO NuGet é um sistema de gerenciamento de pacotes para a plataforma .NET. Com o NuGet, é possíveladicionar os conjuntos do AWSSDK, bem como várias outras extensões, ao seu aplicativo. Para obterinformações adicionais, consulte o repositório aws/dotnet no GitHub.
O NuGet sempre tem as versões mais recentes dos conjuntos do AWSSDK, e também permite ainstalação de versões anteriores. O NuGet está ciente das dependências entre os conjuntos e instala todosos conjuntos necessários automaticamente. Os conjuntos instalados com o NuGet são armazenados coma solução em vez de um local central, como o diretório Arquivos de programas. Isso permite a instalaçãode versões do conjunto específicas para um certo aplicativo, sem criar problemas de compatibilidade paraoutros aplicativos. Para obter mais informações sobre o NuGet, consulte a documentação do NuGet.
O NuGet é instalado automaticamente com o Visual Studio 2010 ou posterior. Se estiver usando umaversão antiga do Visual Studio, instale o NuGet a partir da galeria do Visual Studio em MSDN.
Pacotes do AWSSDK do NuGetO site do NuGet oferece uma página para cada pacote disponível por meio do NuGet. A página decada pacote inclui uma amostra de linha de comando para instalação do pacote usando o Consoledo gerenciador de pacotes. Cada página também inclui uma lista das versões anteriores do pacotedisponíveis por meio do NuGet. Para obter uma lista dos pacotes do AWSSDK disponíveis a partir doNuGet, consulte Pacotes do AWSSDK.
15
AWS SDK para .NET Guia do desenvolvedorInstalação de conjuntos de AWSSDK com NuGet
Usar o NuGet pela linha de comando ou pelo terminal1. Acesse os pacotes NuGet para a AWS e determine quais pacotes NuGet são necessários em seu
projeto. Por exemplo, AWSSDK.S3.2. Copie o comando da CLI do .NET da página da web desse pacote. Por exemplo:
dotnet add package AWSSDK.S3 --version 3.3.110.19
3. No diretório do projeto, execute esse comando da CLI do .NET.
Usar o NuGet no Gerenciador de Soluções1. No Solution Explorer (Gerenciador de Soluções), clique com o botão direito no projeto e selecione
Manage NuGet Packages (Gerenciar pacotes NuGet) no menu de contexto.2. No painel esquerdo do NuGet Package Manager (Gerenciador de pacotes NuGet), escolha Browse
(Procurar). É possível usar a caixa de pesquisa para procurar o pacote que deseja instalar.
A figura a seguir mostra a instalação do pacote AWSSDK.S3. O NuGet instala automaticamentequalquer dependência, que neste caso é o pacote AWSSDK.Core.
Usar o NuGet a partir do Console de gerenciamento de pacotesNo menu Tools (Ferramentas) do Visual Studio, escolha NuGet Package Manager (Gerenciador depacotes NuGet), Package Manager Console (Console do gerenciador de pacotes).
Instale os conjuntos do AWSSDK desejados a partir do Console de gerenciamento de pacotes usando ocomando Install-Package . Por exemplo, para instalar o AWSSDK.S3, use o comando a seguir.
PM> Install-Package AWSSDK.S3
O NuGet também instala quaisquer dependências, como o AWSSDK.Core.
Se você precisar instalar uma versão anterior de um pacote, use a opção -Version e especifique aversão desejada do pacote. Por exemplo:
16
AWS SDK para .NET Guia do desenvolvedorInstalar o AWS SDK para .NET no Windows
PM> Install-Package AWSSDK.S3 -Version 3.3.106.6
Para obter mais informações sobre comandos do Console do gerenciador de pacotes, consulte areferência do PowerShell na documentação do NuGet da Microsoft.
Instalar o AWS SDK para .NET no WindowsO método preferencial de instalação do AWS SDK para .NET no Windows é instalar pacotes AWSSDKNuGet conforme necessário. Isso está descrito nas seções anteriores deste tópico (p. 15).
Use o NuGet para instalar conjuntos de serviço individuais do AWSSDK e extensões para o SDK.Note
Se você for solicitado a instalar um MSI em vez de usar o NuGet, é possível encontrar o MSIlegado em https://sdk-for-net.amazonwebservices.com/latest/AWSToolsAndSDKForNet.msi. Porpadrão, o AWS SDK para .NET é instalado no diretório Program Files, o que requer privilégiosde administrador. Para instalar o SDK sem ser administrador, selecione um diretório de instalaçãodiferente.
Iniciar um novo projetoHá várias técnicas que podem ser usadas para iniciar um novo projeto que acesse serviços da AWS.Algumas dessas técnicas são mostradas abaixo.
• É possível iniciar um projeto básico usando a CLI do .NET. Para fazer isso, abra uma linha de comandoou terminal, crie uma pasta ou um diretório, vá para lá e digite:
dotnet new console
Um projeto simples "Olá mundo" será criado, ao qual você poderá adicionar código e pacotes NuGet.Para obter mais informações, consulte o Guia do .NET Core.
• O AWS Toolkit for Visual Studio inclui modelos de projeto em C# para uma variedade de serviços daAWS. Depois que tiver instalado o toolkit no Visual Studio, você poderá acessar os modelos ao criar umprojeto.
Para ver isso, acesse Trabalhar com serviços da AWS no Guia do usuário do AWS Toolkit for VisualStudio. Vários exemplos nesse tópico criam projetos.
Plataformas que oferecem suporte ao AWS SDKpara .NET
O AWS SDK para .NET fornece grupos distintos de conjuntos para desenvolvedores direcionarem adiferentes plataformas. Contudo, nem toda funcionalidade do SDK é a mesma em cada uma dessasplataformas. Este tópico descreve as diferenças no suporte para cada plataforma.
.NET CoreO AWS SDK para .NET oferece suporte a aplicativos gravados para .NET Core. Clientes do serviço daAWS só oferecem suporte a padrões de chamada assíncrona no .NET Core. Isso também afeta várias das
17
AWS SDK para .NET Guia do desenvolvedor.NET Framework 4.5
abstrações de alto nível criadas sobre clientes de serviços, como o TransferUtility do Amazon S3,que só oferece suporte a chamadas assíncronas no ambiente .NET Core. Para obter detalhes, consulteConfiguração do AWS SDK para .NET com .NET Core (p. 20).
.NET Framework 4.5Esta versão do AWS SDK para .NET é compilada no .NET Framework 4.5 e executada no tempo deexecução do .NET 4.0. Os clientes do serviço da AWS oferecem suporte a padrões de chamada síncronae assíncrona e usam as palavras-chave async e await introduzidas no C# 5.0.
.NET Framework 3.5Esta versão do AWS SDK para .NET é compilada no .NET Framework 3.5 e executada no tempo deexecução do .NET 2.0 ou .NET 4.0. Os clientes do serviço da AWS oferecem suporte a padrões dechamada síncrona e assíncrona e usam o padrão Begin e End.
Note
O AWS SDK para .NET não é compatível com FIPS (Federal Information Processing Standard)quando usado por aplicativos criados na versão 2.0 do CLR. Para obter detalhes sobre comosubstituir uma implementação compatível com FIPS nesse ambiente, consulte CryptoConfig noblog da Microsoft e a classe HMACSHA256 da equipe de segurança de CLR (HMACSHA256Cng)em Security.Cryptography.dll.
Biblioteca de classe portátilO AWS SDK para .NET também contém uma implementação de biblioteca de classes portátil. Aimplementação da biblioteca de classes portátil pode ser destinada a várias plataformas, incluindoUniversal Windows Platform (UWP) e Xamarin em iOS e Android. Consulte o AWS Mobile SDK para .NETand Xamarin para obter mais detalhes. Os clientes do serviço da AWS só oferecem suporte a padrões dechamada assíncrona.
Suporte de unidadeO AWS SDK para .NET oferece suporte à geração de conjuntos da unidade. Mais informações podem serencontradas em Unity README.
Mais informações• Migrar para a versão 3 do AWS SDK para .NET (p. 60)•
This is prerelease documentation for a feature in preview release. It is subject to change.
Migrar para a versão 3.5 do AWS SDK para .NET (p. 62)
18
AWS SDK para .NET Guia do desenvolvedorConfigurar seu aplicativo
Programar com o AWS SDKpara .NET
Esta seção fornece informações gerais sobre o desenvolvimento de softwares com o AWS SDK para .NET.
Para obter informações sobre o software com para serviços da AWS específicos, consulte Exemplos decódigo (p. 66).
Tópicos• Configurar seu aplicativo AWS SDK para .NET (p. 19)• APIs assíncronas da AWS para .NET (p. 51)• Tentativas e tempos limite (p. 59)• Migrar para a versão 3 do AWS SDK para .NET (p. 60)• Migrar para a versão 3.5 do AWS SDK para .NET (p. 62)• Migração do .NET Standard 1.3 (p. 64)
Configurar seu aplicativo AWS SDK para .NETÉ possível configurar seu aplicativo AWS SDK para .NET para especificar opções de login, endpoints ousuporte ao Signature versão 4 com o Amazon S3.
A maneira recomendada de configurar um aplicativo é usar o elemento <aws> no arquivo App.configou Web.config do projeto. O exemplo a seguir especifica os parâmetros AWSRegion (p. 35) eAWSLogging (p. 34).
<configuration> <configSections> <section name="aws" type="Amazon.AWSSection, AWSSDK.Core"/> </configSections> <aws region="us-west-2"> <logging logTo="Log4Net"/> </aws></configuration>
Outra maneira de configurar um aplicativo é editar o elemento <appSettings> no arquivo App.configou Web.config do projeto. O exemplo a seguir especifica os parâmetros AWSRegion (p. 35) eAWSLogging (p. 34).
<configuration> <appSettings> <add key="AWSRegion" value="us-west-2"/> <add key="AWSLogging" value="log4net"/> </appSettings></configuration>
Essas configurações só entram em vigor depois de o aplicativo ser reconstruído.
19
AWS SDK para .NET Guia do desenvolvedorConfigurar o AWS SDK para .NET com .NET Core
Embora seja possível configurar um aplicativo AWS SDK para .NET programaticamente ao definirvalores de propriedade na classe AWSConfigs, recomendamos usar o elemento aws. O exemplo a seguirespecifica os parâmetros AWSRegion (p. 35) e AWSLogging (p. 34):
AWSConfigs.AWSRegion = "us-west-2";AWSConfigs.Logging = LoggingOptions.Log4Net;
Parâmetros definidos programaticamente substituem todos os valores especificados em um arquivoApp.config ou Web.config. Alguns valores de parâmetros definidos programaticamente serãoimplementados no mesmo momento; outros serão implementados somente depois de criar um novo objetodo cliente.
Tópicos• Configurar o AWS SDK para .NET com .NET Core (p. 20)• Configurar as credenciais da AWS (p. 23)• Seleção da região da AWS (p. 32)• Configuração de outros parâmetros do aplicativo (p. 33)• Referência dos arquivos de configuração para o AWS SDK para .NET (p. 39)• Habilitar o Métricas do SDK (p. 47)
Configurar o AWS SDK para .NET com .NET CoreUma das principais alterações no .NET Core é a retirada do ConfigurationManager e dos arquivospadrão app.config e web.config usados nos aplicativos .NET Framework e ASP.NET.
A configuração no .NET Core é baseada em pares de chave/valor estabelecidos pelos provedores deconfiguração. Os provedores de configuração leem dados de configuração em pares de chave/valorde uma variedade de fontes de configuração, incluindo argumentos de linha de comando, arquivos dediretório, variáveis de ambiente e arquivos de configurações.
Note
Para obter mais informações, consulte Configuração no ASP.NET Core.
Para facilitar o uso do AWS SDK para .NET com o .NET Core, use o pacote NuGetAWSSDK.Extensions.NETCore.Setup. Como várias bibliotecas do .NET Core, ele adiciona métodos deextensão à interface IConfiguration para tornar direta a obtenção da configuração da AWS.
Usar o AWSSDK.Extensions.NETCore.SetupQuando você cria um aplicativo ASP.NET Core MVC no Visual Studio, o construtor do Startup.cslida com a configuração lendo várias fontes de entrada de provedores de configuração, por exemplo,appsettings.json.
public Startup(IConfiguration configuration){ Configuration = configuration;}
Para usar o objeto Configuration a fim de obter as opções da AWS, primeiro adicione o pacote NuGetAWSSDK.Extensions.NETCore.Setup. Em seguida, adicione as opções ao arquivo de configuração.Observe que um dos arquivos adicionados ao ConfigurationBuilder se chama $"appsettings.{env.EnvironmentName}.json". Se observar a guia Debug (Depurar) nas propriedades do projeto,note que esse arquivo está definido como Desenvolvimento. Isso funciona muito bem para testes locais,
20
AWS SDK para .NET Guia do desenvolvedorConfigurar o AWS SDK para .NET com .NET Core
pois é possível colocar a configuração no arquivo appsettings.Development.json, que é somenteleitura durante o teste local. Ao implantar uma instância do Amazon EC2 que tenha o EnvironmentNamedefinido como Produção, esse arquivo é ignorado e o AWS SDK para .NET retorna à região e àscredenciais do IAM configuradas para a instância do Amazon EC2.
As definições de configuração a seguir mostram exemplos dos valores que você pode incluir no arquivoappsettings.Development.json em seu projeto para fornecer as configurações da AWS.
{ "AWS": { "Profile": "local-test-profile", "Region": "us-west-2" }, "SupportEmail": "[email protected]"}
Para acessar uma configuração em um arquivo CSHTML, use a diretiva Configuration:
@using Microsoft.Extensions.Configuration@inject IConfiguration Configuration
<h1>Contact</h1>
<p> <strong>Support:</strong> <a href='mailto:@Configuration["SupportEmail"]'>@Configuration["SupportEmail"]</a><br /></p>
Para acessar as opções da AWS definidas no arquivo do código, chame o método de extensãoGetAWSOptions adicionado em IConfiguration.
Para construir um cliente de serviço a partir dessas opções, chame CreateServiceClient. O código deexemplo a seguir mostra como criar um cliente de serviço do Amazon S3.
var options = Configuration.GetAWSOptions();IAmazonS3 client = options.CreateServiceClient<IAmazonS3>();
Também é possível criar vários clientes de serviço com configurações incompatíveis usando váriasentradas no arquivo appsettings.Development.json, conforme mostrado nos exemplos a seguir, emque a configuração de service1 inclui a região us-west-2 e a configuração de service2 inclui o URLdo endpoint especial.
{ "service1": { "Profile": "default", "Region": "us-west-2" }, "service2": { "Profile": "default", "ServiceURL": "URL" }}
Depois, você pode obter as opções para um serviço específico usando a entrada no arquivo JSON. Porexemplo, para obter as configurações de service1:
var options = Configuration.GetAWSOptions("service1");
21
AWS SDK para .NET Guia do desenvolvedorConfigurar o AWS SDK para .NET com .NET Core
Valores permitidos no arquivo appsettings
Os valores de configuração do aplicativo a seguir podem ser definidos no arquivoappsettings.Development.json. Os nomes de campo devem usar a capitalização mostrada na listaabaixo. Para obter detalhes sobre essas configurações, consulte a classe AWS.Runtime.ClientConfig.
• Região• Perfil• ProfilesLocation• SignatureVersion• RegionEndpoint• UseHttp• ServiceURL• AuthenticationRegion• AuthenticationServiceName• MaxErrorRetry• LogResponse• BufferSize• ProgressUpdateInterval• ResignRetries• AllowAutoRedirect• LogMetrics• DisableLogging• UseDualstackEndpoint
Injeção de dependência no núcleo do ASP.NETO pacote NuGet AWSSDK.Extensions.NETCore.Setup também se integra a um novo sistema de injeçãode dependência no núcleo do ASP.NET. O método ConfigureServices em Startup é o local ondeos serviços MVC são adicionados. Se o aplicativo usa a Estrutura de entidade, também é aqui que ela éinicializada.
public void ConfigureServices(IServiceCollection services){ // Add framework services. services.AddMvc();}
Note
O histórico sobre a injeção de dependência no .NET Core está disponível no .NET Coresite dedocumentação do .
O pacote NuGet AWSSDK.Extensions.NETCore.Setup adiciona novos métodos de extensãoao IServiceCollection que podem ser usados para adicionar serviços da AWS à injeçãode dependência. O código a seguir mostra como adicionar as opções da AWS lidas a partir deIConfiguration para adicionar o Amazon S3 e o DynamoDB à lista de serviços.
public void ConfigureServices(IServiceCollection services){ // Add framework services.
22
AWS SDK para .NET Guia do desenvolvedorConfigurar as credenciais da AWS
services.AddMvc();
services.AddDefaultAWSOptions(Configuration.GetAWSOptions()); services.AddAWSService<IAmazonS3>(); services.AddAWSService<IAmazonDynamoDB>();}
Agora, se os controladores MVC usam IAmazonS3 ou IAmazonDynamoDB como parâmetros em seusconstrutores, o sistema de injeção de dependência passa nesses serviços.
public class HomeController : Controller{ IAmazonS3 S3Client { get; set; }
public HomeController(IAmazonS3 s3Client) { this.S3Client = s3Client; }
...
}
Configurar as credenciais da AWSGerencie as credenciais da AWS de forma segura e evite práticas que possam expor involuntariamenteas credenciais ao público. Neste tópico, descrevemos como configurar as credenciais da AWS do seuaplicativo para que elas permaneçam seguras.
• Não use as credenciais raiz da sua conta para acessar os recursos da AWS. Estas credenciais fornecemacesso ilimitado à conta e são difíceis de revogar.
• Não coloque chaves de acesso literais no aplicativo, incluindo os arquivos App.config ouWeb.config do projeto. Se colocar, criará um risco de exposição acidental das credenciais se, porexemplo, fizer upload do projeto em um repositório público.
Note
Presumimos que você criou uma conta da AWS e tem acesso às credenciais. Caso ainda nãotenha feito, consulte Criar uma conta da AWS e credenciais (p. 14).
Veja a seguir orientações gerais para gerenciar credenciais com segurança:
• Crie usuários do IAM e use as credenciais destes usuários em vez de usar o seu usuário raiz da AWS.Credenciais de usuário do IAM são fáceis de revogar se forem comprometidas. Aplique uma política paracada usuário do IAM que restringe o usuário a um conjunto específico de recursos e ações.
• Durante o desenvolvimento do aplicativo, a abordagem preferencial para gerenciar credenciais é colocarum perfil para cada conjunto de credenciais de usuário do IAM no SDK Store. Também é possível usarum arquivo de credenciais de texto simples para armazenar perfis que contêm credenciais. Em seguida,faça referência a um perfil específico de forma programática em vez de armazenar as credenciais nosarquivos de projeto. Para limitar o risco de exposição involuntária das credenciais, armazene o SDKStore ou arquivo de credenciais separadamente dos arquivos de projeto.
• Use IAM Roles for Tasks (Funções do IAM para tarefas) do Amazon Elastic Container Service (AmazonECS).
• Use funções do IAM para aplicativos em execução nas instâncias do Amazon EC2.• Use credenciais temporárias ou variáveis de ambiente para aplicativos disponíveis para usuários de fora
da organização.
23
AWS SDK para .NET Guia do desenvolvedorConfigurar as credenciais da AWS
Os tópicos a seguir descrevem como gerenciar as credenciais em um aplicativo do AWS SDK para .NET.Para uma discussão sobre como gerenciar as credenciais da AWS com segurança, consulte BestPractices for Managing AWS Access Keys (Melhores práticas de gerenciamento de chaves de acesso daAWS).
Usar a SDK StoreDurante o desenvolvimento do aplicativo do AWS SDK para .NET, adicione um perfil ao SDK Storepara cada conjunto de credenciais que deseja usar no aplicativo. Isso evita a exposição acidental dascredenciais da AWS. O SDK Store está localizado na pasta C:\Users\<username>\AppData\Local\AWSToolkit no arquivo RegisteredAccounts.json. O SDK Store oferece os seguintes benefícios:
• O SDK Store pode conter diversos perfis de qualquer número de contas.• As credenciais no SDK Store são criptografadas, e o SDK Store reside no diretório base do usuário. Isso
limita o risco de exposição acidental das credenciais.• Referencie o perfil pelo nome no aplicativo e as credenciais associadas são referenciadas durante o
tempo de execução. Os arquivos de código-fonte nunca contêm as credenciais.• Se incluir um perfil chamado default, o AWS SDK para .NET usará esse perfil. Isso também será
válido se não fornecer outro nome de perfil, ou se o nome especificado não for encontrado.• O SDK Store também oferece credenciais para o AWS Tools para Windows PowerShell e o AWS Toolkit
for Visual Studio.
Note
Os perfis do SDK Store são específicos para um determinado usuário em um host particular.Eles não podem ser copiados para outros hosts ou usuários. Por este motivo, não é possívelusar os perfis do SDK Store nos aplicativos de produção. Para obter mais informações, consulteResolução de perfil e credencial (p. 29).
Gerencie os perfis no SDK Store de diversas formas.
• Use a interface gráfica de usuário (GUI) no AWS Toolkit for Visual Studio para gerenciar perfis. Paraobter mais informações sobre a adição de credenciais ao SDK Store usando a GUI, consulte Forneceras credenciais da AWS no AWS Toolkit for Visual Studio.
• Gerencie os perfis a partir da linha de comando usando o cmdlet Set-AWSCredentials no AWS Toolspara Windows PowerShell. Para obter mais informações, consulte Using AWS Credentials (Uso decredenciais da AWS).
• Crie e gerencie os perfis de forma programática usando a classeAmazon.Runtime.CredentialManagement.CredentialProfile.
Os exemplos a seguir mostram como criar um perfil básico e um perfil SAML e adicioná-los ao SDK Storeusando o método RegisterProfile.
Criar um perfil e salvá-lo no arquivo de credenciais .NET
Crie um objeto Amazon.Runtime.CredentialManagement.CredentialProfileOptionse defina suas propriedades AccessKey e SecretKey. Crie um objetoAmazon.Runtime.CredentialManagement.CredentialProfile. Forneça o nome do perfil e o objetoCredentialProfileOptions criado. Opcionalmente, defina a propriedade Região para o perfil.Instancie um objeto NetSDKCredentialsFile e chame o método RegisterProfile para registrar o perfil.
var options = new CredentialProfileOptions{ AccessKey = "access_key", SecretKey = "secret_key"
24
AWS SDK para .NET Guia do desenvolvedorConfigurar as credenciais da AWS
};var profile = new Amazon.Runtime.CredentialManagement.CredentialProfile("basic_profile", options);profile.Region = RegionEndpoint.USWest1;var netSDKFile = new NetSDKCredentialsFile();netSDKFile.RegisterProfile(profile);
O método RegisterProfile é usado para registrar um novo perfil. O aplicativo normalmente chamaesse método somente uma vez para cada perfil.
Criar um SAMLEndpoint e um perfil associado e salvá-lo no arquivo decredenciais .NET
Crie um objeto Amazon.Runtime.CredentialManagement.SAMLEndpoint. Forneça os parâmetros de nomee URI do endpoint. Crie um objeto Amazon.Runtime.CredentialManagement.SAMLEndpointManager.Chame o método RegisterEndpoint para registrar o endpoint. Crie um objetoAmazon.Runtime.CredentialManagement.CredentialProfileOptions e defina as propriedadesEndpointName e RoleArn. Crie um objeto Amazon.Runtime.CredentialManagement.CredentialProfilee forneça o nome do perfil e o objeto CredentialProfileOptions criado. Opcionalmente, definaa propriedade Região para o perfil. Instancie um objeto NetSDKCredentialsFile e chame o métodoRegisterProfile para registrar o perfil.
var endpoint = new SAMLEndpoint("endpoint1", new Uri("https://some_saml_endpoint"), SAMLAuthenticationType.Kerberos);var endpointManager = new SAMLEndpointManager();endpointManager.RegisterEndpoint(endpoint);options = new CredentialProfileOptions{ EndpointName = "endpoint1", RoleArn = "arn:aws:iam::999999999999:role/some-role"};profile = new CredentialProfile("federated_profile", options);netSDKFile = new NetSDKCredentialsFile();netSDKFile.RegisterProfile(profile);
Usar um arquivo de credenciaisTambém é possível armazenar perfis em um arquivo compartilhado de credenciais da AWS. Este arquivopode ser usado pelos outros AWS SDKs, a AWS CLI e o AWS Tools para Windows PowerShell. Parareduzir o risco de exposição acidental das credenciais, armazene o arquivo de credenciais separadamentede quaisquer arquivos de projeto, geralmente na pasta inicial do usuário. Esteja ciente de que os perfis nosarquivos de credenciais são armazenados em texto simples.
Por padrão, esse arquivo está localizado no diretório .aws dentro de seu diretório inicial e é chamadocredentials. Para obter mais informações, consulte Onde as configurações são armazenadas? no Guiado usuário do AWS Command Line Interface.
Os perfis podem ser gerenciados no arquivo de credenciais compartilhado de duas formas:
• Você pode usar um editor de texto. O arquivo se chama credentials, e o local padrão é na pastainicial do usuário. Por exemplo, se o nome de usuário for awsuser, o arquivo de credenciais será C:\users\awsuser\.aws\credentials.
Veja a seguir um exemplo de um perfil no arquivo de credenciais.
[{profile_name}]aws_access_key_id = {accessKey}aws_secret_access_key = {secretKey}
25
AWS SDK para .NET Guia do desenvolvedorConfigurar as credenciais da AWS
Para obter mais informações, consulte Práticas recomendadas de gerenciamento de chaves de acessoda AWS.
Note
Se você incluir um perfil chamado default, o AWS SDK para .NET usará esse perfil porpadrão se não conseguir encontrar o perfil especificado.
Armazene o arquivo de credenciais que contém os perfis em um local de sua escolha, como C:\aws_service_credentials\credentials. Depois, especifique o caminho de arquivo no atributoAWSProfilesLocation no arquivo App.config ou Web.config do projeto. Para obter maisinformações, consulte Especificação de um perfil (p. 30).
• Gerencie o arquivo de credenciais de forma programática usando as classes no namespaceAmazon.Runtime.CredentialManagement.
Como configurar um perfil de credenciais alternativoPor padrão, o AWS SDK para .NET usa o perfil padrão, mas é possível alterar o perfil usado no arquivo decredenciais usando a variável de ambiente AWS_Profile.
Por exemplo, no Linux, macOS, or Unix, execute o comando a seguir a fim de alterar o perfil paramyProfile.
export AWS_PROFILE="myProfile"
No Windows, use o seguinte comando:
set AWS_PROFILE=myProfile
Definir a variável de ambiente AWS_PROFILE afeta o carregamento da credencial em todos os SDKs eferramentas da AWS compatíveis oficialmente, inclusive a CLI da AWS e a CLI da AWS para PowerShell.
Note
A variável de ambiente tem precedência sobre a propriedade do sistema.
Criar um perfil e salvá-lo no arquivo de credenciais compartilhadoCrie um objeto Amazon.Runtime.CredentialManagement.CredentialProfileOptionse defina suas propriedades AccessKey e SecretKey. Crie um objetoAmazon.Runtime.CredentialManagement.CredentialProfile. Forneça o nome do perfil e oCredentialProfileOptions criado. Opcionalmente, defina a propriedade Região para o perfil.Instancie um objeto Amazon.Runtime.CredentialManagement.SharedCredentialsFile e chame o métodoRegisterProfile para registrar o perfil.
options = new CredentialProfileOptions{ AccessKey = "access_key", SecretKey = "secret_key"};profile = new CredentialProfile("shared_profile", options);profile.Region = RegionEndpoint.USWest1;var sharedFile = new SharedCredentialsFile();sharedFile.RegisterProfile(profile);
O método RegisterProfile é usado para registrar um novo perfil. O aplicativo normalmente chamaráeste método somente uma vez para cada perfil.
26
AWS SDK para .NET Guia do desenvolvedorConfigurar as credenciais da AWS
Criar um perfil de origem e um perfil de função de admissão associado e salvá-lono arquivo de credenciais
Crie um objeto Amazon.Runtime.CredentialManagement.CredentialProfileOptionspara o perfil de origem e defina as propriedades AccessKey e SecretKey. Crieum objeto Amazon.Runtime.CredentialManagement.CredentialProfile. Forneçao nome do perfil e o CredentialProfileOptions criado. Instancie um objetoAmazon.Runtime.CredentialManagement.SharedCredentialsFile e chame o método RegisterProfile pararegistrar o perfil. Crie outro objeto Amazon.Runtime.CredentialManagement.CredentialProfileOptions parao perfil de função de admissão e defina as propriedades SourceProfile e RoleArn para o perfil. Crieum objeto Amazon.Runtime.CredentialManagement.CredentialProfile para a função de admissão. Forneçao nome do perfil e o CredentialProfileOptions criado.
// Create the source profile and save it to the shared credentials filevar sourceProfileOptions = new CredentialProfileOptions{ AccessKey = "access_key", SecretKey = "secret_key"};var sourceProfile = new CredentialProfile("source_profile", sourceProfileOptions);sharedFile = new SharedCredentialsFile();sharedFile.RegisterProfile(sourceProfile);
// Create the assume role profile and save it to the shared credentials filevar assumeRoleProfileOptions = new CredentialProfileOptions{ SourceProfile = "source_profile", RoleArn = "arn:aws:iam::999999999999:role/some-role"};var assumeRoleProfile = new CredentialProfile("assume_role_profile", assumeRoleProfileOptions);sharedFile.RegisterProfile(assumeRoleProfile);
Atualizar um perfil existente no arquivo de credenciais compartilhado
Crie um objeto Amazon.Runtime.CredentialManagement.SharedCredentialsFile. Defina os propriedadesRegion, AccessKey e SecretKey para o perfil. Chame o método TryGetProfile. Se o perfil existe, useuma instância Amazon.Runtime.CredentialManagement.SharedCredentialsFile para chamar o métodoRegisterProfile para registrar o perfil atualizado.
sharedFile = new SharedCredentialsFile();CredentialProfile basicProfile;if (sharedFile.TryGetProfile("basicProfile", out basicProfile)){ basicProfile.Region = RegionEndpoint.USEast1; basicProfile.Options.AccessKey = "different_access_key"; basicProfile.Options.SecretKey = "different_secret_key";
sharedFile.RegisterProfile(basicProfile);}
Acessar credenciais e perfis em um aplicativoÉ possível localizar as credenciais e os perfis com facilidade no arquivo decredenciais .NET ou no arquivo de credenciais compartilhado usando a classeAmazon.Runtime.CredentialManagement.CredentialProfileStoreChain. Esta é a forma que o .NET SDKprocura credenciais e perfis. A classe CredentialProfileStoreChain verifica automaticamenteambos os arquivos de credenciais.
27
AWS SDK para .NET Guia do desenvolvedorConfigurar as credenciais da AWS
É possível obter as credenciais ou perfis usando os métodos TryGetAWSCredentials ou TryGetProfile.A propriedade ProfilesLocation determina o comportamento do CredentialsProfileChain, daseguinte forma:
1. Se ProfilesLocation é não nula e não vazia, pesquise o arquivo de credenciais compartilhado nocaminho do disco na propriedade ProfilesLocation.
2. Se ProfilesLocation é nula ou vazia e a plataforma oferecer suporte para o arquivo decredenciais .NET, pesquise este arquivo. Se o perfil não for encontrado, pesquise o arquivo decredenciais compartilhado no local padrão.
3. Se ProfilesLocation é nula ou vazia e a plataforma não oferece suporte para o arquivo decredenciais .NET, pesquise o arquivo de credenciais compartilhado no local padrão.
Obter credenciais do arquivo de credenciais SDK ou do arquivo de credenciaiscompartilhado no local padrão.
Crie um objeto CredentialProfileStoreChain e um objeto Amazon.Runtime.AWSCredentials.Chame o método TryGetAWSCredentials. Forneça o nome do perfil e o objeto AWSCredentials noqual retornar as credenciais.
var chain = new CredentialProfileStoreChain();AWSCredentials awsCredentials;if (chain.TryGetAWSCredentials("basic_profile", out awsCredentials)){ // use awsCredentials}
Obter um perfil do arquivo de credenciais SDK ou do arquivo de credenciaiscompartilhado no local padrão
Crie um objeto CredentialProfileStoreChain e um objetoAmazon.Runtime.CredentialManagement.CredentialProfile. Chame o método TryGetProfile e forneça onome do perfil e o objeto CredentialProfile no qual retornar as credenciais.
var chain = new CredentialProfileStoreChain();CredentialProfile basicProfile;if (chain.TryGetProfile("basic_profile", out basicProfile)){ // Use basicProfile}
Obter AWSCredentials de um arquivo no formato do arquivo de credenciaiscompartilhado em um local de arquivos
Crie um objeto CredentialProfileStoreChain e forneça o caminho para o arquivo de credenciais.Crie um objeto AWSCredentials. Chame o método TryGetAWSCredentials. Forneça o nome do perfile o objeto AWSCredentials no qual retornar as credenciais.
var chain = new CredentialProfileStoreChain("c:\\Users\\sdkuser\\customCredentialsFile.ini");AWSCredentials awsCredentials;if (chain.TryGetAWSCredentials("basic_profile", out awsCredentials)){ // Use awsCredentials}
28
AWS SDK para .NET Guia do desenvolvedorConfigurar as credenciais da AWS
Como criar um AmazonS3Client usando a classe SharedCredentialsFile
Crie um objeto AmazonS3Client que usa as credenciais para um perfil específico ao usar a classeAmazon.Runtime.CredentialManagement.SharedCredentialsFile. O AWS SDK para .NET carrega ascredenciais contidas no perfil automaticamente. Faça isso se desejar usar um perfil específico para umcerto cliente, diferente do profile especificado em App.Config.
CredentialProfile basicProfile;AWSCredentials awsCredentials;var sharedFile = new SharedCredentialsFile();if (sharedFile.TryGetProfile("basic_profile", out basicProfile) && AWSCredentialsFactory.TryGetAWSCredentials(basicProfile, sharedFile, out awsCredentials)){ using (var client = new AmazonS3Client(awsCredentials, basicProfile.Region)) { var response = client.ListBuckets(); }}
Se desejar usar o perfil padrão e quiser que o AWS SDK para .NET use as credenciais padrãoautomaticamente para criar o objeto cliente, use o código a seguir.
using (var client = new AmazonS3Client(RegionEndpoint.US-West2)){ var response = client.ListBuckets();}
Resolução de perfil e credenciaisO AWS SDK para .NET busca credenciais na ordem a seguir e usa o primeiro conjunto disponível para oaplicativo atual.
1. A configuração do cliente, ou o que for explicitamente definido no cliente de serviço da AWS.2. BasicAWSCredentials criadas dos valores AWSAccessKey e AWSSecretKey de AppConfig, se
estiverem disponíveis.3. Um perfil de credenciais com o nome especificado por um valor em AWSConfigs.AWSProfileName
(definido explicitamente ou em AppConfig).4. O perfil de credenciais default.5. SessionAWSCredentials criadas das variáveis de ambiente AWS_ACCESS_KEY_ID,
AWS_SECRET_ACCESS_KEY e AWS_SESSION_TOKEN, se forem todas não vazias.6. BasicAWSCredentials criadas das variáveis de ambiente AWS_ACCESS_KEY_ID e
AWS_SECRET_ACCESS_KEY, se ambas forem não vazias.7. Funções do IAM para tarefas para tarefas do Amazon ECS.8. Metadados da instância do EC2.
Os perfis do SDK Store são específicos para um determinado usuário em um host particular. Não épossível copiá-los para outros hosts nem outros usuários. Por esse motivo, não é possível reutilizar osperfis do SDK Store que estiverem na máquina de desenvolvimento em outros hosts ou outras máquinasde desenvolvedores. Se o aplicativo estiver em execução em uma instância do Amazon EC2, como emum ambiente de produção, use uma função do IAM conforme descrito em Como usar funções do IAMpara instâncias do EC2 com o AWS SDK para .NET (p. 138). Caso contrário, como no teste de pré-lançamento, armazene as credenciais em um arquivo de credenciais ao qual o aplicativo web tenhaacesso no servidor.
29
AWS SDK para .NET Guia do desenvolvedorConfigurar as credenciais da AWS
Resolução do perfil
Com dois tipos diferentes de arquivo de credenciais, é importante entender como configuraro AWS SDK para .NET e o AWS Tools para Windows PowerShell para usá-los. OAWSConfigs.AWSProfilesLocation (definido explicitamente ou em AppConfig) controla comoo AWS SDK para .NET encontra os perfis de credenciais. O argumento da linha de comando -ProfileLocation controla como o AWS Tools para Windows PowerShell encontra um perfil. Veja comofunciona a configuração em ambos os casos.
Valor do local do perfil Comportamento da resolução do perfil
nulo (não definido) ou vazio Primeiro, pesquise o arquivo de credenciais .NETpara um perfil com o nome especificado. Se operfil não for encontrado, pesquise %HOME%\.aws\credentials. Se o perfil não for encontrado,pesquise %HOME%\.aws\config.
O caminho para um arquivo no formato de arquivode credenciais compartilhado
Pesquise somente o arquivo especificado para umperfil com o nome especificado.
Especificar um perfil
Os perfis são a forma preferencial de uso das credenciais em um aplicativo do AWS SDK para .NET. Nãoé necessário especificar o local de armazenamento do perfil. Faça referência ao perfil somente pelo nome.O AWS SDK para .NET recupera as credenciais correspondentes, conforme descrito na seção anterior.
A melhor maneira de especificar um perfil é definir um valor de AWSProfileName na seçãoappSettings dos arquivos App.config ou Web.config do aplicativo. As credenciais associadas sãoincorporadas ao aplicativo durante o processão de compilação.
O exemplo a seguir especifica um perfil chamado development.
<configuration> <appSettings> <add key="AWSProfileName" value="development"/> </appSettings></configuration>
Este exemplo assume que o perfil existe no SDK Store ou em um arquivo de credenciais no local padrão.
Se os perfis estão armazenados em um arquivo de credenciais em outro local, especifique o localadicionando um valor de atributo AWSProfilesLocation no elemento <appSettings>. O exemplo aseguir especifica C:\aws_service_credentials\credentials como arquivo de credenciais.
<configuration> <appSettings> <add key="AWSProfileName" value="development"/> <add key="AWSProfilesLocation" value="C:\aws_service_credentials\credentials"/> </appSettings></configuration>
Para integralidade, a maneira alternativa obsoleta para especificar um perfil é mostrada abaixo, mas elanão é recomendada.
<configuration> <configSections>
30
AWS SDK para .NET Guia do desenvolvedorConfigurar as credenciais da AWS
<section name="aws" type="Amazon.AWSSection, AWSSDK.Core"/> </configSections> <aws profileName="development" profilesLocation="C:\aws_service_credentials\credentials"/></configuration>
<configuration> <configSections> <section name="aws" type="Amazon.AWSSection,AWSSDK.Core"/> </configSections> <aws profileName="development" profilesLocation="C:\aws_service_credentials\credentials"/></configuration>
Usar credenciais da conta de usuário federado
Os aplicativos que usam o AWS SDK para .NET (AWSSDK.Core versão 3.1.6.0 ou posterior) podemusar contas de usuário federado por meio do Active Directory Federation Services (AD FS - Serviços defederação do Active Directory) para acessar web services da AWS usando o Security Assertion MarkupLanguage (SAML).
Suporte ao acesso federado significa que usuários podem se autenticar usando o Active Directory.São concedidas credenciais temporárias ao usuário automaticamente. Estas credenciais temporárias,que são válidas por uma hora, são usadas quando o aplicativo invoca os serviços web da AWS. OSDK faz o gerenciamento das credenciais temporárias. Para contas de usuário associados a umdomínio, se o aplicativo realizar uma chamada mas as credenciais expiraram, o usuário é reautenticadoautomaticamente e são concedidas novas credenciais. (Para contas que não estão associadas a umdomínio, o usuário deve informar as credenciais antes da reautenticação.)
Para usar esse suporte no aplicativo .NET, primeiro é necessário configurar o perfil da função usandoum cmdlet PowerShell. Para saber como, consulte a AWS Tools for Windows PowerShell documentation(documentação sobre Ferramentas da AWS para o Windows PowerShell).
Depois de configurar o perfil da função, faça referência ao perfil no arquivo app.config/web.config doaplicativo com a chave AWSProfileName da mesma forma que faria com outros perfis de credenciais.
O conjunto SDK Security Token Service (AWSSDK.SecurityToken.dll), que é carregado durante otempo de execução, oferece o suporte ao SAML para obtenção das credenciais da AWS. Verifique se oconjunto está disponível para o aplicativo durante o tempo de execução.
Especificar funções ou credenciais temporárias
Para aplicativos executados em instâncias do Amazon EC2, a forma mais segura de gerenciar ascredenciais é utilizar funções do IAM, conforme descrito em Como usar funções do IAM para instâncias doEC2 com o AWS SDK para .NET (p. 138).
Para cenários do aplicativo em que o executável do software está disponível para usuários de fora daorganização, recomendamos que projete o software para usar credenciais de segurança temporárias.Além de oferecer acesso restrito aos recursos da AWS, essas credenciais têm o benefício de expiraremapós um período especificado. Para obter mais informações sobre as credenciais de segurançatemporárias, consulte:
• Uso de tokens de segurança para conceder acesso temporário aos recursos da AWS• Authenticating Users of AWS Mobile Applications with a Token Vending Machine (Autenticação de
usuários dos aplicativos móveis da AWS com uma máquina de vendas de token).
Embora o título do segundo artigo se refira especificamente aos aplicativos móveis, o artigo contéminformações úteis para qualquer aplicativo da AWS implantado fora da organização.
31
AWS SDK para .NET Guia do desenvolvedorSeleção da região da AWS
Usar credenciais de proxySe o software se comunica com a AWS por meio de um proxy, especifique as credenciais para o proxyusando a propriedade ProxyCredentials na classe AmazonS3Config para o serviço. Por exemplo, parao Amazon S3 use um código semelhante ao seguinte, onde {my-username} e {my-password} são o nomede usuário e senha do proxy especificados em um objeto NetworkCredential.
AmazonS3Config config = new AmazonS3Config();config.ProxyCredentials = new NetworkCredential("my-username", "my-password");
Versões anteriores do SDK utilizavam ProxyUsername e ProxyPassword, mas estas propriedadesestão obsoletas.
Seleção da região da AWSAs regiões da AWS permitem o acesso aos serviços da AWS que residem fisicamente em uma regiãogeográfica específica. Isso pode ser útil para redundância e para manter os seus dados e aplicativos emexecução próximo ao lugar em que você e os seus usuários os acessarão. Especifique uma região ao criaro cliente do serviço da AWS usando a classe RegionEndpoint.
Veja um exemplo que instancia um cliente do Amazon EC2 em uma região específica.
AmazonEC2Client ec2Client = new AmazonEC2Client(RegionEndpoint.USEast1);
As regiões estão isoladas umas das outras. Por exemplo, não é possível acessar os recursos da Lestedos EUA (Norte da Virgínia) ao usar a região Europa (Irlanda). Se o seu código precisa de acesso a váriasregiões da AWS, recomendamos a criação de um cliente separado para cada região.
Para usar serviços na região China (Pequim), é necessário ter uma conta e credenciais específicas para aregião China (Pequim). As contas e credenciais para outras regiões da AWS não funcionarão para a regiãoChina (Pequim). Da mesma forma, as contas e credenciais para a região China (Pequim) não funcionarãoem outras regiões da AWS. Para obter informações sobre os endpoints e protocolos que estão disponíveisna região China (Pequim), consulte Região China (Pequim).
Novos serviços da AWS podem ser lançados inicialmente em algumas regiões e, em seguida, liberadospara outras regiões. Nesses casos, não é necessário instalar o SDK mais recente para acessar as novasregiões. Especifique regiões recentemente adicionadas com uma base por cliente ou globalmente.
Por clienteDefinir a região em um cliente tem precedência sobre qualquer configuração global.
Construa o endpoint da nova região usando GetBySystemName:
var newRegion = RegionEndpoint.GetBySystemName("us-west-new");using (var ec2Client = new AmazonEC2Client(newRegion)){ // Make a request to EC2 using ec2Client}
Também é possível usar a propriedade ServiceURL da classe de configuração do cliente do serviço paraespecificar a região. Esta técnica funciona mesmo se o endpoint da região não seguir o padrão regular deendpoints da região.
var ec2ClientConfig = new AmazonEC2Config{ // Specify the endpoint explicitly
32
AWS SDK para .NET Guia do desenvolvedorConfiguração de outros parâmetros do aplicativo
ServiceURL = "https://ec2.us-west-new.amazonaws.com"};
using (var ec2Client = new AmazonEC2Client(newRegion)){ // Make a request to EC2 using ec2Client}
GlobalmenteHá várias maneiras de especificar uma região para todos os clientes. O AWS SDK para .NET procura umvalor de região na seguinte ordem:
Defina como uma propriedade AWSConfigs.AWSRegion,
AWSConfigs.AWSRegion = "us-west-new";using (var ec2Client = new AmazonEC2Client()){ // Make request to Amazon EC2 using ec2Client}
Defina como uma chave AWSRegion na seção appSettings do arquivo app.config.
<configuration> <appSettings> <add key="AWSRegion" value="us-west-2"/> </appSettings></configuration>
Defina como um atributo region na seção aws, conforme descrito em AWSRegion (p. 35).
<aws region="us-west-2"/>
Para exibir a lista atual de todas as regiões e endpoints compatíveis com cada serviço da AWS, consulteRegiões e endpoints no Referência geral do Amazon Web Services.
Configuração de outros parâmetros do aplicativoAlém de configurar as credenciais (p. 23), é possível configurar vários outros parâmetros do aplicativo:
• AWSLogging (p. 34)• AWSLogMetrics (p. 34)• AWSRegion (p. 35)• AWSResponseLogging (p. 35)• AWS.DynamoDBContext.TableNamePrefix (p. 36)• AWS.S3.UseSignatureVersion4 (p. 36)• AWSEndpointDefinition (p. 37)• Serviço da AWS - Endpoints gerados (p. 37)
Esses parâmetros podem ser configurados no arquivo App.config ou Web.config do aplicativo.Embora também seja possível configurar esses parâmetros com a API AWS SDK para .NET,recomendamos o uso do arquivo .config do aplicativo. Ambas as abordagens são descritas aqui.
Para obter mais informações sobre o uso do elemento <aws> conforme descrito posteriormente nestetópico, consulte Referência de arquivos de configuração para o AWS SDK para .NET (p. 39).
33
AWS SDK para .NET Guia do desenvolvedorConfiguração de outros parâmetros do aplicativo
AWSLoggingConfigura a forma como o SDK registra os eventos, caso registre. Por exemplo, a abordagemrecomendada é usar o elemento <logging>, que é um elemento filho do elemento <aws>:
<aws> <logging logTo="Log4Net"/></aws>
Alternativa:
<add key="AWSLogging" value="log4net"/>
Os valores possíveis são:
None
Desligue o registro de eventos. Esse é o padrão.log4net
Registre usando o log4net.SystemDiagnostics
Registre usando a classe System.Diagnostics.
Defina diversos valores para o atributo logTo, separado por vírgulas. O exemplo a seguir define ambos osregistros log4net e System.Diagnostics no arquivo .config:
<logging logTo="Log4Net, SystemDiagnostics"/>
Alternativa:
<add key="AWSLogging" value="log4net, SystemDiagnostics"/>
Ou, usando a API AWS SDK para .NET, combine os valores da enumeração LoggingOptions e defina apropriedade AWSConfigs.Logging:
AWSConfigs.Logging = LoggingOptions.Log4Net | LoggingOptions.SystemDiagnostics;
As alterações desta configuração entram em vigor somente para novas instâncias de cliente da AWS.
AWSLogMetricsEspecifica se o SDK deve ou não registrar as métricas de desempenho. Para definir a configuraçãodo registro das métricas no arquivo .config, defina o valor do atributo logMetrics no elemento<logging>, que é um elemento filho do elemento <aws>:
<aws> <logging logMetrics="true"/></aws>
Como alternativa, defina a chave AWSLogMetrics na seção<appSettings>:
<add key="AWSLogMetrics" value="true">
34
AWS SDK para .NET Guia do desenvolvedorConfiguração de outros parâmetros do aplicativo
Ou, para definir o registro das métricas com a API AWS SDK para .NET, defina a propriedadeAWSConfigs.LogMetrics:
AWSConfigs.LogMetrics = true;
Essa definição configura propriedade padrão LogMetrics para todos os clientes/configurações. Asalterações desta configuração entram em vigor somente para novas instâncias de cliente da AWS.
AWSRegionConfigura a região da AWS padrão para clientes que não especificaram uma região de forma explícita.Para definir a região no arquivo .config, a abordagem recomendada é definir o valor do atributo regionno elemento aws:
<aws region="us-west-2"/>
Como alternativa, defina a chave AWSRegion na seção<appSettings>:
<add key="AWSRegion" value="us-west-2"/>
Ou, para definir a região com a API AWS SDK para .NET, defina a propriedade AWSConfigs.AWSRegion:
AWSConfigs.AWSRegion = "us-west-2";
Para obter mais informações sobre a criação de um cliente da AWS para uma região específica, consulteSeleção de região da AWS (p. 32). As alterações desta configuração entram em vigor somente paranovas instâncias de cliente da AWS.
AWSResponseLoggingConfigura quando o SDK deve registrar respostas de serviços. Os valores possíveis são:
Never
Nunca registrar as respostas de serviços. Esse é o padrão.Always
Sempre registrar as respostas de serviços.OnError
Somente registrar as respostas de serviços quando ocorrer um erro.
Para definir a configuração do registro de serviços no arquivo .config, a abordagem recomendada édefinir o valor do atributo logResponses no elemento <logging>, que é um elemento filho do elemento<aws>:
<aws> <logging logResponses="OnError"/></aws>
Como alternativa, defina a chave AWSResponseLogging na seção<appSettings>:
<add key="AWSResponseLogging" value="OnError"/>
35
AWS SDK para .NET Guia do desenvolvedorConfiguração de outros parâmetros do aplicativo
Ou, para definir o registro de serviços com a API AWS SDK para .NET, defina a propriedadeAWSConfigs.ResponseLogging com um dos valores da enumeração ResponseLoggingOption:
AWSConfigs.ResponseLogging = ResponseLoggingOption.OnError;
As alterações desta configuração entram em vigor imediatamente.
AWS.DynamoDBContext.TableNamePrefixConfigura a TableNamePrefix padrão que o DynamoDBContext usará, se não for configuradamanualmente.
Para definir o prefixo do nome da tabela no arquivo .config, a abordagem recomendada é definir o valordo atributo tableNamePrefix no elemento <dynamoDBContext>, que é um elemento filho do elemento<dynamoDB>, que por sua vez é um elemento filho do elemento <aws>:
<dynamoDBContext tableNamePrefix="Test-"/>
Como alternativa, defina a chave AWS.DynamoDBContext.TableNamePrefix naseção<appSettings>:
<add key="AWS.DynamoDBContext.TableNamePrefix" value="Test-"/>
Ou, para definir o prefixo do nome da tabela com a API do AWS SDK para .NET, defina a propriedadeAWSConfigs.DynamoDBContextTableNamePrefix:
AWSConfigs.DynamoDBContextTableNamePrefix = "Test-";
As alterações desta configuração serão implementadas somente em instâncias recentemente criadas doDynamoDBContextConfig e DynamoDBContext.
AWS.S3.UseSignatureVersion4Configura se o cliente do Amazon S3 deve ou não usar a assinatura do Signature versão 4 com assolicitações.
Para definir a assinatura do Signature versão 4 para o Amazon S3 no arquivo .config, a abordagemrecomendada é definir o valor do atributo useSignatureVersion4 do elemento <s3>, que é umelemento filho do elemento <aws>:
<aws> <s3 useSignatureVersion4="true"/></aws>
Como alternativa, defina a chave AWS.S3.UseSignatureVersion4 como true na seção<appSettings>:
<add key="AWS.S3.UseSignatureVersion4" value="true"/>
Ou, para definir a assinatura do Signature versão 4 com a API AWS SDK para .NET, defina a propriedadeAWSConfigs.S3UseSignatureVersion4 como true:
AWSConfigs.S3UseSignatureVersion4 = true;
Por padrão, esta configuração é false, mas o Signature versão 4 pode ser usado como padrão em algunscasos ou em algumas regiões. Quando a configuração é true, o Signature versão 4 será usada em todas
36
AWS SDK para .NET Guia do desenvolvedorConfiguração de outros parâmetros do aplicativo
as solicitações. As alterações desta configuração entram em vigor somente para novas instâncias decliente do Amazon S3.
AWSEndpointDefinitionConfigura se o SDK deve ou não usar um arquivo de configuração personalizado que define as regiões eos endpoints.
Para definir o arquivo de definição do endpoint no arquivo .config, recomendamos definir o valor doatributo endpointDefinition no elemento <aws>.
<aws endpointDefinition="c:\config\endpoints.json"/>
Como alternativa, defina a chave AWSEndpointDefinition na seção<appSettings>:
<add key="AWSEndpointDefinition" value="c:\config\endpoints.json"/>
Ou, para definir o arquivo de definição do endpoint com a API AWS SDK para .NET, defina a propriedadeAWSConfigs.EndpointDefinition:
AWSConfigs.EndpointDefinition = @"c:\config\endpoints.json";
Se nenhum nome de arquivo for fornecido, não será usado um arquivo de configuração personalizado.As alterações desta configuração entram em vigor somente para novas instâncias de cliente da AWS. Oarquivo endpoint.json está disponível em https://github.com/aws/aws-sdk-net/blob/master/sdk/src/Core/endpoints.json.
Serviço da AWS - Endpoints geradosAlguns serviços da AWS geram seus próprios endpoints em vez de consumir um endpoint da região.Os clientes desses serviços consomem um URL de serviço específico ao serviço e aos recursos. Doisexemplos desses serviços são o Amazon CloudSearch e o AWS IoT. Os exemplos a seguir mostram comoobter os endpoints para esses serviços.
Exemplo dos endpoints do Amazon CloudSearchO cliente do Amazon CloudSearch é usado para acessar o serviço de configuração do AmazonCloudSearch. Use o serviço de configuração do Amazon CloudSearch para criar, configurar e gerenciar osdomínios de pesquisa. Para criar um domínio de pesquisa, crie um objeto CreateDomainRequest e forneçaa propriedade DomainName. Crie um objeto AmazonCloudSearchClient usando o objeto de solicitação.Chame o método CreateDomain. O objeto CreateDomainResponse retornado pela chamada contém umapropriedade DomainStatus que possui os endpoints DocService e SearchService. Crie um objetoAmazonCloudSearchDomainConfig e use-o para inicializar as instâncias DocService e SearchServiceda classe AmazonCloudSearchDomainClient.
// Create domain and retrieve DocService and SearchService endpointsDomainStatus domainStatus;using (var searchClient = new AmazonCloudSearchClient()){ var request = new CreateDomainRequest { DomainName = "testdomain" }; domainStatus = searchClient.CreateDomain(request).DomainStatus; Console.WriteLine(domainStatus.DomainName + " created");}
37
AWS SDK para .NET Guia do desenvolvedorConfiguração de outros parâmetros do aplicativo
// Test the DocService endpointvar docServiceConfig = new AmazonCloudSearchDomainConfig{ ServiceURL = "https://" + domainStatus.DocService.Endpoint};using (var domainDocService = new AmazonCloudSearchDomainClient(docServiceConfig)){ Console.WriteLine("Amazon CloudSearchDomain DocService client instantiated using the DocService endpoint"); Console.WriteLine("DocService endpoint = " + domainStatus.DocService.Endpoint);
using (var docStream = new FileStream(@"C:\doc_source\XMLFile4.xml", FileMode.Open)) { var upload = new UploadDocumentsRequest { ContentType = ContentType.ApplicationXml, Documents = docStream }; domainDocService.UploadDocuments(upload); }}
// Test the SearchService endpointvar searchServiceConfig = new AmazonCloudSearchDomainConfig{ ServiceURL = "https://" + domainStatus.SearchService.Endpoint};using (var domainSearchService = new AmazonCloudSearchDomainClient(searchServiceConfig)){ Console.WriteLine("Amazon CloudSearchDomain SearchService client instantiated using the SearchService endpoint"); Console.WriteLine("SearchService endpoint = " + domainStatus.SearchService.Endpoint);
var searchReq = new SearchRequest { Query = "Gambardella", Sort = "_score desc", QueryParser = QueryParser.Simple }; var searchResp = domainSearchService.Search(searchReq);}
Exemplo dos endpoints do AWS IoTPara obter o endpoint do AWS IoT, crie um objeto AmazonIoTClient e chame o método DescribeEndPoint.O objeto DescribeEndPointResponse retornado contém o EndpointAddress. Crie um objetoAmazonIotDataConfig, defina a propriedade ServiceURL e use o objeto para instanciar a classeAmazonIotDataClient.
string iotEndpointAddress;using (var iotClient = new AmazonIoTClient()){ var endPointResponse = iotClient.DescribeEndpoint(); iotEndpointAddress = endPointResponse.EndpointAddress;}
var ioTdocServiceConfig = new AmazonIotDataConfig{ ServiceURL = "https://" + iotEndpointAddress};using (var dataClient = new AmazonIotDataClient(ioTdocServiceConfig)){ Console.WriteLine("AWS IoTData client instantiated using the endpoint from the IotClient");
38
AWS SDK para .NET Guia do desenvolvedorReferência dos arquivos de configuração
para o AWS SDK para .NET
}nstantiated using the endpoint from the IoT client");
Referência dos arquivos de configuração para o AWSSDK para .NETUse um arquivo App.config ou Web.config do projeto .NET para especificar as configurações da AWS,como credenciais da AWS, opções de registro, endpoints de serviço da AWS e regiões da AWS, bemcomo algumas configurações dos serviços da AWS, como Amazon DynamoDB, Amazon EC2 e AmazonS3. As informações a seguir descrevem como formatar de forma apropriada um arquivo App.config ouWeb.config para especificar esses tipos de configurações.
Note
Embora seja possível continuar a usar o elemento <appSettings> em um arquivo App.configou Web.config para especificar as configurações da AWS, recomendamos o uso dos elementos<configSections> e <aws> conforme descrito posteriormente neste tópico. Para obtermais informações sobre o elemento <appSettings>, consulte os exemplos de elementos<appSettings> em Configuração do aplicativo AWS SDK para .NET (p. 19).Note
Embora seja possível continuar a usar as propriedades a seguir da classe AWSConfigs em umarquivo de código para especificar as configurações da AWS, essas propriedades são obsoletas epodem não ser compatíveis em versões futuras:
• DynamoDBContextTableNamePrefix
• EC2UseSignatureVersion4
• LoggingOptions
• LogMetrics
• ResponseLoggingOption
• S3UseSignatureVersion4
Geralmente, recomendamos que em vez de usar as propriedades da classe AWSConfigsem um arquivo de código para especificar as configurações da AWS, use os elementos<configSections> e <aws> em um arquivo App.config ou Web.config para especificar taisconfigurações, conforme descrito posteriormente neste tópico. Para obter mais informações sobreas propriedades anteriores, consulte os exemplos de códigos AWSConfigs em Configuração doaplicativo AWS SDK para .NET (p. 19).
Tópicos• Declarar uma seção de configurações da AWS (p. 39)• Elementos permitidos (p. 40)• Referência dos elementos (p. 41)
Declarar uma seção de configurações da AWSEspecifique as configurações da AWS em um arquivo App.config ou Web.config a partir do elemento<aws>. Antes de começar a usar o elemento <aws>, é necessário criar um elemento <section> (que éum elemento filho do elemento <configSections>) e definir o seu atributo name como aws e o atributotype como Amazon.AWSSection, AWSSDK.Core, conforme mostrado no seguinte exemplo:
<?xml version="1.0"?><configuration> ...
39
AWS SDK para .NET Guia do desenvolvedorReferência dos arquivos de configuração
para o AWS SDK para .NET
<configSections> <section name="aws" type="Amazon.AWSSection, AWSSDK.Core"/> </configSections> <aws> <!-- Add your desired AWS settings declarations here. --> </aws> ...</configuration>
O editor do Visual Studio não oferece a conclusão de código automática (IntelliSense) para o elemento<aws> ou para os seus elementos filho.
Para auxiliá-lo na criação de uma versão corretamente formatada <aws>, chame o métodoAmazon.AWSConfigs.GenerateConfigTemplate. Isso gera como saída uma versão canônica doelemento <aws> como uma string formatada, que pode ser adaptada para as suas necessidades. Asseções a seguir descrevem os atributos e os elementos filho do elemento <aws>.
Elementos permitidosA seguir encontra-se uma lista das relações lógicas entre os elementos permitidos em umaseção de configurações da AWS. Gere a versão mais recente dessa lista chamando o métodoAmazon.AWSConfigs.GenerateConfigTemplate, que gera como saída uma versão canônica doelemento <aws> como uma string que pode ser adaptada para as suas necessidades.
<aws endpointDefinition="string value" region="string value" profileName="string value" profilesLocation="string value"> <logging logTo="None, Log4Net, SystemDiagnostics" logResponses="Never | OnError | Always" logMetrics="true | false" logMetricsFormat="Standard | JSON" logMetricsCustomFormatter="NameSpace.Class, Assembly" /> <dynamoDB conversionSchema="V1 | V2"> <dynamoDBContext tableNamePrefix="string value"> <tableAliases> <alias fromTable="string value" toTable="string value" /> </tableAliases> <map type="NameSpace.Class, Assembly" targetTable="string value"> <property name="string value" attribute="string value" ignore="true | false" version="true | false" converter="NameSpace.Class, Assembly" /> </map> </dynamoDBContext> </dynamoDB> <s3 useSignatureVersion4="true | false" /> <ec2 useSignatureVersion4="true | false" /> <proxy host="string value" port="1234"
40
AWS SDK para .NET Guia do desenvolvedorReferência dos arquivos de configuração
para o AWS SDK para .NET
username="string value" password="string value" /></aws>
Referência dos elementosA seguir encontra-se uma lista dos elementos permitidos em uma seção de configurações da AWS. Paracada elemento, são listados os atributos permitidos e os elementos filho.
Tópicos• alias (p. 41)• aws (p. 41)• dynamoDB (p. 42)• dynamoDBContext (p. 43)• ec2 (p. 43)• registro (p. 43)• mapear (p. 45)• property (p. 45)• proxy (p. 46)• s3 (p. 46)
aliasO elemento <alias> representa um único item em um conjunto de um ou mais mapeamentosfrom-table até to-table, que especifica uma tabela diferente daquela configurada para um tipo. Esseelemento é mapeado para uma instância da classe Amazon.Util.TableAlias da propriedadeAmazon.AWSConfigs.DynamoDBConfig.Context.TableAliases no AWS SDK para .NET. Oremapeamento é feito antes de aplicar um prefixo de nome da tabela.
Esse elemento pode incluir os seguintes atributos:
fromTable
A parte from-table do mapeamento from-table até to-table. Esse atributo é mapeado para apropriedade Amazon.Util.TableAlias.FromTable no AWS SDK para .NET.
toTable
A parte to-table do mapeamento from-table até to-table. Esse atributo é mapeado para a propriedadeAmazon.Util.TableAlias.ToTable no AWS SDK para .NET.
O pai do elemento <alias> é o elemento <tableAliases>.
O elemento <alias> não contém elementos filho.
Veja a seguir um exemplo do elemento <alias> em uso:
<alias fromTable="Studio" toTable="Studios" />
awsO elemento <aws> representa o elemento mais superior em uma seção de configurações da AWS. Esseelemento pode incluir os seguintes atributos:
41
AWS SDK para .NET Guia do desenvolvedorReferência dos arquivos de configuração
para o AWS SDK para .NET
endpointDefinition
O caminho absoluto para um arquivo de configuração personalizado que define asregiões e endpoints da AWS para o uso. Esse atributo é mapeado para a propriedadeAmazon.AWSConfigs.EndpointDefinition no AWS SDK para .NET.
profileName
O nome do perfil para as credenciais da AWS armazenadas que serão utilizadaspara realizar chamadas de serviços. Esse atributo é mapeado para a propriedadeAmazon.AWSConfigs.AWSProfileName no AWS SDK para .NET.
profilesLocation
O caminho absoluto do local do arquivo de credenciais compartilhado com outros AWS SDKs. Porpadrão, o arquivo de credenciais está armazenado no diretório .aws no diretório inicial do usuárioatual. Esse atributo é mapeado para a propriedade Amazon.AWSConfigs.AWSProfilesLocationno AWS SDK para .NET.
region
O ID da região da AWS padrão para clientes que não especificaram explicitamente uma região. Esseatributo é mapeado para a propriedade Amazon.AWSConfigs.AWSRegion no AWS SDK para .NET.
O elemento <aws> não possui elemento pai.
O elemento <aws> pode incluir os seguintes elementos filho:
• <dynamoDB>
• <ec2>
• <logging>
• <proxy>
• <s3>
Veja a seguir um exemplo do elemento <aws> em uso:
<aws endpointDefinition="C:\Configs\endpoints.xml" region="us-west-2" profileName="development" profilesLocation="C:\Configs"> <!-- ... --></aws>
dynamoDBO elemento <dynamoDB> representa um conjunto de configurações do Amazon DynamoDB. Esteelemento pode incluir o atributo conversionSchema, que representa a versão a ser usada para conversãoentre objetos .NET e DynamoDB. Os valores permitidos incluem V1 e V2. Esse atributo é mapeado para aclasse Amazon.DynamoDBv2.DynamoDBEntryConversion no AWS SDK para .NET. Para obter maisinformações, consulte Série DynamoDB – esquemas de conversão.
O pai do elemento <dynamoDB> é o elemento <aws>.
O elemento <dynamoDB> pode incluir o elemento filho <dynamoDBContext>.
Veja a seguir um exemplo do elemento <dynamoDB> em uso:
<dynamoDB conversionSchema="V2">
42
AWS SDK para .NET Guia do desenvolvedorReferência dos arquivos de configuração
para o AWS SDK para .NET
<!-- ... --></dynamoDB>
dynamoDBContextO elemento <dynamoDBContext> representa um conjunto de configurações específicas de contexto doAmazon DynamoDB. Este elemento pode incluir o atributo tableNamePrefix, que representa o prefixo donome da tabela padrão que o contexto do DynamoDB usará se não for configurado manualmente. Esseatributo é mapeado para a propriedade Amazon.Util.DynamoDBContextConfig.TableNamePrefixda propriedade Amazon.AWSConfigs.DynamoDBConfig.Context.TableNamePrefix no AWS SDKpara .NET. Para obter mais informações, consulte Aprimoramentos do DynamoDB SDK.
O pai do elemento <dynamoDBContext> é o elemento <dynamoDB>.
O elemento <dynamoDBContext> pode incluir os seguintes elementos filho:
• <alias> (uma ou mais instâncias)• <map> (uma ou mais instâncias)
Veja a seguir um exemplo do elemento <dynamoDBContext> em uso:
<dynamoDBContext tableNamePrefix="Test-"> <!-- ... --></dynamoDBContext>
ec2O elemento <ec2> representa um conjunto de configurações do Amazon EC2. Este elemento pode incluiro atributo useSignatureVersion4, que especifica se a assinatura do Signature Version4 será usada paratodas as solicitações (verdadeiro) ou se ela não será usada para todas as solicitações (falso, o padrão).Esse atributo é mapeado para a propriedade Amazon.Util.EC2Config.UseSignatureVersion4 dapropriedade Amazon.AWSConfigs.EC2Config.UseSignatureVersion4 no AWS SDK para .NET.
O pai do elemento <ec2> é o elemento.
O elemento <ec2> não contém elementos filho.
Veja a seguir um exemplo do elemento <ec2> em uso:
<ec2 useSignatureVersion4="true" />
registroO elemento <logging> representa um conjunto de configurações para o registro de respostas e demétricas de desempenho. Esse elemento pode incluir os seguintes atributos:
logMetrics
Se as métricas de desempenho serão registradas para todos os clientes econfigurações (verdadeiro); caso contrário, falso. Esse atributo é mapeado paraa propriedade Amazon.Util.LoggingConfig.LogMetrics da propriedadeAmazon.AWSConfigs.LoggingConfig.LogMetrics no AWS SDK para .NET.
logMetricsCustomFormatter
O tipo de dados e o nome do conjunto de um formatador personalizadopara as métricas de registro. Esse atributo é mapeado para a propriedade
43
AWS SDK para .NET Guia do desenvolvedorReferência dos arquivos de configuração
para o AWS SDK para .NET
Amazon.Util.LoggingConfig.LogMetricsCustomFormatter da propriedadeAmazon.AWSConfigs.LoggingConfig.LogMetricsCustomFormatter no AWS SDK para .NET.
logMetricsFormat
O formato em que as métricas de registro são apresentadas (é mapeado para apropriedade Amazon.Util.LoggingConfig.LogMetricsFormat da propriedadeAmazon.AWSConfigs.LoggingConfig.LogMetricsFormat no AWS SDK para .NET).
Os valores permitidos incluem:JSON
Use o formato JSON.Standard
Use o formato padrão.logResponses
Quando registrar as respostas de serviços (é mapeado para a propriedadeAmazon.Util.LoggingConfig.LogResponses da propriedadeAmazon.AWSConfigs.LoggingConfig.LogResponses no AWS SDK para .NET).
Os valores permitidos incluem:Always
Sempre registrar as respostas de serviços.Never
Nunca registrar as respostas de serviços.OnError
Somente registrar as respostas de serviços quando existirem erros.logTo
Onde registrar (é mapeado para a propriedade LogTo a partir da propriedadeAmazon.AWSConfigs.LoggingConfig.LogTo no AWS SDK para .NET).
Os valores permitidos incluem um ou mais entre:Log4Net
Registrar no log4net.None
Desativar o registro.SystemDiagnostics
Registrar no System.Diagnostics.
O pai do elemento <logging> é o elemento <aws>.
O elemento <logging> não contém elementos filho.
Veja a seguir um exemplo do elemento <logging> em uso:
<logging logTo="SystemDiagnostics" logResponses="OnError" logMetrics="true"
44
AWS SDK para .NET Guia do desenvolvedorReferência dos arquivos de configuração
para o AWS SDK para .NET
logMetricsFormat="JSON" logMetricsCustomFormatter="MyLib.Util.MyMetricsFormatter, MyLib" />
mapearO elemento <map> representa um único item em um conjunto de mapeamentos type-to-table de tipos .NETpara tabelas do DynamoDB (é mapeado para uma instância da classe TypeMapping da propriedadeAmazon.AWSConfigs.DynamoDBConfig.Context.TypeMappings no AWS SDK para .NET). Paraobter mais informações, consulte Aprimoramentos do DynamoDB SDK.
Esse elemento pode incluir os seguintes atributos:
targetTable
A tabela do DynamoDB a qual o mapeamento se aplica. Esse atributo é mapeado para a propriedadeAmazon.Util.TypeMapping.TargetTable no AWS SDK para .NET.
type
O tipo e o nome do conjunto ao qual o mapeamento se aplica. Esse atributo é mapeado para apropriedade Amazon.Util.TypeMapping.Type no AWS SDK para .NET.
O pai do elemento <map> é o elemento <dynamoDBContext>.
O elemento <map> pode incluir uma ou mais instâncias do elemento filho <property>.
Veja a seguir um exemplo do elemento <map> em uso:
<map type="SampleApp.Models.Movie, SampleDLL" targetTable="Movies"> <!-- ... --></map>
propertyO elemento <property> representa uma propriedade do DynamoDB. (Este elemento é mapeado parauma instância da classe Amazon.Util.PropertyConfig do método AddProperty no AWS SDK para .NET)Para obter mais informações, consulte Aprimoramentos do DynamoDB SDK e Atributos do DynamoDB.
Esse elemento pode incluir os seguintes atributos:
attribute
O nome de um atributo da propriedade, como o nome de uma chave de intervalo. Esse atributoé mapeado para a propriedade Amazon.Util.PropertyConfig.Attribute no AWS SDKpara .NET.
converter
O tipo de conversor que deve ser usado para esta propriedade. Esse atributo é mapeado para apropriedade Amazon.Util.PropertyConfig.Converter no AWS SDK para .NET.
ignore
Se a propriedade associada deve ser ignorada (verdadeiro); caso contrário, falso. Esse atributo émapeado para a propriedade Amazon.Util.PropertyConfig.Ignore no AWS SDK para .NET.
name
O nome da propriedade. Esse atributo é mapeado para a propriedadeAmazon.Util.PropertyConfig.Name no AWS SDK para .NET.
45
AWS SDK para .NET Guia do desenvolvedorReferência dos arquivos de configuração
para o AWS SDK para .NET
version
Se essa propriedade deve armazenar o número da versão do item (verdadeiro); caso contrário, falso.Esse atributo é mapeado para a propriedade Amazon.Util.PropertyConfig.Version no AWSSDK para .NET.
O pai do elemento <property> é o elemento <map>.
O elemento <property> não contém elementos filho.
Veja a seguir um exemplo do elemento <property> em uso:
<property name="Rating" converter="SampleApp.Models.RatingConverter, SampleDLL" />
proxyO elemento <proxy> representa as configurações necessárias de um proxy para o seu uso pelo AWSSDK para .NET. Esse elemento pode incluir os seguintes atributos:
host
O nome do host ou endereço IP do servidor de proxy. Esses atributos sãomapeados para a propriedade Amazon.Util.ProxyConfig.Host da propriedadeAmazon.AWSConfigs.ProxyConfig.Host no AWS SDK para .NET.
password
A senha para a autenticação com o servidor de proxy. Esses atributos são mapeadospara a propriedade Amazon.Util.ProxyConfig.Password da propriedadeAmazon.AWSConfigs.ProxyConfig.Password no AWS SDK para .NET.
port
O número da porta do proxy. Esses atributos são mapeados para a propriedadeAmazon.Util.ProxyConfig.Port da propriedade Amazon.AWSConfigs.ProxyConfig.Portno AWS SDK para .NET.
nome de usuário
O nome de usuário para a autenticação com o servidor de proxy. Esses atributos sãomapeados para a propriedade Amazon.Util.ProxyConfig.Username da propriedadeAmazon.AWSConfigs.ProxyConfig.Username no AWS SDK para .NET.
O pai do elemento <proxy> é o elemento <aws>.
O elemento <proxy> não contém elementos filho.
Veja a seguir um exemplo do elemento <proxy> em uso:
<proxy host="192.0.2.0" port="1234" username="My-Username-Here" password="My-Password-Here" />
s3O elemento <s3> representa um conjunto de configurações do Amazon S3. Este elementopode incluir o atributo useSignatureVersion4, que especifica se a assinatura do Signature
46
AWS SDK para .NET Guia do desenvolvedorHabilitar o Métricas do SDK
Version4 será usada para todas as solicitações (verdadeiro) ou se ela não será usadapara todas as solicitações (falso, o padrão). Esse atributo é mapeado para a propriedadeAmazon.AWSConfigs.S3Config.UseSignatureVersion4 no AWS SDK para .NET.
O pai do elemento <s3> é o elemento <aws>.
O elemento <s3> não contém elementos filho.
Veja a seguir um exemplo do elemento <s3> em uso:
<s3 useSignatureVersion4="true" />
Habilitar o Métricas do SDKO Métricas do AWS SDK para Enterprise Support (Métricas do SDK) permite que os clientes corporativoscoletem métricas dos AWS SDKs em seus hosts e clientes compartilhados como AWS Enterprise Support.O Métricas do SDK fornece informações que ajudam a acelerar a detecção e o diagnóstico de problemasque ocorrem em conexões com os serviços da AWS para os clientes do AWS Enterprise Support.
Como a telemetria é coletada em cada host, ela é retransmitida por UDP para 127.0.0.1 (tambémconhecido como localhost), em que o agente do CloudWatch agrega os dados e envia-os para o serviço doMétricas do SDK. Portanto, para receber métricas, o agente do CloudWatch deverá ser adicionado à suainstância.
As etapas a seguir para configurar o Métricas do SDK pertencem a uma instância do Amazon EC2executando o Amazon Linux para um aplicativo cliente que está usando AWS SDK para .NET. O Métricasdo SDK também está disponível para seus ambientes de produção se você habilitá-lo ao configurar o AWSSDK para .NET.
Para utilizar Métricas do SDK, execute a versão mais recente do agente do CloudWatch. Saiba comoconfigurar o agente do CloudWatch para métricas do SDK no Guia do usuário do Amazon CloudWatch.
Para configurar o Métricas do SDK com o AWS SDK para .NET, siga estas instruções:
1. Crie um aplicativo com um cliente do AWS SDK para .NET para usar um serviço da AWS.2. Hospede seu projeto em uma instância do Amazon EC2 ou em seu ambiente local.3. Instale e use a versão mais recente do AWS SDK para .NET.4. Instale e configure um agente do CloudWatch em uma instância do EC2 ou no ambiente local.5. Autorize o Métricas do SDK a coletar e enviar métricas.6. Habilite as métricas do SDK para o AWS SDK para .NET (p. 47).
Para obter mais informações, consulte:
• Atualizar um alarme do CloudWatch (p. 48)• Desabilitar métricas do SDK (p. 49)
Habilitar o Métricas do SDK para o AWS SDK para .NETPor padrão, o Métricas do SDK é desativado, e a porta é definida como 31000. Os parâmetros a seguir sãoo padrão:
//default values [ 'enabled' => false, 'port' => 31000,
47
AWS SDK para .NET Guia do desenvolvedorHabilitar o Métricas do SDK
]
A habilitação do Métricas do SDK é independente da configuração de suas credenciais para usar umserviço da AWS.
Você pode habilitar o Métricas do SDK definindo variáveis de ambiente ou usando o arquivo deconfiguração compartilhado da AWS.
Opção 1: definir variáveis de ambienteSe AWS_CSM_ENABLED não estiver definido, o SDK primeiro verificará o perfil especificado na variávelde ambiente em AWS_PROFILE para determinar se o Métricas do SDK está habilitado. Por padrão, isso édefinido como false.
Para ativar o Métricas do SDK, adicione o seguinte às variáveis de ambiente.
export AWS_CSM_ENABLED=true
Outras definições de configuração (p. 48) estão disponíveis.
Observação: habilitar o Métricas do SDK não configura suas credenciais para usar um serviço da AWS.
Opção 2: arquivo de configuração compartilhado da AWSSe nenhuma configuração do Métricas do SDK for encontrada nas variáveis de ambiente, o SDK vaiprocurar o campo de perfil da AWS padrão. Se AWS_DEFAULT_PROFILE estiver definido como algo quenão seja padrão, atualize esse perfil. Para habilitar o Métricas do SDK, adicione csm_enabled ao arquivode configuração compartilhado localizado em ~/.aws/config.
[default]csm_enabled = true
[profile aws_csm]csm_enabled = true
Outras definições de configuração (p. 48) estão disponíveis.
Observação: a habilitação do Métricas do SDK é independente da configuração de suas credenciais parausar um serviço da AWS. Você pode usar um perfil diferente para autenticar.
Atualizar um agente do CloudWatchPara alterar a porta, é necessário definir os valores e, em seguida, reiniciar os trabalhos da AWS queestejam atualmente ativos.
Opção 1: definir variáveis de ambienteA maioria dos serviços usa a porta padrão. No entanto, se o seu serviço exige um ID de porta exclusivo,adicione AWS_CSM_PORT=[número_da_porta], às variáveis de ambiente do host.
export AWS_CSM_ENABLED=trueexport AWS_CSM_PORT=1234
Opção 2: arquivo de configuração compartilhado da AWSA maioria dos serviços usa a porta padrão. No entanto, se o seu serviço exige um ID de porta exclusivo,adicione csm_port = [número_da_porta] a ~/.aws/config.
48
AWS SDK para .NET Guia do desenvolvedorHabilitar o Métricas do SDK
[default]csm_enabled = falsecsm_port = 1234
[profile aws_csm]csm_enabled = falsecsm_port = 1234
Reiniciar o Métricas do SDKPara reiniciar um trabalho, use os comandos a seguir.
amazon-cloudwatch-agent-ctl –a stop;amazon-cloudwatch-agent-ctl –a start;
Desabilitar o Métricas do SDKPara desativar o Métricas do SDK, defina csm_enabled como false nas variáveis de ambiente, ou em seuarquivo de configuração compartilhado da AWS localizado em ~/.aws/config. Depois, reinicie o agentedo CloudWatch para que as alterações entrem em vigor.
Variáveis de ambiente
export AWS_CSM_ENABLED=false
Arquivo de configuração compartilhado da AWS
Remova csm_enabled dos perfis no arquivo de configuração compartilhado da AWS localizado em~/.aws/config.
Note
As variáveis de ambiente substituem o arquivo de configuração compartilhado da AWS. Se oMétricas do SDK estiver habilitado nas variáveis de ambiente, o Métricas do SDK permaneceráhabilitado.
[default]csm_enabled = false
[profile aws_csm]csm_enabled = false
Para desabilitar o Métricas do SDK, use o comando a seguir para interromper o agente do CloudWatch.
sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a stop &&echo "Done"
Se você estiver usando outros recursos do CloudWatch, reinicie o CloudWatch com o comando a seguir.
amazon-cloudwatch-agent-ctl –a start;
Reiniciar o Métricas do SDKPara reiniciar um trabalho, use os comandos a seguir.
amazon-cloudwatch-agent-ctl –a stop;amazon-cloudwatch-agent-ctl –a start;
49
AWS SDK para .NET Guia do desenvolvedorHabilitar o Métricas do SDK
Definições para o Métricas do SDKVocê pode usar as seguintes descrições do Métricas do SDK para interpretar os resultados. Em geral,essas métricas estão disponíveis para análise com seu gerente de contas técnicas durante as análisesempresariais regulares. Os recursos do AWS Support e o Gerente de contas técnicas devem ter acessoaos dados de métricas do SDK para ajudar você a resolver casos, mas se você descobrir dados confusosou inesperados, mas que não parecem afetar negativamente o desempenho de seus aplicativos, é melhoranalisar esses dados durante as análises empresariais programadas.
Métrica: CallCount
Definição Número total de chamadas de API com êxito oucom falha do código para serviços da AWS.
Como usar Use-o como uma linha de base para correlacionarcom outras métricas, como erros ou limitação.
Métrica: ClientErrorCount
Definição O número de chamadas de API que tiveram falhacom erros de cliente (códigos de resposta HTTP4xx). Exemplos: limitação, acesso negado, obucket do S3 não existe e valor de parâmetroinválido.
Como usar Exceto em determinados casos relacionados alimitações (por exemplo, quando a limitação ocorredevido a um limite que precisa ser aumentado),essa métrica pode indicar algo que precisa sercorrigido em seu aplicativo.
Métrica: ConnectionErrorCount
Definição O número de chamadas de API que tiveram falhadevido a erros na conexão com o serviço. Issopode ser causado por problemas de rede entreo aplicativo do cliente e os serviços da AWS,incluindo problemas de load balancers, falhas deDNS e problemas de provedor de trânsito. Emalguns casos, problemas da AWS podem resultarnesse erro.
Como usar Use essa métrica para determinar se os problemassão específicos do seu aplicativo ou se sãocausados por sua infraestrutura e/ou rede. UmaConnectionErrorCount alta também pode indicarvalores de tempo limite curto de chamadas de API.
Métrica: ThrottleCount
Definição O número de chamadas de API com falha devido alimitações por serviços da AWS.
50
AWS SDK para .NET Guia do desenvolvedorAPIs assíncronas
Métrica: ThrottleCount
Como usar Use esta métrica para avaliar se o aplicativo atingiuos limites de controle de fluxo, bem como paradeterminar a causa de novas tentativas e a latênciado aplicativo. Considere distribuir as chamadas emuma janela em vez de colocar suas chamadas emlote.
Métrica: ServerErrorCount
Definição O número de chamadas de API com falha devidoa erros de servidor (códigos de resposta HTTP5xx) de serviços da AWS. Eles geralmente sãocausados por serviços da AWS.
Como usar Determine a causa das novas tentativas do SDKou a latência. Essa métrica nem sempre indicaque os serviços da AWS estão com falha, porquealgumas equipes da AWS classificam latênciacomo uma resposta HTTP 503.
Métrica: EndToEndLatency
Definição O tempo total para seu aplicativo fazer umachamada usando o AWS SDK, inclusive de novastentativas. Em outras palavras, independentementede ele ter tido êxito após várias tentativas, ouassim que uma chamada tiver falha devido a umerro que não pode ser repetível.
Como usar Determine como chamadas de API da AWScontribuem para a latência geral de seu aplicativo.Latência mais alta do que o esperado pode sercausado por problemas com a rede, o firewall, ououtras definições de configuração, ou por latênciaque ocorre como resultado de novas tentativas doSDK.
APIs assíncronas da AWS para .NETAPI assíncrona para .NET Framework 4.5, WindowsStore e Windows Phone 8O AWS SDK para .NET usa o novo padrão assíncrono baseado em tarefa para a versão 4.5 do .NETFramework, Windows Store e Windows Phone 8. Use as palavras-chave async e await para realizar egerenciar operações assíncronas em todos os produtos da AWS sem bloqueio.
Para saber mais sobre o padrão assíncrono baseado em tarefa, consulte Padrão assíncrono baseado emtarefas (TAP) no MSDN.
51
AWS SDK para .NET Guia do desenvolvedorAPI assíncrona para .NET Framework 3.5
API assíncrona para .NET Framework 3.5O AWS SDK para .NET oferece suporte a versões assíncronas (async) da maioria das chamadas demétodos expostas pelas classes de cliente .NET. Os métodos assíncronos permitem a chamada deserviços da AWS sem que o código seja bloqueado na resposta do serviço. Por exemplo, é possível fazeruma solicitação para gravar dados no Amazon S3 ou DynamoDB e, em seguida, continuar realizandooutros trabalhos com o código enquanto a AWS processa as solicitações.
Sintaxe dos métodos de solicitação assíncronaExistem duas fases para realizar uma solicitação assíncrona a um serviço da AWS. A primeira échamar o método Begin para a solicitação. Esse método inicia a operação assíncrona. O método Endcorrespondente recupera a resposta do serviço e também oferece uma oportunidade para gerenciarexceções que podem ter ocorrido durante a operação.
Note
Não é necessário chamar o método End. Supondo que nenhum erro foi encontrado, a operaçãoassíncrona será concluída independentemente de você chamar ou não o método End.
Sintaxe do método BeginAlém de tomar um parâmetro do objeto de solicitação, como o PutItemRequest, os métodos Beginassíncronos tomam dois parâmetros diferentes: uma função de retorno de chamada e um objeto deestado. Em vez de retornar um service response object (objeto de resposta do serviço), os métodos Beginretornam um resultado do tipo IAsyncResult. Para obter a definição deste tipo, acesse a documentaçãodo MSDN.
Método síncrono
PutItemResponse PutItem( PutItemRequest putItemRequest)
Método assíncrono
IAsyncResult BeginPutItem( GetSessionTokenRequest getSessionTokenRequest, {AsyncCallback callback}, {Object state})
Retorno de chamada AsyncCallback
A função de retorno de chamada é chamada quando a operação assíncrona for concluída. Quando afunção é chamada, ela recebe um único parâmetro do tipo IAsyncResult. A função de retorno de chamadapossui a assinatura a seguir.
void Callback(IAsyncResult asyncResult)
Objeto state
O terceiro parâmetro, state, é um objeto definido pelo usuário, disponível para a função deretorno de chamada como a propriedade AsyncState do parâmetro asyncResult, isto é,asyncResult.AsyncState.
Padrões de chamada
• Transmitir uma função de retorno de chamada e um objeto de estado.
52
AWS SDK para .NET Guia do desenvolvedorAPI assíncrona para .NET Framework 3.5
• Transmitir uma função de retorno de chamada, mas transmitir zero para o objeto de estado.• Transmitir zero para a função de retorno de chamada e para o objeto de estado.
Este tópico fornece um exemplo de cada um desses padrões.
Usando IAsyncResult.AsyncWaitHandle
Em algumas circunstâncias, o código que chama o método Begin pode precisar ativar outro métodochamado para esperar a conclusão da operação assíncrona. Nestas situações, ele pode transmitir ométodo WaitHandle retornado pela propriedade IAsyncResult.AsyncWaitHandle do valor deretorno IAsyncResult. O método pode, então, esperar a conclusão da operação assíncrona ao chamarWaitOne neste WaitHandle.
ExemplosPara obter o exemplo de código completo, consulte Exemplo completo (p. 55) abaixo ou visualize-o noGitHub.
Todos os exemplos a seguir pressupõem o código de inicialização a seguir.
public static void TestPutObjectAsync(string bucket) { // Create a client AmazonS3Client client = new AmazonS3Client();
PutObjectResponse response; IAsyncResult asyncResult;
// // Create a PutObject request object using the supplied bucket name. // PutObjectRequest request = new PutObjectRequest { BucketName = bucket, Key = "Item0-Synchronous", ContentBody = "Put S3 object synchronously." };
Nenhum retorno de chamado especificado
O exemplo de código a seguir chama BeginPutObject, realiza algum trabalho e, em seguida, chamaEndPutObject para recuperar a resposta do serviço. A chamada para EndPutObject está anexada emum bloco try para capturar quaisquer exceções que possam ser lançadas durante a operação.
asyncResult = client.BeginPutObject(request, null, null); while (!asyncResult.IsCompleted) { // // Do some work here // } try { response = client.EndPutObject(asyncResult); } catch (AmazonS3Exception s3Exception) { Console.WriteLine("Caught exception calling EndPutObject:"); Console.WriteLine(s3Exception);
53
AWS SDK para .NET Guia do desenvolvedorAPI assíncrona para .NET Framework 3.5
}
Retorno de chamada simplesEste exemplo pressupõe que a função de retorno de chamada a seguir foi definida.
public static void SimpleCallback(IAsyncResult asyncResult) { Console.WriteLine("Finished PutObject operation with simple callback."); Console.WriteLine("--------------------------------------------------"); Console.WriteLine("asyncResult.IsCompleted: {0}\n\n", asyncResult.IsCompleted.ToString()); }
A linha de código a seguir chama BeginPutObject e especifica a função de retorno de chamadaacima. Quando a operação PutObject for concluída, a função de retorno de chamada será chamada.A chamada ao BeginPutObject especifica null para o parâmetro state, pois a função de retorno dechamada simples não acessa a propriedade AsyncState do parâmetro asyncResult. Nem o código dechamada ou a função de retorno de chamada chamam EndPutObject. Portanto, a resposta do serviço érejeitada de forma eficiente e quaisquer exceções que ocorreram durante a operação serão ignoradas.
asyncResult = client.BeginPutObject(request, SimpleCallback, null);
Retorno de chamada com clienteEste exemplo pressupõe que a função de retorno de chamada a seguir foi definida.
public static void CallbackWithClient(IAsyncResult asyncResult) { try { AmazonS3Client s3Client = (AmazonS3Client)asyncResult.AsyncState; PutObjectResponse response = s3Client.EndPutObject(asyncResult); Console.WriteLine("Finished PutObject operation with client callback. Service Version: {0}", s3Client.Config.ServiceVersion); Console.WriteLine("--------------------------------------------------"); Console.WriteLine("Service Response:"); Console.WriteLine("-----------------"); Console.WriteLine("Request ID: {0}\n\n", response.ResponseMetadata.RequestId); } catch (AmazonS3Exception s3Exception) { Console.WriteLine("Caught exception calling EndPutObject:"); Console.WriteLine(s3Exception); } }
A linha de código a seguir chama BeginPutObject e especifica a função de retorno de chamadaanterior. Quando a operação PutObject for concluída, a função de retorno de chamada será chamada.Neste exemplo, a chamado ao BeginPutObject especifica o objeto do cliente do Amazon S3 para oparâmetro state. A função de retorno de chamada utiliza o cliente para chamar o método EndPutObjecta fim de recuperar a resposta do servidor. Como todas as exceções que ocorreram durante a operaçãoserão recebidas quando o retorno de chamada chamar EndPutObject, esta chamada é colocada em umbloco try.
asyncResult = client.BeginPutObject(request_client, CallbackWithClient, client);
54
AWS SDK para .NET Guia do desenvolvedorAPI assíncrona para .NET Framework 3.5
Retorno de chamada com objeto de estadoEste exemplo pressupõe que a classe e função de retorno de chamada a seguir foram definidas.
class ClientState { public AmazonS3Client Client { get; set; } public DateTime Start { get; set; } }
public static void CallbackWithState(IAsyncResult asyncResult) { try { ClientState state = asyncResult.AsyncState as ClientState; AmazonS3Client s3Client = (AmazonS3Client)state.Client; PutObjectResponse response = state.Client.EndPutObject(asyncResult); Console.WriteLine("Finished PutObject operation with state callback that started at {0}", state.Start.ToString()); Console.WriteLine("--------------------------------------------------"); Console.WriteLine("Service Response:"); Console.WriteLine("-----------------"); Console.WriteLine("Request ID: {0}\n\n", response.ResponseMetadata.RequestId); } catch (AmazonS3Exception s3Exception) { Console.WriteLine("Caught exception calling EndPutObject:"); Console.WriteLine(s3Exception); } }
A linha de código a seguir chama BeginPutObject e especifica a função de retorno de chamada acima.Quando a operação PutObject for concluída, a função de retorno de chamada será chamada. Nesteexemplo, a chamada ao BeginPutObject especifica, para o parâmetro state, uma instância da classeClientState definida anteriormente. Esta classe incorpora o cliente do Amazon S3, bem como o tempoem que BeginPutObject é chamado. A função de retorno de chamada utiliza o objeto do cliente doAmazon S3 para chamar o método EndPutObject a fim de recuperar a resposta do servidor. O retornode chamada também extrai o tempo de início da operação e usa-o para imprimir o tempo até conclusão daoperação assíncrona.
Da mesma forma que os exemplos anteriores, como as exceções que ocorreram durante a operação sãorecebidas quando EndPutObject é chamado, essa chamada é colocada em um bloco try.
asyncResult = client.BeginPutObject(request_state, CallbackWithState, new ClientState { Client = client, Start = DateTime.Now });
Exemplo completoO exemplo de código a seguir demonstra os padrões que podem ser usados ao chamar os métodos desolicitação assíncrona.
using System;using System.Threading;
using Amazon.S3;using Amazon.S3.Model;
namespace async_aws_net
55
AWS SDK para .NET Guia do desenvolvedorAPI assíncrona para .NET Framework 3.5
{ class ClientState { public AmazonS3Client Client { get; set; } public DateTime Start { get; set; } }
class Program { // // Function Main(). // Parse the command line and call the worker function. // public static void Main(string[] args) { if (args.Length != 1) { Console.WriteLine("You must supply the name of an existing Amazon S3 bucket."); return; }
TestPutObjectAsync(args[0]); }
// // Function SimpleCallback(). // A very simple callback function. // public static void SimpleCallback(IAsyncResult asyncResult) { Console.WriteLine("Finished PutObject operation with simple callback."); Console.WriteLine("--------------------------------------------------"); Console.WriteLine("asyncResult.IsCompleted: {0}\n\n", asyncResult.IsCompleted.ToString()); }
// // Function CallbackWithClient(). // A callback function that provides access to a given S3 client. // public static void CallbackWithClient(IAsyncResult asyncResult) { try { AmazonS3Client s3Client = (AmazonS3Client)asyncResult.AsyncState; PutObjectResponse response = s3Client.EndPutObject(asyncResult); Console.WriteLine("Finished PutObject operation with client callback. Service Version: {0}", s3Client.Config.ServiceVersion); Console.WriteLine("--------------------------------------------------"); Console.WriteLine("Service Response:"); Console.WriteLine("-----------------"); Console.WriteLine("Request ID: {0}\n\n", response.ResponseMetadata.RequestId); } catch (AmazonS3Exception s3Exception) { Console.WriteLine("Caught exception calling EndPutObject:"); Console.WriteLine(s3Exception); } }
// // Function CallbackWithState(). // A callback function that provides access to a given S3 client as well as state information.
56
AWS SDK para .NET Guia do desenvolvedorAPI assíncrona para .NET Framework 3.5
// public static void CallbackWithState(IAsyncResult asyncResult) { try { ClientState state = asyncResult.AsyncState as ClientState; AmazonS3Client s3Client = (AmazonS3Client)state.Client; PutObjectResponse response = state.Client.EndPutObject(asyncResult); Console.WriteLine("Finished PutObject operation with state callback that started at {0}", state.Start.ToString()); Console.WriteLine("--------------------------------------------------"); Console.WriteLine("Service Response:"); Console.WriteLine("-----------------"); Console.WriteLine("Request ID: {0}\n\n", response.ResponseMetadata.RequestId); } catch (AmazonS3Exception s3Exception) { Console.WriteLine("Caught exception calling EndPutObject:"); Console.WriteLine(s3Exception); } }
// // Function TestPutObjectAsync(). // Test synchronous and asynchronous variations of PutObject(). // public static void TestPutObjectAsync(string bucket) { // Create a client AmazonS3Client client = new AmazonS3Client();
PutObjectResponse response; IAsyncResult asyncResult;
// // Create a PutObject request object using the supplied bucket name. // PutObjectRequest request = new PutObjectRequest { BucketName = bucket, Key = "Item0-Synchronous", ContentBody = "Put S3 object synchronously." };
// // Perform a synchronous PutObject operation. // Console.WriteLine("-------------------------------------------------------------------------------"); Console.WriteLine("Performing synchronous PutObject operation for {0}.", request.Key); response = client.PutObject(request); Console.WriteLine("Finished PutObject operation for {0}.", request.Key); Console.WriteLine("Service Response:"); Console.WriteLine("-----------------"); Console.WriteLine("Request ID: {0}", response.ResponseMetadata.RequestId); Console.Write("\n");
// // Perform an async PutObject operation and wait for the response. // // (Re-use the existing PutObject request object since it isn't being used for another async request.) //
57
AWS SDK para .NET Guia do desenvolvedorAPI assíncrona para .NET Framework 3.5
request.Key = "Item1-Async-wait"; request.ContentBody = "Put S3 object asynchronously; wait for response."; Console.WriteLine("-------------------------------------------------------------------------------"); Console.WriteLine("Performing async PutObject operation and waiting for response (Key: {0}).", request.Key);
asyncResult = client.BeginPutObject(request, null, null); while (!asyncResult.IsCompleted) { // // Do some work here // } try { response = client.EndPutObject(asyncResult); } catch (AmazonS3Exception s3Exception) { Console.WriteLine("Caught exception calling EndPutObject:"); Console.WriteLine(s3Exception); }
Console.WriteLine("Finished Async PutObject operation for {0}.", request.Key); Console.WriteLine("Service Response:"); Console.WriteLine("-----------------"); Console.WriteLine("Request ID: {0}\n", response.ResponseMetadata.RequestId);
Console.WriteLine("-------------------------------------------------------------------------------"); Console.WriteLine("Performing the following async PutObject operations:"); Console.WriteLine("\"simple callback\", \"callback with client\", and \"callback with state\"...\n");
// // Perform an async PutObject operation with a simple callback. // // (Re-use the existing PutObject request object since it isn't being used for another async request.) // request.Key = "Item2-Async-simple"; request.ContentBody = "Put S3 object asynchronously; use simple callback.";
Console.WriteLine("PutObject with simple callback (Key: {0}).", request.Key); asyncResult = client.BeginPutObject(request, SimpleCallback, null);
// // Perform an async PutObject operation with a client callback. // // Create a PutObject request object for this call using the supplied bucket name. // PutObjectRequest request_client = new PutObjectRequest { BucketName = bucket, Key = "Item3-Async-client", ContentBody = "Put S3 object asynchronously; use callback with client." };
Console.WriteLine("PutObject with client callback (Key: {0}).", request_client.Key); asyncResult = client.BeginPutObject(request_client, CallbackWithClient, client);
//
58
AWS SDK para .NET Guia do desenvolvedorTentativas e tempos limite
// Perform an async PutObject operation with a state callback. // // Create a PutObject request object for this call using the supplied bucket name. // PutObjectRequest request_state = new PutObjectRequest { BucketName = bucket, Key = "Item3-Async-state", ContentBody = "Put S3 object asynchronously; use callback with state." };
Console.WriteLine("PutObject with state callback (Key: {0}).\n", request_state.Key); asyncResult = client.BeginPutObject(request_state, CallbackWithState, new ClientState { Client = client, Start = DateTime.Now });
// // Finished with async calls. Wait a bit for them to finish. // Thread.Sleep(TimeSpan.FromSeconds(5)); } }}
Também é possível visualizá-lo no GitHub.
Consulte também• Configurar o AWS SDK para .NET (p. 14)• Programação com o AWS SDK para .NET (p. 19)
Tentativas e tempos limiteO AWS SDK para .NET permite a configuração dos valores do número de tentativas e do tempo limite parasolicitações HTTP de serviços da AWS. Se os valores padrão para novas tentativas e tempos limite nãoforem apropriados, ajuste-os conforme os seus requisitos específicos, mas é importante entender comoessa ação afetará o comportamento do aplicativo.
Para determinar quais valores usar para tentativas e tempos limite, considere o seguinte:
• Como devem responder o AWS SDK para .NET e o aplicativo quando a qualidade da conexão coma rede piorar ou quando um serviço da AWS não estiver acessível? Deseja que a chamada falherapidamente, ou é apropriado que a chamada continue tentando em seu nome?
• O seu aplicativo é um aplicativo ou site voltado para o usuário e que deve ser responsivo, ou ele é umtrabalho de processamento em segundo plano com maior tolerância a latências?
• O aplicativo é implantado em uma rede confiável com baixa latência ou é implantado em um local remotocom conectividade incerta?
TentativasO AWS SDK para .NET realizará novas tentativas para as solicitações que falharem devido a limitaçõesno lado do servidor ou conexões perdidas. É possível usar a propriedade MaxErrorRetry da classeClientConfig para especificar o número de tentativas no nível do cliente do serviço. O AWS SDK para .NETrealizará o número especificado de novas tentativas para a operação antes que ocorra uma falha e seja
59
AWS SDK para .NET Guia do desenvolvedorTempo limite atingido
lançada uma exceção. Por padrão, a propriedade MaxErrorRetry é definida como 4, exceto para aclasse AmazonDynamoDBConfig, que possui 10 tentativas como padrão. Quando ocorre uma novatentativa, a latência da solicitação é aumentada. Configure as tentativas com base nos limites de latênciatotal da solicitação e taxas de erros do aplicativo.
Tempo limite atingidoO AWS SDK para .NET permite configurar os valores do tempo limite da solicitação e o tempo limitede leitura/gravação do soquete no nível do cliente do serviço. Esses valores são especificados naspropriedades Timeout e ReadWriteTimeout da classe ClientConfig, respectivamente. Esses valoressão transmitidos como as propriedades Timeout e ReadWriteTimeout dos objetos HttpWebRequestcriados pelo objeto do cliente do serviço da AWS. Por padrão, o valor Timeout é 100 segundos e o valorReadWriteTimeout é 300 segundos.
Quando a sua rede estiver com latência alta, ou existirem condições que gerem uma nova tentativa parauma operação, utilizar valores de tempo limite longos e um alto número de tentativas pode fazer com quealgumas operações do SDK pareçam indiferentes.
Note
A versão do AWS SDK para .NET que aponta para a biblioteca de classes portátil (PCL) usa aclasse HttpClient em vez da classe HttpWebRequest e oferece suporte apenas à propriedadeTimeout.
Veja a seguir as exceções aos valores de tempo limite padrão. Estes valores são substituídos ao definirexplicitamente os valores de tempo limite.
• Timeout e ReadWriteTimeout são definidos com os valores máximos se o método chamadofaz upload de um stream, como AmazonS3Client.PutObject(), AmazonS3Client.UploadPart(),AmazonGlacierClient.UploadArchive() e assim por diante.
• A versão do AWS SDK para .NET que aponta para o .NET Framework 4.5 define Timeout eReadWriteTimeout com os valores máximos para todos os objetos do AmazonS3Client eAmazonGlacierClient.
• A versão do AWS SDK para .NET que aponta para a biblioteca de classes portátil (PCL) define Timeoutcom o valor máximo para todos os objetos do AmazonS3Client e AmazonGlacierClient.
ExemploO exemplo a seguir mostra como especificar um máximo de duas tentativas, um tempo limite de 10segundos e um tempo limite de leitura/gravação de 10 segundos para um objeto do AmazonS3Client.
var client = new AmazonS3Client( new AmazonS3Config { Timeout = TimeSpan.FromSeconds(10), // Default value is 100 seconds ReadWriteTimeout = TimeSpan.FromSeconds(10), // Default value is 300 seconds MaxErrorRetry = 2 // Default value is 4 retries });
Migrar para a versão 3 do AWS SDK para .NETEste tópico descreve as alterações na versão 3 do AWS SDK para .NET e como migrar o seu código paraesta versão do SDK.
60
AWS SDK para .NET Guia do desenvolvedorSobre as versões do AWS SDK para .NET
Sobre as versões do AWS SDK para .NETO AWS SDK para .NET, lançado originalmente em novembro de 2009, foi projetado para o .NETFramework 2.0. Desde o lançamento, o .NET foi aperfeiçoado com o .NET Framework 4.0 e o .NETFramework 4.5, e adicionou novas plataformas de destino: WinRT e Windows Phone.
A versão 2 do AWS SDK para .NET foi atualizada para aproveitar os novos recursos da plataforma .NET epara atingir o WinRT e o Windows Phone.
A versão 3 do AWS SDK para .NET foi atualizada para tornar os conjuntos modulares.
Redefinição da arquitetura para o SDKToda a versão 3 do AWS SDK para .NET está redefinida para ser modular. Agora, cada serviço estáimplementado em seu próprio conjunto, em vez de um único conjunto global. Não é mais necessárioadicionar todo o AWS SDK para .NET ao aplicativo. Adicione conjuntos somente para os serviços da AWSutilizados pelo aplicativo.
Últimas alteraçõesAs seções a seguir descrevem as alterações na versão 3 do AWS SDK para .NET.
AWSClientFactory removidaA classe Amazon.AWSClientFactory foi removida. Agora, para criar um cliente de serviço, use oconstrutor do cliente de serviço. Por exemplo, para criar um AmazonEC2Client:
var ec2Client = new Amazon.EC2.AmazonEC2Client();
Amazon.Runtime.AssumeRoleAWSCredentials removidaA classe Amazon.Runtime.AssumeRoleAWSCredentials foi removida pois estava em um namespacecentral, mas tinha uma dependência no AWS Security Token Service, e porque era obsoleta no SDK poralgum tempo. No lugar, use a classe Amazon.SecurityToken.AssumeRoleAWSCredentials.
Método SetACL removido da S3LinkA classe S3Link faz parte do pacote Amazon.DynamoDBv2 e é usada para armazenar objetos noAmazon S3 que são referências em um item do DynamoDB. Este é um recurso útil, mas não queríamoscriar uma dependência de compilação no pacote Amazon.S3 para o DynamoDB. Consequentemente,simplificamos os métodos Amazon.S3 expostos da classe S3Link, substituindo o método SetACL pelométodo MakeS3ObjectPublic. Para obter mais controle sobre a lista de controle de acesso (ACL) noobjeto, use o pacote Amazon.S3 diretamente.
Remoção de classes de resultados obsoletasPara a maioria dos serviços do AWS SDK para .NET, as operações retornam um objeto de resposta quecontém metadados para a operação, como o ID da solicitação e um objeto de resultado. Ter classes deresultados e respostas separadas era redundante e gerava linhas extras para os desenvolvedores. Naversão 2 do AWS SDK para .NET, colocamos todas as informações da classe de resultados na classe derespostas. Também marcamos as classes de resultados como obsoletas para desencorajar o seu uso. Naversão 3 do AWS SDK para .NET, removemos essas classes de resultados obsoletas para ajudar a reduziro tamanho do SDK.
61
AWS SDK para .NET Guia do desenvolvedorMigrar para a versão 3.5
Alterações na seção AWS ConfigÉ possível realizar a configuração avançada do AWS SDK para .NET por meio dos arquivos App.configou Web.config. Faça isso por meio de uma seção de configuração da <aws> como a seguinte, que fazreferência ao nome do conjunto do SDK.
<configuration> <configSections> <section name="aws" type="Amazon.AWSSection, AWSSDK"/> </configSections> <aws region="us-west-2"> <logging logTo="Log4Net"/> </aws></configuration>
Na versão 3 do AWS SDK para .NET, o conjunto AWSSDK não existe mais. Colocamos o código comum noconjunto AWSSDK.Core. Como resultado, será necessário alterar as referências ao conjunto AWSSDK nosarquivos App.config ou Web.config para o conjunto AWSSDK.Core, como mostrado a seguir.
<configuration> <configSections> <section name="aws" type="Amazon.AWSSection, AWSSDK.Core"/> </configSections> <aws region="us-west-2"> <logging logTo="Log4Net"/> </aws></configuration>
Também é possível manipular as definições de configuração com a classe Amazon.AWSConfigs. Naversão 3 do AWS SDK para .NET, movemos as definições de configuração do DynamoDB da classeAmazon.AWSConfigs para a classe Amazon.AWSConfigsDynamoDB.
Migrar para a versão 3.5 do AWS SDK para .NETThis is prerelease documentation for a feature in preview release. It is subject to change.
A versão 3.5 do AWS SDK para .NET padroniza ainda mais a experiência do .NET fazendo a transição dosuporte para todas as variações que não sejam do Framework do SDK para o .NET Standard 2.0.
Este tópico descreve as alterações na versão 3.5 e o possível trabalho que talvez seja necessário paramigrar seu ambiente ou código da versão 3.
O que mudou na versão 3.5Veja a seguir o que mudou ou não no AWS SDK para .NET versão 3.5.
.NET Framework e .NET CoreO suporte ao .NET Framework e ao .NET Core não foi alterado.
XamarinOs projetos Xamarin (novos e existentes) devem ter como destino o .NET Standard 2.0. Consulte Suportedo .NET Standard 2.0 no Xamarin.Forms e Suporte à implementação do .NET.
62
AWS SDK para .NET Guia do desenvolvedorMigrar código síncrono
UnityOs aplicativos Unity devem ter como destino os perfis do .NET Standard 2.0 ou do .NET 4.x usando oUnity 2018.1 ou posterior. Para obter mais informações, consulte Suporte a perfis do .NET. Além disso,se estiver usando IL2CPP para criar, você deverá desativar a remoção de código adicionando um arquivolink.xml conforme descrito em Fazer referência ao AWS SDK para .NET Standard 2.0 do Unity, Xamarin ouUWP. Depois que transferir seu código para uma das bases de código recomendadas, seu aplicativo Unitypoderá acessar todos os serviços oferecidos pelo SDK.
Como o Unity oferece suporte ao .NET Standard 2.0, o pacote AWSSDK.Core do SDK versão 3.5 não temmais código específico do Unity, incluindo algumas funcionalidades de nível superior. Para proporcionaruma transição melhor, todo o código do Unity está disponível para referência no repositório aws/aws-sdk-unity-net do GitHub. Se encontrar uma funcionalidade ausente que afete seu uso da AWS com o Unity,você poderá registrar uma solicitação de recurso em https://github.com/aws/dotnet/issues.
Plataforma Universal do Windows (UWP)Dirija seu aplicativo UWP para a versão 16299 ou posterior (Fall Creators Update, versão 1709, lançadaem outubro de 2017).
Windows Phone e SilverlightA versão 3.5 do AWS SDK para .NET não oferece suporte a essas plataformas porque a Microsoft nãoestá mais desenvolvendo-as ativamente. Para obter mais informações, consulte:
• Fim do suporte ao Windows 10 Mobile• Fim do suporte ao Silverlight
Bibliotecas de classes portáteis legadas (PCLs baseadas emperfis)Considere redirecionar sua biblioteca para o .NET Standard. Para obter mais informações, consulteComparação com bibliotecas de classes portáteis da Microsoft.
Gerenciador do Amazon Cognito Sync e Gerenciador do AmazonMobile AnalyticsAbstrações de alto nível que facilitam o uso do Amazon Cognito Sync e do Amazon Mobile Analytics foramremovidas da versão 3.5 do AWS SDK para .NET. O AWS AppSync é a substituição preferida para oAmazon Cognito Sync. O Amazon Pinpoint é a substituição preferida para o Amazon Mobile Analytics.
Se o seu código for afetado pela falta de código de biblioteca de nível superior para o AWS AppSync e oAmazon Pinpoint, você poderá registrar seu interesse em um ou ambos os seguintes chamados do GitHub:https://github.com/aws/dotnet/issues/20 e https://github.com/aws/dotnet/issues/19. Também é possívelobter as bibliotecas para o Gerenciador do Amazon Cognito Sync e o Gerenciador do Amazon MobileAnalytics nos seguintes repositórios do GitHub: aws/amazon-cognito-sync-manager-net e aws/aws-mobile-analytics-manager-net.
Migrar código síncronoA versão 3.5 do AWS SDK para .NET oferece suporte somente a chamadas assíncronas para serviçosda AWS. Você deve alterar o código síncrono que deseja executar usando a versão 3.5 para que ele sejaexecutado de forma assíncrona.
63
AWS SDK para .NET Guia do desenvolvedorMigração do .NET Standard 1.3
Os trechos de código a seguir mostram como alterar o código síncrono para código assíncrono. O códigonesses trechos é usado para exibir o número de buckets do Amazon S3.
O código original chama ListBuckets.
private int GetNumberOfBuckets(){ using (var s3Client = new AmazonS3Client()) { var response = s3Client.ListBuckets(); return response.Buckets.Count; }}
// From the calling functionConsole.WriteLine("Number of Buckets: {0}", GetNumberOfBuckets());
Para usar a versão 3.5 do SDK, chame ListBucketsAsync.
private async Task<int> GetNumberOfBucketsAsync(){ using (var client = new AmazonS3Client()) { var response = await client.ListBucketsAsync(); return response.Buckets.Count; }}
// From the calling functionTask<int> response = GetNumberOfBucketsAsync();Console.WriteLine("Number of buckets: {0}", response.Result);
Migração do .NET Standard 1.3Em 27 de junho de 2019, a Microsoft encerrou o suporte para as versões .NET Core 1.0 e .NET Core1.1. De acordo com esse anúncio, a AWS terminará o suporte para o .NET Standard 1.3 no .AWS SDKpara .NET em 31 de dezembro de 2020.
A AWS continuará fornecendo atualizações de serviço e correções de segurança no AWS SDK para .NETem relação ao .NET Standard 1.3 até 1º de outubro de 2020. Após essa data, o alvo .NET Standard 1.3entrará no modo de Manutenção, o que significa que não será lançada nenhuma nova atualização; a AWSaplicará somente correções de bugs críticos e patches de segurança.
Em 31 de dezembro de 2020, o suporte para o NET Standard 1.3 no AWS SDK para .NET chegará aofim da vida útil. Após esta data, não será aplicada nenhuma correção de bugs ou patches de segurança.Artefatos criados com esse alvo continuarão disponíveis para download no NuGet.
O que você precisa fazer
• Se estiver executando aplicativos usando .NET Framework, você não será afetado.
• Se você estiver executando aplicativos usando .NET Core 2.0 ou superior, você não será afetado.
• Se estiver executando aplicativos usando .NET Core 1.0 ou .NET Core 1.1, faça a migração dosseus aplicativos para uma versão mais recente do .NET Core seguindo as instruções de migração daMicrosoft. Recomendamos no mínimo .NET Core 3.1.
64
AWS SDK para .NET Guia do desenvolvedorMigração do .NET Standard 1.3
• Se estiver executando aplicativos críticos para os negócios que não podem ser atualizados nestemomento, você poderá continuar usando sua versão atual do AWS SDK para .NET.
Se tiver dúvidas ou perguntas, entre em contato com o AWS Support.
65
AWS SDK para .NET Guia do desenvolvedorListar recursos da AWS usando o AWS CloudFormation
Exemplos de códigoOs exemplos a seguir demonstram como usar o AWS SDK para .NET para trabalhar com serviçosindividuais da AWS.
Encontre o código-fonte para esses exemplos e outros no repositório de exemplos de código no GitHubda documentação da AWS. Para sugerir um novo exemplo de código para a equipe de documentação daAWS considerar a produção, crie uma solicitação. A equipe está buscando produzir exemplos de códigoque abrangem cenários e casos de uso mais amplos, em vez de trechos de código simples que abrangemapenas chamadas de API individuais. Para obter instruções, consulte a seção Propor novos exemplos decódigo no Readme no GitHub.
Outros exemplos podem ser encontrados no GitHub.
Antes de começar, configure o AWS SDK para .NET (p. 14) e leia Programação com o AWS SDKpara .NET (p. 19).
Tópicos• Listar recursos da AWS usando o AWS CloudFormation (p. 66)• Autenticar usuários com o Amazon Cognito (p. 67)• Usar bancos de dados NoSQL do Amazon DynamoDB (p. 72)• Implantar aplicativos usando o Amazon EC2 (p. 93)• Armazenar dados de arquivamento usando o Amazon S3 Glacier (p. 119)• Como gerenciar usuários com o AWS Identity and Access Management (IAM) (p. 122)• Usar chaves do AWS KMS com o AmazonS3EncryptionClient no AWS SDK para .NET (p. 142)• Gerenciar recursos do Domain Name System (DNS) usando o Amazon Route 53 (p. 144)• Usar o armazenamento na Internet do Amazon Simple Storage Service (p. 149)• Enviar notificações da nuvem usando o Amazon Simple Notification Service (p. 149)• Enviar mensagens usando o Amazon SQS (p. 152)• Monitoramento de seus recursos da AWS usando o Amazon CloudWatch (p. 161)• Programar o AWS OpsWorks para trabalhar com pilhas e aplicativos (p. 172)• Programar suporte para serviços da AWS adicionais (p. 173)
Listar recursos da AWS usando o AWSCloudFormation
O AWS SDK para .NET oferece suporte ao AWS CloudFormation, que cria e provisiona implantaçõesda infraestrutura da AWS de forma previsível e repetida. Para obter mais informações, consulte Guia deconceitos básicos do AWS CloudFormation.
O exemplo a seguir mostra como usar as APIs de baixo nível para listar os recursos acessíveis no AWSCloudFormation.
// using Amazon.CloudFormation;// using Amazon.CloudFormation.Model;
var client = new AmazonCloudFormationClient();var request = new DescribeStacksRequest();var response = client.DescribeStacks(request);
foreach (var stack in response.Stacks)
66
AWS SDK para .NET Guia do desenvolvedorAutenticar usuários com o Amazon Cognito
{ Console.WriteLine("Stack: {0}", stack.StackName); Console.WriteLine(" Status: {0}", stack.StackStatus); Console.WriteLine(" Created: {0}", stack.CreationTime);
var ps = stack.Parameters;
if (ps.Any()) { Console.WriteLine(" Parameters:");
foreach (var p in ps) { Console.WriteLine(" {0} = {1}", p.ParameterKey, p.ParameterValue); }
} }
Para obter informações relacionadas à referência de API, consulte Amazon.CloudFormation eAmazon.CloudFormation.Model no AWS SDK for .NET API Reference.
Autenticar usuários com o Amazon CognitoUsando o Amazon Cognito Identity, você pode criar identidades exclusivas para os usuários e autenticá-laspara acesso seguro aos seus recursos da AWS, como o Amazon S3 ou o Amazon DynamoDB. O AmazonCognito Identity oferece suporte a provedores de identidade públicos, como Amazon, o Facebook, oTwitter/Digits e o Google, ou qualquer provedor compatível com OpenID Connect, bem como a identidadesnão autenticadas. O Amazon Cognito também é compatível com developer authenticated identities(identidades autenticadas pelo desenvolvedor), que permitem a você registrar e autenticar usuários pormeio de seu próprio processo de autenticação de back-end, sem deixar de usar o Amazon Cognito Syncpara sincronizar os dados do usuário e acessar os recursos da AWS.
Para obter mais informações sobre o Amazon Cognito, consulte o Amazon Cognito Developer Guide (Guiado desenvolvedor do Amazon Cognito)
Os exemplos de códigos a seguir mostram como usar o Amazon Cognito Identity facilmente. O exemplode Provedor de credenciais do Amazon Cognito mostra como criar e autenticar identidades de usuários.O exemplo da Biblioteca de extensões Amazon CognitoAuthentication mostra como usar a biblioteca deextensões CognitoAuthentication para autenticar grupos de usuários do Amazon Cognito.
Tópicos• Provedor de credenciais do Amazon Cognito (p. 67)• Exemplo da biblioteca de extensões Amazon CognitoAuthentication (p. 69)
Provedor de credenciais do Amazon CognitoAmazon.CognitoIdentity.CognitoAWSCredentials é um objeto de credenciais que usa o AmazonCognito e o AWS Security Token Service (AWS STS) para recuperar credenciais para fazer chamadas daAWS.
A primeira etapa da configuração do CognitoAWSCredentials é criar um "grupo de identidades". Umgrupo de identidades é um armazenamento de informações de identidades de usuários específico parasua conta. As informações podem ser recuperadas entre plataformas, dispositivos e sistemas operacionaisde clientes, para que, se um usuário começar a usar o aplicativo em um telefone e depois mudar para um
67
AWS SDK para .NET Guia do desenvolvedorProvedor de credenciais do Amazon Cognito
tablet, as informações mantidas do aplicativo ainda estejam disponíveis para esse usuário. Você podecriar um novo grupo de identidades no console do Amazon Cognito. Se você está usando o console, eletambém oferece outras informações de que você precisa:
• Seu número de conta – um número de 12 dígitos, como 123456789012, que é exclusivo para sua conta.• O ARN da função não autenticada – uma função que os usuários não autenticados assumirão. Por
exemplo, essa função pode fornecer permissões somente leitura aos seus dados.• O ARN da função autenticada – uma função que os usuários autenticados assumirão. Essa função pode
fornecer permissões mais amplas aos seus dados.
Configurar CognitoAWSCredentialsO código de exemplo a seguir mostra como configurar CognitoAWSCredentials, que você podeusar para fazer uma chamada para o Amazon S3 como usuário não autenticado. Isso permite que vocêfaça chamadas com apenas uma quantidade mínima de dados necessária para autenticar o usuário. Aspermissões de usuários são controladas pela função para que seja possível configurar o acesso conformenecessário.
CognitoAWSCredentials credentials = new CognitoAWSCredentials( accountId, // Account number identityPoolId, // Identity pool ID unAuthRoleArn, // Role for unauthenticated users null, // Role for authenticated users, not set region);using (var s3Client = new AmazonS3Client(credentials)){ s3Client.ListBuckets();}
Usar a AWS como um usuário não autenticadoO exemplo de código a seguir mostra como é possível começar a usar a AWS como usuário nãoautenticado e, depois, autenticar por meio do Facebook e atualizar as credenciais para usar as doFacebook. Usando essa abordagem, você pode conceder capacidades diferentes a usuários autenticadospor meio da função autenticada. Por exemplo, você pode ter um aplicativo de telefone que permite que osusuários visualizem conteúdo anonimamente, mas lhes permite publicar se eles estão conectados com umou mais dos provedores configurados.
CognitoAWSCredentials credentials = new CognitoAWSCredentials( accountId, identityPoolId, unAuthRoleArn, // Role for unauthenticated users authRoleArn, // Role for authenticated users region);using (var s3Client = new AmazonS3Client(credentials)){ // Initial use will be unauthenticated s3Client.ListBuckets();
// Authenticate user through Facebook string facebookToken = GetFacebookAuthToken();
// Add Facebook login to credentials. This clears the current AWS credentials // and retrieves new AWS credentials using the authenticated role. credentials.AddLogin("graph.facebook.com", facebookAccessToken);
// This call is performed with the authenticated role and credentials s3Client.ListBuckets();}
68
AWS SDK para .NET Guia do desenvolvedorExemplo da biblioteca de extensões
Amazon CognitoAuthentication
O objeto CognitoAWSCredentials oferecerá ainda mais funcionalidades se você usá-lo como AmazonCognitoSyncClient que faz parte do AWS SDK para .NET. Se você estiver usandoAmazonCognitoSyncClient e CognitoAWSCredentials, não precisará especificar as propriedadesIdentityPoolId e IdentityId ao fazer chamadas com o AmazonCognitoSyncClient. Essaspropriedades são preenchidas automaticamente em CognitoAWSCredentials. O exemplo decódigo a seguir ilustra isso, bem como um evento que notifica você sempre que o IdentityId paraCognitoAWSCredentials é alterado. O IdentityId pode ser alterado em alguns casos, como naalteração de um usuário não autenticado para um autenticado.
CognitoAWSCredentials credentials = GetCognitoAWSCredentials();
// Log identity changescredentials.IdentityChangedEvent += (sender, args) =>{ Console.WriteLine("Identity changed: [{0}] => [{1}]", args.OldIdentityId, args.NewIdentityId);};
using (var syncClient = new AmazonCognitoSyncClient(credentials)){ var result = syncClient.ListRecords(new ListRecordsRequest { DatasetName = datasetName // No need to specify these properties //IdentityId = "...", //IdentityPoolId = "..." });}
Exemplo da biblioteca de extensões AmazonCognitoAuthenticationA biblioteca de extensões CognitoAuthentication simplifica o processo de autenticação de grupos deusuários do Amazon Cognito para desenvolvedores de .NET Core e Xamarin. A biblioteca foi criadacom base na API do provedor de identidade do Amazon Cognito para criar e enviar chamadas de APIde autenticação de usuários. Você pode obter Amazon.Extensions.CognitoAuthentication na galeria doNuGet.
Uso da biblioteca de extensões CognitoAuthenticationO Amazon Cognito tem alguns valores de AuthFlow e ChallengeName incorporados para que um fluxode autenticação padrão valide o nome de usuário e a senha por meio de Secure Remote Password (SRP– Senha remota protegida) Para obter mais informações sobre o fluxo de autenticação, consulte AmazonCognito User Pool Authentication Flow (Fluxo de autenticação de grupos de usuários do Amazon Cognito).
Os exemplos a seguir exigem estas instruções using:
// Required for all examplesusing System;using Amazon;using Amazon.CognitoIdentity;using Amazon.CognitoIdentityProvider;using Amazon.Extensions.CognitoAuthentication;using Amazon.Runtime;// Required for the GetS3BucketsAsync exampleusing Amazon.S3;using Amazon.S3.Model;
69
AWS SDK para .NET Guia do desenvolvedorExemplo da biblioteca de extensões
Amazon CognitoAuthentication
Uso da autenticação básica
Crie um AmazonCognitoIdentityProviderClient usando AnonymousAWSCredentials, que não requeremsolicitações assinadas. Você não precisa fornecer uma região. O código subjacente chamaráFallbackRegionFactory.GetRegionEndpoint() se uma região não for fornecida. Crie objetosCognitoUserPool e CognitoUser. Chame o método StartWithSrpAuthAsync com umInitiateSrpAuthRequest que contenha a senha do usuário.
public static async void GetCredsAsync(){ AmazonCognitoIdentityProviderClient provider = new AmazonCognitoIdentityProviderClient(new Amazon.Runtime.AnonymousAWSCredentials()); CognitoUserPool userPool = new CognitoUserPool("poolID", "clientID", provider); CognitoUser user = new CognitoUser("username", "clientID", userPool, provider); InitiateSrpAuthRequest authRequest = new InitiateSrpAuthRequest() { Password = "userPassword" };
AuthFlowResponse authResponse = await user.StartWithSrpAuthAsync(authRequest).ConfigureAwait(false); accessToken = authResponse.AuthenticationResult.AccessToken;
}
Autenticar com desafios
Continuar o fluxo de autenticação com desafios, como com NewPasswordRequired e autenticaçãomultifator (MFA), também é mais simples. Os únicos requisitos são os objetos CognitoAuthentication, asenha do usuário para SRP e as informações necessárias para o próximo desafio, que são adquiridasdepois de solicitar que o usuário as insira. O código a seguir mostra uma maneira de verificar o tipo dedesafio e obter respostas adequadas para desafios de MFA e NewPasswordRequired durante o fluxo deautenticação.
Faça uma solicitação de autenticação básica como antes, e await um AuthFlowResponse.Quando a resposta for recebida, percorra o objeto retornado AuthenticationResult.Se o tipo de ChallengeName for NEW_PASSWORD_REQUIRED, chame o métodoRespondToNewPasswordRequiredAsync.
public static async void GetCredsChallengesAsync(){ AmazonCognitoIdentityProviderClient provider = new AmazonCognitoIdentityProviderClient(new Amazon.Runtime.AnonymousAWSCredentials()); CognitoUserPool userPool = new CognitoUserPool("poolID", "clientID", provider); CognitoUser user = new CognitoUser("username", "clientID", userPool, provider); InitiateSrpAuthRequest authRequest = new InitiateSrpAuthRequest(){ Password = "userPassword" };
AuthFlowResponse authResponse = await user.StartWithSrpAuthAsync(authRequest).ConfigureAwait(false);
while (authResponse.AuthenticationResult == null) { if (authResponse.ChallengeName == ChallengeNameType.NEW_PASSWORD_REQUIRED) { Console.WriteLine("Enter your desired new password:"); string newPassword = Console.ReadLine();
70
AWS SDK para .NET Guia do desenvolvedorExemplo da biblioteca de extensões
Amazon CognitoAuthentication
authResponse = await user.RespondToNewPasswordRequiredAsync(new RespondToNewPasswordRequiredRequest() { SessionID = authResponse.SessionID, NewPassword = newPassword }); accessToken = authResponse.AuthenticationResult.AccessToken; } else if (authResponse.ChallengeName == ChallengeNameType.SMS_MFA) { Console.WriteLine("Enter the MFA Code sent to your device:"); string mfaCode = Console.ReadLine();
AuthFlowResponse mfaResponse = await user.RespondToSmsMfaAuthAsync(new RespondToSmsMfaRequest() { SessionID = authResponse.SessionID, MfaCode = mfaCode
}).ConfigureAwait(false); accessToken = authResponse.AuthenticationResult.AccessToken; } else { Console.WriteLine("Unrecognized authentication challenge."); accessToken = ""; break; } }
if (authResponse.AuthenticationResult != null) { Console.WriteLine("User successfully authenticated."); } else { Console.WriteLine("Error in authentication process."); } }
Uso dos recursos da AWS após a autenticaçãoAssim que um usuário é autenticado usando a biblioteca CognitoAuthentication, a próxima etapa é permitirque o usuário acesse os recursos adequados da AWS. Para fazer isso, você deve criar um grupo deidentidades por meio do console de identidades federadas do Amazon Cognito. Ao especificar o grupode usuários do Amazon Cognito que você criou como provedor, usando seu poolID e clientID, vocêpode permitir que os usuários do grupo de usuários do Amazon Cognito acessem os recursos da AWSconectados à sua conta. Você também pode especificar diferentes funções para permitir que usuáriosautenticados e não autenticados acessem recursos diferentes. É possível alterar essas regras no consoledo IAM, em que você pode adicionar ou remover permissões no campo Action (Ação) da política associadada função. Em seguida, usando o grupo de identidades, o grupo de usuários e as informações de usuáriosdo Amazon Cognito adequadas, você pode fazer chamadas para recursos diferentes da AWS. O exemploa seguir mostra um usuário autenticado com SRP acessando os diferentes buckets do Amazon S3permitidos pela função do grupo de identidades associado
public async void GetS3BucketsAsync(){ var provider = new AmazonCognitoIdentityProviderClient(new AnonymousAWSCredentials()); CognitoUserPool userPool = new CognitoUserPool("poolID", "clientID", provider); CognitoUser user = new CognitoUser("username", "clientID", userPool, provider);
string password = "userPassword";
71
AWS SDK para .NET Guia do desenvolvedorUsar bancos de dados NoSQL do Amazon DynamoDB
AuthFlowResponse context = await user.StartWithSrpAuthAsync(new InitiateSrpAuthRequest() { Password = password }).ConfigureAwait(false);
CognitoAWSCredentials credentials = user.GetCognitoAWSCredentials("identityPoolID", RegionEndpoint.< YourIdentityPoolRegion >);
using (var client = new AmazonS3Client(credentials)) { ListBucketsResponse response = await client.ListBucketsAsync(new ListBucketsRequest()).ConfigureAwait(false);
foreach (S3Bucket bucket in response.Buckets) { Console.WriteLine(bucket.BucketName); } }}
Mais opções de autenticaçãoAlém de SRP, NewPasswordRequired e MFA, a biblioteca de extensões CognitoAuthentication oferece umfluxo de autenticação mais fácil para:
• Personalizado – iniciar com uma chamada paraStartWithCustomAuthAsync(InitiateCustomAuthRequest customRequest)
• RefreshToken – iniciar com uma chamada paraStartWithRefreshTokenAuthAsync(InitiateRefreshTokenAuthRequestrefreshTokenRequest)
• RefreshTokenSRP – iniciar com uma chamada paraStartWithRefreshTokenAuthAsync(InitiateRefreshTokenAuthRequestrefreshTokenRequest)
• AdminNoSRP – iniciar com uma chamada paraStartWithAdminNoSrpAuthAsync(InitiateAdminNoSrpAuthRequest adminAuthRequest)
Chame o método adequado de acordo com o fluxo que você deseja. Em seguida, continue abordando ousuário com desafios à medida que são apresentados nos objetos AuthFlowResponse de cada chamadade método. Além disso, chame o método de resposta adequado, como RespondToSmsMfaAuthAsyncpara desafios de MFA e RespondToCustomAuthAsync para desafios personalizados.
Usar bancos de dados NoSQL do AmazonDynamoDB
O AWS SDK para .NET oferece suporte ao Amazon DynamoDB, que é um serviço de banco de dadosNoSQL rápido oferecido pela AWS. O SDK fornece três módulos de programação para comunicar-se como DynamoDB: o modelo de baixo nível, o modelo de documento e o modelo de object persistência deobjetos.
A informações a seguir apresentam esses modelos e suas APIs, fornecem exemplos de como e quandousá-los e links para recursos de programação adicionais do DynamoDB no AWS SDK para .NET.
Tópicos
72
AWS SDK para .NET Guia do desenvolvedorModelo de baixo nível
• Modelo de baixo nível (p. 73)• Modelo de documento (p. 75)• Modelo de persistência de objeto (p. 76)• Mais informações (p. 78)• Usar expressões com Amazon DynamoDB e AWS SDK para .NET (p. 78)• Suporte a JSON no Amazon DynamoDB com o AWS SDK para .NET (p. 88)• Gerenciamento do estado da sessão ASP.NET com o Amazon DynamoDB (p. 90)
Modelo de baixo nívelO modelo de programação de baixo nível encapsula chamadas diretas para o serviço do DynamoDB. Vocêacessa esse modelo pelo namespace Amazon.DynamoDBv2.
Dos três modelos, o de baixo nível é o que exige que você escreva mais código. Por exemplo, você deveconverter tipos de dados .NET para seus equivalentes em DynamoDB. Contudo, esse modelo forneceacesso à maioria dos recursos.
Os exemplos a seguir mostram como usar o modelo de baixo nível para criar ou modificar uma tabela einserir itens em uma tabela no DynamoDB.
Criação de uma tabelaNo exemplo a seguir, você cria uma tabela usando o método CreateTable da classeAmazonDynamoDBClient. O método CreateTable usa uma instância da classeCreateTableRequest que contém características como nomes de atributo do item obrigatório, definiçãode chave primária e a capacidade de transferência. O método CreateTable retorna uma instância daclasse CreateTableResponse.
// using Amazon.DynamoDBv2;// using Amazon.DynamoDBv2.Model;
var client = new AmazonDynamoDBClient();
Console.WriteLine("Getting list of tables");List<string> currentTables = client.ListTables().TableNames;Console.WriteLine("Number of tables: " + currentTables.Count);if (!currentTables.Contains("AnimalsInventory")){ var request = new CreateTableRequest { TableName = "AnimalsInventory", AttributeDefinitions = new List<AttributeDefinition> { new AttributeDefinition { AttributeName = "Id", // "S" = string, "N" = number, and so on. AttributeType = "N" }, new AttributeDefinition { AttributeName = "Type", AttributeType = "S" } }, KeySchema = new List<KeySchemaElement> { new KeySchemaElement
73
AWS SDK para .NET Guia do desenvolvedorModelo de baixo nível
{ AttributeName = "Id", // "HASH" = hash key, "RANGE" = range key. KeyType = "HASH" }, new KeySchemaElement { AttributeName = "Type", KeyType = "RANGE" }, }, ProvisionedThroughput = new ProvisionedThroughput { ReadCapacityUnits = 10, WriteCapacityUnits = 5 }, };
var response = client.CreateTable(request);
Console.WriteLine("Table created with request ID: " + response.ResponseMetadata.RequestId);}
Verificação de que uma tabela está pronta para ser modificadaAntes que você possa alterar ou modificar uma tabela, esta tem de estar pronta para modificação.O exemplo a seguir mostra como usar o modelo de baixo nível para verificar se uma tabela noDynamoDB está pronta. Neste exemplo, a tabela de destino a ser verificada é mencionada pelo métodoDescribeTable da classe AmazonDynamoDBClient. A cada cinco segundos, o código verifica o valorda propriedade TableStatus da tabela. Quando o status é definido como ACTIVE, a tabela está prontapara ser modificada.
// using Amazon.DynamoDBv2;// using Amazon.DynamoDBv2.Model;
var client = new AmazonDynamoDBClient(); var status = "";
do{ // Wait 5 seconds before checking (again). System.Threading.Thread.Sleep(TimeSpan.FromSeconds(5)); try { var response = client.DescribeTable(new DescribeTableRequest { TableName = "AnimalsInventory" });
Console.WriteLine("Table = {0}, Status = {1}", response.Table.TableName, response.Table.TableStatus);
status = response.Table.TableStatus; } catch (ResourceNotFoundException) { // DescribeTable is eventually consistent. So you might // get resource not found. }
74
AWS SDK para .NET Guia do desenvolvedorModelo de documento
} while (status != TableStatus.ACTIVE);
Introdução um item em uma tabelaNo exemplo a seguir, você usa o modelo de baixo nível para inserir dois itens em uma tabela doDynamoDB. Cada item é inserido pelo método PutItem da classe AmazonDynamoDBClient usandouma instância da classe PutItemRequest. Cada uma das duas instâncias da classe PutItemRequestpega o nome da tabela em que os itens serão introduzidos, com uma série de valores de atributos de item.
// using Amazon.DynamoDBv2;// using Amazon.DynamoDBv2.Model;
var client = new AmazonDynamoDBClient();
var request1 = new PutItemRequest{ TableName = "AnimalsInventory", Item = new Dictionary<string, AttributeValue> { { "Id", new AttributeValue { N = "1" }}, { "Type", new AttributeValue { S = "Dog" }}, { "Name", new AttributeValue { S = "Fido" }} }};
var request2 = new PutItemRequest{ TableName = "AnimalsInventory", Item = new Dictionary<string, AttributeValue> { { "Id", new AttributeValue { N = "2" }}, { "Type", new AttributeValue { S = "Cat" }}, { "Name", new AttributeValue { S = "Patches" }} }}; client.PutItem(request1);client.PutItem(request2);
Modelo de documentoO modelo de programação de documento oferece uma maneira mais fácil para trabalhar com dados dentrodo DynamoDB. Esse modelo é destinado especificamente a acessar tabelas e itens nas tabelas. Vocêacessa esse modelo pelo namespace Amazon.DynamoDBv2.DocumentModel.
Em comparação com o modelo de programação de baixo nível, o modelo de documento é mais fácil decodificar com dados do DynamoDB. Por exemplo, não é necessário converter tantos tipos de dados .NETem seus equivalentes no DynamoDB. Contudo, esse modelo não fornece acesso a tantos recursos comoo modelo de programação de baixo nível. Por exemplo, você pode usar esse modelo para criar, recuperar,atualizar e excluir itens nas tabelas. No entanto, para criar as tabelas, é preciso usar o módulo de baixonível. Em comparação com o modelo de persistência de objetos, este modelo exige que você grave maiscódigo para armazenar, carregar e consultar objetos .NET.
Os exemplos a seguir mostram como usar o modelo de documentos para inserir itens e obter itens nastabelas do DynamoDB.
Introdução um item em uma tabelaNo exemplo a seguir, um item é introduzido na tabela com pelo método PutItem da classe Table. Ométodo PutItem leva uma instância da classe Document; a classe Document é simplesmente uma
75
AWS SDK para .NET Guia do desenvolvedorModelo de persistência de objeto
coleção de atributos inicializados. Para determinar a tabela na qual inserir o item, chame o métodoLoadTable da classe Table, especificando uma instância da classe AmazonDynamoDBClient e o nomeda tabela de destino no DynamoDB.
// using Amazon.DynamoDBv2;// using Amazon.DynamoDBv2.DocumentModel;
var client = new AmazonDynamoDBClient();var table = Table.LoadTable(client, "AnimalsInventory");var item = new Document();
item["Id"] = 3;item["Type"] = "Horse";item["Name"] = "Shadow";
table.PutItem(item);
Obtenção de um item de uma tabelaNo exemplo a seguir, o item é recuperado pelo método GetItem da classe Table. Para determinar oitem a ser obtido, o método GetItem usa a chave primária de hash e intervalo do item de destino. Paradeterminar a tabela de onde se obter o item, o método LoadTable da classe Table usa uma instância daclasse AmazonDynamoDBClient e o nome da tabela de destino no DynamoDB.
// using Amazon.DynamoDBv2;// using Amazon.DynamoDBv2.DocumentModel;
var client = new AmazonDynamoDBClient();var table = Table.LoadTable(client, "AnimalsInventory");var item = table.GetItem(3, "Horse");
Console.WriteLine("Id = " + item["Id"]);Console.WriteLine("Type = " + item["Type"]);Console.WriteLine("Name = " + item["Name"]);
O exemplo anterior converter implicitamente valores de atributo de Id, Type e Name em strings para ométodo WriteLine. Você pode fazer conversões explícitas usando os vários métodos AsType da classeDynamoDBEntry. Por exemplo, você pode converter explicitamente o valor do atributo para Id a partir dotipo de dados Primitive para um número inteiro pelo método AsInt:
int id = item["Id"].AsInt();
Ou você pode simplesmente executar um molde explícito aqui usando (int):
int id = (int)item["Id"];
Modelo de persistência de objetoO modelo de programação de persistência de objetos é especificamente projetado para armazenar,carregar e consultar objetos .NET no DynamoDB. Você acessa esse modelo pelo namespaceAmazon.DynamoDBv2.DataModel.
Dos três modelos, o modelo de persistência de objetos é o mais fácil de codificar sempre que você estiverarmazenando, carregando ou consultando dados do DynamoDB. Por exemplo, você trabalha diretamentecom tipos de dados do DynamoDB. Contudo, este modelo fornece acesso somente a operações quearmazenam, carregam e consultam objetos .NET no DynamoDB. Por exemplo, você pode usar esse
76
AWS SDK para .NET Guia do desenvolvedorModelo de persistência de objeto
modelo para criar, recuperar, atualizar e excluir itens nas tabelas. No entanto, é preciso primeiro criar suastabelas usando o modelo de baixo nível e, em seguida, usar esse modelo para mapear suas classes .NETpara as tabelas.
Os exemplos a seguir mostram como definir uma classe .NET que representa um item, usa uma instânciada classe .NET para inserir um item e usa uma instância de um objeto .NET para obter um item de umatabela DynamoDB.
Definição de uma classe .NET que represente um item em umatabelaNo exemplo a seguir, o atributo DynamoDBTable especifica o nome da tabela, enquanto os atributosDynamoDBHashKey e DynamoDBRangeKey modelam a chave principal de hash e intervalo.
// using Amazon.DynamoDBv2.DataModel;
[DynamoDBTable("AnimalsInventory")]class Item{ [DynamoDBHashKey] public int Id { get; set; } [DynamoDBRangeKey] public string Type { get; set; } public string Name { get; set; }}
Usando uma instância da classe .NET para inserir um item emuma tabelaNeste exemplo, o item é introduzido pelo método Save da classe DynamoDBContext, que pega umainstância inicializada da classe .NET que representa o item. (A instância da classe DynamoDBContext éinicializada com uma instância da classe AmazonDynamoDBClient.)
// using Amazon.DynamoDBv2;// using Amazon.DynamoDBv2.DataModel; var client = new AmazonDynamoDBClient();var context = new DynamoDBContext(client);var item = new Item{ Id = 4, Type = "Fish", Name = "Goldie"};
context.Save(item);
Uso de uma instância de um objeto .NET para obter um item deuma tabelaNeste exemplo, o item é recuperado pelo método Load da classe DynamoDBContext, que leva umainstância parcialmente inicializada da classe .NET que representa a chave primária de hash e intervalodo item a ser recuperado. (Como mostrado anteriormente, a instância da classe DynamoDBContext éinicializada com uma instância da classe AmazonDynamoDBClient.)
// using Amazon.DynamoDBv2;
77
AWS SDK para .NET Guia do desenvolvedorMais informações
// using Amazon.DynamoDBv2.DataModel;
var client = new AmazonDynamoDBClient();var context = new DynamoDBContext(client);var item = context.Load<Item>(4, "Fish");
Console.WriteLine("Id = {0}", item.Id);Console.WriteLine("Type = {0}", item.Type);Console.WriteLine("Name = {0}", item.Name);
Mais informaçõesUsar o AWS SDK para .NET para programar informações e exemplos do DynamoDB**
• APIs do DynamoDB• Kickoff do DynamoDB Series• DynamoDB Series – Modelo de documento• DynamoDB Series – Esquemas de conversão• DynamoDB Series – Modelo de persistência de objetos• DynamoDB Series – Expressões• Uso de expressões com Amazon DynamoDB e AWS SDK para .NET (p. 78)• Suporte a JSON no Amazon DynamoDB com o AWS SDK para .NET (p. 88)• Gerenciamento do estado da sessão ASP.NET com Amazon DynamoDB (p. 90)
Informações e exemplos do modelo de baixo nível
• Trabalho com tabelas usando a API de baixo nível do AWS SDK para .NET• Trabalho com itens usando a API de baixo nível do AWS SDK para .NET• Consulta de tabelas usando a API de baixo nível do AWS SDK para .NET• Digitalização de tabelas usando a API de baixo nível do AWS SDK para .NET• Trabalho com índices secundários locais usando a API de baixo nível do AWS SDK para .NET• Trabalho com índices secundários globais usando a API de baixo nível do AWS SDK para .NET
Informações e exemplos do modelo de documentos
• Tipos de dados do DynamoDB• DynamoDBEntry• .NET: Modelo de documento
Informações e exemplos do modelo de persistência de objetos
• .NET: Modelo de persistência de objeto
Usar expressões com Amazon DynamoDB e AWSSDK para .NETOs exemplos de código a seguir demonstram como usar o AWS SDK para .NET para programar oDynamoDB com expressões. As expressões denotam os atributos que você deseja ler de um item natabela do DynamoDB. Você também usa expressões ao gravar um item, de forma a indicar quaisquer
78
AWS SDK para .NET Guia do desenvolvedorUsar expressões com Amazon
DynamoDB e AWS SDK para .NET
condições devam ser atendidas (também conhecido como atualização condicional) e como os atributosdevem ser atualizados. Alguns exemplos de atualização substituem o atributo por um valor novo ouadicionam novos dados a uma lista ou um mapa. Para obter mais informações, consulte Reading andWriting Items Using Expressions (Leitura e gravação de itens usando expressões).
Tópicos• Dados de exemplo (p. 79)• Obtenha um único item usando expressões e a chave principal do item (p. 82)• Obtenha vários itens usando expressões e a chave principal da tabela (p. 82)• Obtenha vários itens usando expressões e outros atributos do item (p. 83)• Imprimir um item (p. 84)• Criar ou substituir um item usando expressões (p. 85)• Atualização de um item usando expressões (p. 87)• Exclusão de um item usando expressões (p. 87)• Mais informações (p. 88)
Dados de exemploOs exemplos de código neste tópico dependem dos dois itens de exemplo a seguir em uma tabela doDynamoDB chamada ProductCatalog. Esses itens descrevem as informações sobre entradas doproduto em um catálogo fictício de loja de bicicleta. Os itens são baseados no exemplo fornecido emCase Study: A ProductCatalog Item (Estudo de caso: um item ProductCatalog). Os descritores de tiposde dados, como BOOL, L, M, N, NS, S e SS, corresponde aos em JSON Data Format (Formato de dadosJSON).
{ "Id": { "N": "205" }, "Title": { "S": "20-Bicycle 205" }, "Description": { "S": "205 description" }, "BicycleType": { "S": "Hybrid" }, "Brand": { "S": "Brand-Company C" }, "Price": { "N": "500" }, "Gender": { "S": "B" }, "Color": { "SS": [ "Red", "Black" ] }, "ProductCategory": { "S": "Bike" }, "InStock": { "BOOL": true
79
AWS SDK para .NET Guia do desenvolvedorUsar expressões com Amazon
DynamoDB e AWS SDK para .NET
}, "QuantityOnHand": { "N": "1" }, "RelatedItems": { "NS": [ "341", "472", "649" ] }, "Pictures": { "L": [ { "M": { "FrontView": { "S": "http://example/products/205_front.jpg" } } }, { "M": { "RearView": { "S": "http://example/products/205_rear.jpg" } } }, { "M": { "SideView": { "S": "http://example/products/205_left_side.jpg" } } } ] }, "ProductReviews": { "M": { "FiveStar": { "SS": [ "Excellent! Can't recommend it highly enough! Buy it!", "Do yourself a favor and buy this." ] }, "OneStar": { "SS": [ "Terrible product! Do not buy this." ] } } }},{ "Id": { "N": "301" }, "Title": { "S": "18-Bicycle 301" }, "Description": { "S": "301 description" }, "BicycleType": { "S": "Road" }, "Brand": {
80
AWS SDK para .NET Guia do desenvolvedorUsar expressões com Amazon
DynamoDB e AWS SDK para .NET
"S": "Brand-Company C" }, "Price": { "N": "185" }, "Gender": { "S": "F" }, "Color": { "SS": [ "Blue", "Silver" ] }, "ProductCategory": { "S": "Bike" }, "InStock": { "BOOL": true }, "QuantityOnHand": { "N": "3" }, "RelatedItems": { "NS": [ "801", "822", "979" ] }, "Pictures": { "L": [ { "M": { "FrontView": { "S": "http://example/products/301_front.jpg" } } }, { "M": { "RearView": { "S": "http://example/products/301_rear.jpg" } } }, { "M": { "SideView": { "S": "http://example/products/301_left_side.jpg" } } } ] }, "ProductReviews": { "M": { "FiveStar": { "SS": [ "My daughter really enjoyed this bike!" ] }, "ThreeStar": { "SS": [ "This bike was okay, but I would have preferred it in my color.", "Fun to ride."
81
AWS SDK para .NET Guia do desenvolvedorUsar expressões com Amazon
DynamoDB e AWS SDK para .NET
] } } }}
Obtenha um único item usando expressões e a chave principaldo itemO exemplo a seguir apresenta o método Amazon.DynamoDBv2.AmazonDynamoDBClient.GetIteme um conjunto de expressões para obter e imprimir o item que tem um Id of 205. Somente os atributosa seguir do item são retornados: Id, Title, Description, Color, RelatedItems, Pictures eProductReviews.
// using Amazon.DynamoDBv2;// using Amazon.DynamoDBv2.Model;
var client = new AmazonDynamoDBClient();var request = new GetItemRequest{ TableName = "ProductCatalog", ProjectionExpression = "Id, Title, Description, Color, #ri, Pictures, #pr", ExpressionAttributeNames = new Dictionary<string, string> { { "#pr", "ProductReviews" }, { "#ri", "RelatedItems" } }, Key = new Dictionary<string, AttributeValue> { { "Id", new AttributeValue { N = "205" } } },};var response = client.GetItem(request);
// PrintItem() is a custom function.PrintItem(response.Item);
No exemplo anterior, a propriedade ProjectionExpression especifica os atributos a serem retornados.A propriedade ExpressionAttributeNames especifica o placeholder #pr para representar o atributoProductReviews e o placeholder #ri para representar o atributo RelatedItems. A chamada paraPrintItem refere-se uma função personalizada, como descrito em Imprimir um item (p. 84).
Obtenha vários itens usando expressões e a chave principal databelaO exemplo a seguir caracteriza o método Amazon.DynamoDBv2.AmazonDynamoDBClient.Query euma série de expressões para obter e imprimir o item que tenha um Id of 301, mas somente se o valorde Price for maior que 150. Somente os atributos a seguir do item são retornados: Id, Title e todos osatributos ThreeStar em ProductReviews.
// using Amazon.DynamoDBv2;// using Amazon.DynamoDBv2.Model;
var client = new AmazonDynamoDBClient();var request = new QueryRequest{ TableName = "ProductCatalog", KeyConditions = new Dictionary<string,Condition>
82
AWS SDK para .NET Guia do desenvolvedorUsar expressões com Amazon
DynamoDB e AWS SDK para .NET
{ { "Id", new Condition() { ComparisonOperator = ComparisonOperator.EQ, AttributeValueList = new List<AttributeValue> { new AttributeValue { N = "301" } } } } }, ProjectionExpression = "Id, Title, #pr.ThreeStar", ExpressionAttributeNames = new Dictionary<string, string> { { "#pr", "ProductReviews" }, { "#p", "Price" } }, ExpressionAttributeValues = new Dictionary<string,AttributeValue> { { ":val", new AttributeValue { N = "150" } } }, FilterExpression = "#p > :val"};var response = client.Query(request);
foreach (var item in response.Items){ // Write out the first page of an item's attribute keys and values. // PrintItem() is a custom function. PrintItem(item); Console.WriteLine("=====");}
No exemplo anterior, a propriedade ProjectionExpression especifica os atributos a serem retornados.A propriedade ExpressionAttributeNames especifica o espaço reservado #pr para representar oatributo ProductReviews e o espaço reservado #p para representar o atributo Price. #pr.ThreeStarespecifica para retornar somente o atributo ThreeStar. A propriedade ExpressionAttributeValuesespecifica o placeholder :val para representar o valor 150. A propriedade FilterExpressionespecifica que #p (Price) deve ser maior que :val (150). A chamada para PrintItem refere-se umafunção personalizada, como descrito em Imprimir um item (p. 84).
Obtenha vários itens usando expressões e outros atributos doitemO exemplo a seguir apresenta o método Amazon.DynamoDBv2.AmazonDynamoDBClient.Scane um conjunto de expressões para obter e imprimir todos os itens que tenham ProductCategoryof Bike. Somente os atributos a seguir do item são retornados: Id, Title e todos os atributos emProductReviews.
// using Amazon.DynamoDBv2;// using Amazon.DynamoDBv2.Model;
var client = new AmazonDynamoDBClient();var request = new ScanRequest{ TableName = "ProductCatalog", ProjectionExpression = "Id, Title, #pr", ExpressionAttributeValues = new Dictionary<string,AttributeValue> { { ":catg", new AttributeValue { S = "Bike" } } }, ExpressionAttributeNames = new Dictionary<string, string>
83
AWS SDK para .NET Guia do desenvolvedorUsar expressões com Amazon
DynamoDB e AWS SDK para .NET
{ { "#pr", "ProductReviews" }, { "#pc", "ProductCategory" } }, FilterExpression = "#pc = :catg", };var response = client.Scan(request);
foreach (var item in response.Items){ // Write out the first page/scan of an item's attribute keys and values. // PrintItem() is a custom function. PrintItem(item); Console.WriteLine("=====");}
No exemplo anterior, a propriedade ProjectionExpression especifica os atributos a serem retornados.A propriedade ExpressionAttributeNames especifica o placeholder #pr para representar o atributoProductReviews e o placeholder #pc para representar o atributo ProductCategory. A propriedadeExpressionAttributeValues especifica o placeholder :catg para representar o valor Bike. Apropriedade FilterExpression especifica que #pc (ProductCategory) deve ser igual a :catg(Bike). A chamada para PrintItem refere-se uma função personalizada, como descrito em Imprimir umitem (p. 84).
Imprimir um itemO exemplo a seguir mostra como imprimir os atributos e os valores de um item. Este exemplo é usadonos exemplos anteriores que mostram como Obter um único item usando expressões e a chave principaldo item (p. 82), Obter vários itens usando expressões e a chave principal da tabela (p. 82) e Obtervários itens usando expressões e outros atributos do item (p. 83).
// using Amazon.DynamoDBv2.Model;
// Writes out an item's attribute keys and values.public static void PrintItem(Dictionary<string, AttributeValue> attrs){ foreach (KeyValuePair<string, AttributeValue> kvp in attrs) { Console.Write(kvp.Key + " = "); PrintValue(kvp.Value); }}
// Writes out just an attribute's value.public static void PrintValue(AttributeValue value){ // Binary attribute value. if (value.B != null) { Console.Write("Binary data"); } // Binary set attribute value. else if (value.BS.Count > 0) { foreach (var bValue in value.BS) { Console.Write("\n Binary data"); } } // List attribute value. else if (value.L.Count > 0) {
84
AWS SDK para .NET Guia do desenvolvedorUsar expressões com Amazon
DynamoDB e AWS SDK para .NET
foreach (AttributeValue attr in value.L) { PrintValue(attr); } } // Map attribute value. else if (value.M.Count > 0) { Console.Write("\n"); PrintItem(value.M); } // Number attribute value. else if (value.N != null) { Console.Write(value.N); } // Number set attribute value. else if (value.NS.Count > 0) { Console.Write("{0}", string.Join("\n", value.NS.ToArray())); } // Null attribute value. else if (value.NULL) { Console.Write("Null"); } // String attribute value. else if (value.S != null) { Console.Write(value.S); } // String set attribute value. else if (value.SS.Count > 0) { Console.Write("{0}", string.Join("\n", value.SS.ToArray())); } // Otherwise, boolean value. else { Console.Write(value.BOOL); } Console.Write("\n");}
No exemplo anterior, cada valor do atributo tem várias propriedades específicas do tipo de dados, quepodem ser avaliadas para determinar o formato correto para imprimir o atributo. Essas propriedadesincluem B, BOOL, BS, L, M, N, NS, NULL, S e SS, que correspondem às no formato de dados JSON. Parapropriedades como B, N, NULL e S, se a propriedade correspondente não for null, o atributo será o tipode dados não null correspondente. Para propriedades como BS, L, M, NS e SS, se a propriedade Countfor maior que zero, o atributo será do tipo de dados não com valor não zero correspondente. Se todas aspropriedades específicas do tipo de dados do atributo forem null ou se Count for igual a zero, o atributocorresponderá ao tipo de dados BOOL.
Criar ou substituir um item usando expressõesO exemplo a seguir apresenta o método Amazon.DynamoDBv2.AmazonDynamoDBClient.PutItem eum conjunto de expressões para atualizar o item com Title of 18-Bicycle 301. Se o item não existirainda, será adicionado um novo item.
// using Amazon.DynamoDBv2;// using Amazon.DynamoDBv2.Model;
85
AWS SDK para .NET Guia do desenvolvedorUsar expressões com Amazon
DynamoDB e AWS SDK para .NET
var client = new AmazonDynamoDBClient();var request = new PutItemRequest{ TableName = "ProductCatalog", ExpressionAttributeNames = new Dictionary<string, string> { { "#title", "Title" } }, ExpressionAttributeValues = new Dictionary<string, AttributeValue> { { ":product", new AttributeValue { S = "18-Bicycle 301" } } }, ConditionExpression = "#title = :product", // CreateItemData() is a custom function. Item = CreateItemData()};client.PutItem(request);
No exemplo anterior, a propriedade ExpressionAttributeNames especifica o placeholder #title pararepresentar o atributo Title. A propriedade ExpressionAttributeValues especifica o placeholder:product para representar o valor 18-Bicycle 301. A propriedade ConditionExpressionespecifica que #title (Title) deve ser igual a :product (18-Bicycle 301). A chamada paraCreateItemData refere-se à seguinte função personalizada:
// using Amazon.DynamoDBv2.Model;
// Provides a sample item that can be added to a table.public static Dictionary<string, AttributeValue> CreateItemData(){ var itemData = new Dictionary<string, AttributeValue> { { "Id", new AttributeValue { N = "301" } }, { "Title", new AttributeValue { S = "18\" Girl's Bike" } }, { "BicycleType", new AttributeValue { S = "Road" } }, { "Brand" , new AttributeValue { S = "Brand-Company C" } }, { "Color", new AttributeValue { SS = new List<string>{ "Blue", "Silver" } } }, { "Description", new AttributeValue { S = "301 description" } }, { "Gender", new AttributeValue { S = "F" } }, { "InStock", new AttributeValue { BOOL = true } }, { "Pictures", new AttributeValue { L = new List<AttributeValue>{ { new AttributeValue { M = new Dictionary<string,AttributeValue>{ { "FrontView", new AttributeValue { S = "http://example/products/301_front.jpg" } } } } }, { new AttributeValue { M = new Dictionary<string,AttributeValue>{ { "RearView", new AttributeValue {S = "http://example/products/301_rear.jpg" } } } } }, { new AttributeValue { M = new Dictionary<string,AttributeValue>{ { "SideView", new AttributeValue { S = "http://example/products/301_left_side.jpg" } } } } } } } }, { "Price", new AttributeValue { N = "185" } }, { "ProductCategory", new AttributeValue { S = "Bike" } }, { "ProductReviews", new AttributeValue { M = new Dictionary<string,AttributeValue>{ { "FiveStar", new AttributeValue { SS = new List<string>{ "My daughter really enjoyed this bike!" } } }, { "OneStar", new AttributeValue { SS = new List<string>{ "Fun to ride.", "This bike was okay, but I would have preferred it in my color." } } } } } }, { "QuantityOnHand", new AttributeValue { N = "3" } }, { "RelatedItems", new AttributeValue { NS = new List<string>{ "979", "822", "801" } } } };
86
AWS SDK para .NET Guia do desenvolvedorUsar expressões com Amazon
DynamoDB e AWS SDK para .NET
return itemData;}
No exemplo anterior, um item de exemplo com dados de exemplo é retornado ao chamador. Uma série deatributos e valores correspondentes é construída usando os tipos de dados como BOOL, L, M, N, NS, S eSS, que correspondem aos do JSON Data Format (formato de dados JSON).
Atualização de um item usando expressõesO exemplo a seguir apresenta o método Amazon.DynamoDBv2.AmazonDynamoDBClient.UpdateIteme um conjunto de expressões para alterar Title para 18" Girl's Bike para o item com Id de 301.
// using Amazon.DynamoDBv2;// using Amazon.DynamoDBv2.Model;
var client = new AmazonDynamoDBClient();var request = new UpdateItemRequest{ TableName = "ProductCatalog", Key = new Dictionary<string,AttributeValue> { { "Id", new AttributeValue { N = "301" } } }, ExpressionAttributeNames = new Dictionary<string, string> { { "#title", "Title" } }, ExpressionAttributeValues = new Dictionary<string, AttributeValue> { { ":newproduct", new AttributeValue { S = "18\" Girl's Bike" } } }, UpdateExpression = "SET #title = :newproduct"};client.UpdateItem(request);
No exemplo anterior, a propriedade ExpressionAttributeNames especifica o placeholder #title pararepresentar o atributo Title. A propriedade ExpressionAttributeValues especifica o placeholder:newproduct para representar o valor 18" Girl's Bike. A propriedade UpdateExpressionespecifica a alteração de #title (Title) para :newproduct (18" Girl's Bike).
Exclusão de um item usando expressõesO exemplo a seguir caracteriza o métodoAmazon.DynamoDBv2.AmazonDynamoDBClient.DeleteItem e um conjunto de expressões paraexcluir o item com Id de 301, mas somente se o Title do item for 18-Bicycle 301.
// using Amazon.DynamoDBv2;// using Amazon.DynamoDBv2.Model;
var client = new AmazonDynamoDBClient();var request = new DeleteItemRequest{ TableName = "ProductCatalog", Key = new Dictionary<string,AttributeValue> { { "Id", new AttributeValue { N = "301" } } }, ExpressionAttributeNames = new Dictionary<string, string> { { "#title", "Title" }
87
AWS SDK para .NET Guia do desenvolvedorSuporte a JSON no Amazon
DynamoDB com o AWS SDK para .NET
}, ExpressionAttributeValues = new Dictionary<string, AttributeValue> { { ":product", new AttributeValue { S = "18-Bicycle 301" } } }, ConditionExpression = "#title = :product"};client.DeleteItem(request);
No exemplo anterior, a propriedade ExpressionAttributeNames especifica o placeholder #title pararepresentar o atributo Title. A propriedade ExpressionAttributeValues especifica o placeholder:product para representar o valor 18-Bicycle 301. A propriedade ConditionExpression especificaque #title (Title) deve ser igual a :product (18-Bicycle 301).
Mais informaçõesPara obter mais informações e exemplos de código, consulte:
• DynamoDB Series – Expressões• Acesso aos atributos do item com expressões de projeção• Uso de placeholders para nomes e valores de atributo• Especificação de condições com expressões de condição• Modificação de itens e atributos com expressões de atualização• Trabalho com itens usando a API de baixo nível do AWS SDK para .NET• Consulta de tabelas usando a API de baixo nível do AWS SDK para .NET• Digitalização de tabelas usando a API de baixo nível do AWS SDK para .NET• Trabalho com índices secundários locais usando a API de baixo nível do AWS SDK para .NET• Trabalho com índices secundários globais usando a API de baixo nível do AWS SDK para .NET
Suporte a JSON no Amazon DynamoDB com o AWSSDK para .NETO AWS SDK para .NET oferece suporte a dados JSON ao trabalhar com Amazon DynamoDB. Isso permiteque você obtenha dados formatados para JSON com mais facilidade e insira documentos em JSON nastabelas do DynamoDB.
Tópicos• Obtenha dados de uma tabela do DynamoDB em formato JSON (p. 88)• Inserir os dados do formato JSON em uma tabela do DynamoDB (p. 89)• Conversões do tipo de dados do DynamoDB para JSON (p. 89)• Mais informações (p. 90)
Obtenha dados de uma tabela do DynamoDB em formato JSONO exemplo a seguir mostra como obter dados de uma tabela do DynamoDB em formato JSON:
// using Amazon.DynamoDBv2;// using Amazon.DynamoDBv2.DocumentModel;
var client = new AmazonDynamoDBClient();
88
AWS SDK para .NET Guia do desenvolvedorSuporte a JSON no Amazon
DynamoDB com o AWS SDK para .NET
var table = Table.LoadTable(client, "AnimalsInventory");var item = table.GetItem(3, "Horse");
var jsonText = item.ToJson();Console.Write(jsonText); // Output:// {"Name":"Shadow","Type":"Horse","Id":3}
var jsonPrettyText = item.ToJsonPretty();Console.WriteLine(jsonPrettyText); // Output:// {// "Name" : "Shadow",// "Type" : "Horse",// "Id" : 3// }
No exemplo anterior, o método ToJson da classe Document converte um item da tabela em uma stringformatada para JSON. O item é recuperado pelo método GetItem da classe Table. Para determinar oitem a ser obtido, neste exemplo, o método GetItem usa a chave primária de hash e intervalo do item dedestino. Para determinar a tabela de onde se obter o item, o método LoadTable da classe Table usauma instância da classe AmazonDynamoDBClient e o nome da tabela de destino no DynamoDB.
Inserir os dados do formato JSON em uma tabela do DynamoDBO exemplo a seguir mostra como usar o formato JSON para inserir um item em uma tabela do DynamoDB:
// using Amazon.DynamoDBv2;// using Amazon.DynamoDBv2.DocumentModel;
var client = new AmazonDynamoDBClient();var table = Table.LoadTable(client, "AnimalsInventory");var jsonText = "{\"Id\":6,\"Type\":\"Bird\",\"Name\":\"Tweety\"}";var item = Document.FromJson(jsonText);
table.PutItem(item);
No exemplo anterior, o método FromJson da classe Document converte uma string formatadapara JSON em um item. O item é inserido na tabela pelo método PutItem da classe Table, queusa a instância da classe Document que contém o item. Para determinar a tabela na qual inserir oitem, o método LoadTable da classe Table é chamado, especificando uma instância da classeAmazonDynamoDBClient e o nome da tabela de destino no DynamoDB.
Conversões do tipo de dados do DynamoDB para JSONSempre que você chama o método ToJson da classe Document, e daí nos dados JSON resultantesvocê chamar o método FromJson para converter dados JSON de volta a uma instância de uma classeDocument, alguns tipos de dados do DynamoDB não serão convertidos como esperado. Especificamente:
• Conjuntos do DynamoDB (os tipos SS, NS e BS) serão convertidos em matrizes JSON.• Conjuntos e escalares binários do DynamoDB (os tipos B e BS) convertidos em strings JSON codificadas
para base64 ou em listas de strings.
Nesse cenário, você deverá chamar o método DecodeBase64Attributes da classe Document parasubstituir os dados de JSON codificados para base64 pela representação binária correta. O exemploa seguir substitui um atributo de item escalar binário codificado para base64 em uma instância de umaclasse Document, de nome Picture, pela representação binária correta. Este exemplo também faz o
89
AWS SDK para .NET Guia do desenvolvedorGerenciamento do estado da sessãoASP.NET com o Amazon DynamoDB
mesmo pelo atributo do item do conjunto binário codificado para base64 na mesma instância da classeDocument, de nome RelatedPictures:
item.DecodeBase64Attributes("Picture", "RelatedPictures");
Mais informaçõesPara obter mais informações e exemplos de programação JSON com DynamoDB usando o AWS SDKpara .NET, consulte:
• Suporte a JSON pelo DynamoDB• Atualização do Amazon DynamoDB – JSON, nível gratuito expandido, escalabilidade flexível, itens
maiores
Gerenciamento do estado da sessão ASP.NET com oAmazon DynamoDBOs aplicativos ASP.NET costumam armazenar dados de estado da sessão na memória. Contudo, essaabordagem não oferece uma boa escalabilidade. Após o aplicativo crescer além de um único servidorweb, o estado de sessão deverá ser compartilhado entre servidores. Uma solução comum é configurarum servidor de estado de sessão dedicada com o Microsoft SQL Server, mas essa abordagem teminconvenientes: você precisa administrar outra máquina; o servidor de estado de sessão é um ponto únicode falha; e o servidor de estado de sessão pode se tornar um gargalo de desempenho.
O DynamoDB, um armazenamento de banco de dados NoSQL da Amazon Web Services (AWS), ofereceuma solução econômica para compartilhar o estado da sessão entre servidores da web sem incorrer emnenhum desses inconvenientes.
Note
Não importa a solução que você escolher: esteja ciente de que o Amazon DynamoDB impõelimites sobre o tamanho de um item. Nenhum dos registros que você armazena no DynamoDBpodem exceder esse limite. Para obter mais informações, consulte Limites no DynamoDB no Guiado desenvolvedor do Amazon DynamoDB.
O AWS SDK para .NET inclui AWS.SessionProvider.dll, que contém um provedor de estadode sessão ASP.NET. Ele também inclui o exemplo AmazonDynamoDBSessionProviderSample, quedemonstra como usar Amazon DynamoDB como provedor de estado de sessão.
Para obter mais informações sobre como usar o estado de sessão com aplicativos ASP.NET, consulte adocumentação do MSDN.
Crie uma tabela do ASP.NET_SessionStateAo iniciar o aplicativo, ele procura pela tabela do Amazon DynamoDB de nome, por padrão,ASP.NET_SessionState. Recomendamos que você crie essa tabela antes de executar seu aplicativopela primeira vez.
Para criar a tabela ASP.NET_SessionState
1. Selecione Create Table (Criar tabela). O assistente para Create Table (Criar tabela) é aberto.2. Na caixa de texto Table name (nome da tabela), digite ASP.NET_SessionState.3. No campo Primary key (chave primária), digite SessionId e defina o tipo como String.4. Quando todas as suas opções forem inseridas como as desejar, selecione Create (Criar).
90
AWS SDK para .NET Guia do desenvolvedorGerenciamento do estado da sessãoASP.NET com o Amazon DynamoDB
A tabela ASP.NET_SessionState estará pronta para uso quando o status mudar de CREATING paraACTIVE.
Note
Se você decidir não criar a tabela de antemão, o provedor do estado da sessão criará a tabeladurante a inicialização. Consulte as opções de web.config abaixo para ver uma lista dosatributos que atuam como parâmetros de configuração para a tabela de estado da sessão. Se oprovedor criar a tabela, ela usará estes parâmetros.
Configure o provedor de estado da sessãoPara configurar um aplicativo ASP.NET para usar o DynamoDB como servidor de estado da sessão
1. Adicione referências tanto a AWSSDK.dll quanto a AWS.SessionProvider.dll ao seu projeto doVisual Studio ASP.NET. Esses conjuntos estão disponíveis ao instalar o AWS SDK para .NET (p. 17).Você também pode instalá-los usando NuGet (p. 15).
Em versões anteriores do SDK, a funcionalidade do provedor do estado da sessão estavacontida em AWS.Extension.dll. Para melhorar a usabilidade, a funcionalidade foi movida paraAWS.SessionProvider.dll. Para obter mais informações, consulte o post Como renomear aextensão da AWS.
2. Edite o arquivo Web.config do seu aplicativo. No elemento system.web, substitua o elementosessionState existente pelo seguinte fragmento XML:
<sessionState timeout="20" mode="Custom" customProvider="DynamoDBSessionStoreProvider"> <providers> <add name="DynamoDBSessionStoreProvider" type="Amazon.SessionProvider.DynamoDBSessionStateStore" AWSProfileName="{profile_name}" Region="us-west-2" /> </providers></sessionState>
O perfil representa as credenciais da AWS usadas para se comunicar com o DynamoDB paraarmazenar e recuperar o estado da sessão. Se você estiver usando o AWS SDK para .NET eespecificar um perfil na seção appSettings do arquivo Web.config do seu aplicativo, não precisaráespecificar um perfil na seção providers. O código do cliente .NET da AWS descobrirá no momentoda execução. Para obter mais informações, consulte Configuração do seu aplicativo AWS SDKpara .NET (p. 19).
Se o servidor web estiver sendo executado na instância do Amazon EC2 configurada para usar asfunções do IAM com as instâncias do EC2, você não precisará especificar nenhuma credencial noarquivo Web.config. Nesse caso, o cliente .NET da AWS usará as credenciais da função do IAM.Para obter mais informações, consulte Como conceder acesso usando uma função do IAM (p. 138) eConsiderações sobre segurança (p. 92).
Opções de Web.config
Você pode usar os seguintes atributos de configuração na seção providers do seu arquivoWeb.config:
AWSAccessKey
ID de chave de acesso a usar. Isso pode ser definido na seção providers ou appSettings.É recomendável não usar esta configuração. Em vez disso, especifique as credenciais usandoAWSProfileName para especificar um perfil.
91
AWS SDK para .NET Guia do desenvolvedorGerenciamento do estado da sessãoASP.NET com o Amazon DynamoDB
AWSSecretKey
Chave de secreta a ser usada. Isso pode ser definido na seção providers ou appSettings.É recomendável não usar esta configuração. Em vez disso, especifique as credenciais usandoAWSProfileName para especificar um perfil.
AWSProfileName
O nome de perfil associado com as credenciais que você deseja usar. Para obter mais informações,consulte Configuração do seu aplicativo AWS SDK para .NET (p. 19).
Região
Atributo string obrigatório. A região da AWS na qual usar o Amazon DynamoDB. Para obter umalista das regiões da AWS, consulte Regions and Endpoints: DynamoDB (Regiões e endpoints:DynamoDB).
Aplicativo
Atributo string opcional. O valor do atributo Application é usado para particionar os dados desessão na tabela, de forma que a tabela possa ser usada para mais de um aplicativo.
Tabela
Atributo string opcional. O nome da tabela usada para armazenar dados da sessão. O padrão éASP.NET_SessionState.
ReadCapacityUnits
Atributo int opcional. As unidades de capacidade de leitura a serem usadas se o provedor criar atabela. O padrão é 10.
WriteCapacityUnits
Atributo int opcional. As unidades de capacidade de gravação a serem usadas se o provedor criar atabela. O padrão é 5.
CreateIfNotExist
Atributo boolean opcional. O atributo CreateIfNotExist gerencia se o provedor criaráautomaticamente a tabela, caso ela ainda não exista. O padrão é verdadeiro. Se esse indicador fordefinido como falso e a tabela não existir, será emitida uma exceção.
Considerações sobre segurançaApós a tabela do DynamoDB ser criada e o aplicativo ser configurado, as sessões poderão ser usadascomo com qualquer outro provedor de sessão.
Como uma melhor prática de segurança, recomendamos a execução de seus aplicativos com ascredenciais de um usuário do Guia do usuário do IAM. É possível usar o Console de gerenciamento doIAM ou o AWS Toolkit for Visual Studio para criar os usuários do IAM e definir as políticas de acesso.
O provedor de estado da sessão precisa poder chamar as operações DeleteItem, DescribeTable, GetItem,PutItem e UpdateItem para a tabela que armazena os dados da sessão. As políticas de exemplo a seguirpodem ser usadas para restringir o usuário do IAM somente às operações necessárias pelo provedor parauma instância do DynamoDB executada em us-west-2:
{ "Version" : "2012-10-17","Statement" : [ { "Sid" : "1", "Effect" : "Allow", "Action" : [ "dynamodb:DeleteItem", "dynamodb:DescribeTable",
92
AWS SDK para .NET Guia do desenvolvedorImplantar aplicativos usando o Amazon EC2
"dynamodb:GetItem", "dynamodb:PutItem", "dynamodb:UpdateItem" ], "Resource" : "arn:aws:dynamodb:us-west-2:{<YOUR-AWS-ACCOUNT-ID>}:table/ASP.NET_SessionState" } ]}
Implantar aplicativos usando o Amazon EC2O AWS SDK para .NET oferece suporte ao Amazon EC2, que é um web service que oferece capacidadecomputacional redimensionável — literalmente, servidores nos datacenters da Amazon — usado paracompilar e hospedar os sistemas de software. As APIs do Amazon EC2 são fornecidas pelo conjuntoAWSSDK.EC2.
Os Exemplos de instâncias do Amazon EC2 (p. 93) têm como objetivo ajudá-lo a começar a usar oAmazon EC2.
Os exemplos de instâncias spot do Amazon EC2 (p. 111) mostram como usar as instâncias spot, quepermitem acessar a capacidade não utilizada do EC2 em até 90% em comparação com o preço dainstância sob demanda. O Amazon EC2 define os preços das instâncias spot e os ajusta gradualmentecom base em tendências de longo prazo na oferta e na demanda pela capacidade de instâncias spot.Você pode especificar o valor que está disposto a pagar por uma instância spot como uma porcentagemdo preço da instância sob demanda; os clientes cujas solicitações atendam ou excedam essa instânciaganham acesso às instâncias spot disponíveis.
Para obter mais informações, consulte Instâncias spot no Guia do usuário do Amazon EC2 para instânciasdo Linux e Instâncias spot no Guia do usuário do Amazon EC2 para instâncias do Windows.
Tópicos• Exemplos de instâncias do Amazon EC2 (p. 93)• Exemplos de instância spot do Amazon EC2 (p. 111)
Exemplos de instâncias do Amazon EC2É possível acessar os recursos do Amazon EC2 usando AWS SDK para .NET. Por exemplo, você podecriar, iniciar e finalizar as instâncias do Amazon EC2.
O código de exemplo é escrito em C#, mas é possível usar o AWS SDK para .NET com qualquerlinguagem compatível. Quando você instala o AWS Toolkit for Visual Studio, é instalada uma série demodelos de projetos C#. Portanto, a maneira mais fácil de iniciar esse projeto é abrir o Visual Studio e,em seguida, selecionar File, New Project, AWS Sample Projects, Compute and Networking, AWS EC2Sample.
Pré-requisitos
Para que você comece, é preciso ter criado uma conta da AWS e configurado suas credenciais da AWS.Para obter mais informações consulte Conceitos básicos do AWS SDK para .NET (p. 14).
Exemplos
Tópicos• Criar um cliente do Amazon EC2 (p. 94)• Criar um grupo de segurança no Amazon EC2 (p. 94)
93
AWS SDK para .NET Guia do desenvolvedorExemplos de instâncias do Amazon EC2
• Trabalhar com pares de chaves do Amazon EC2 (p. 98)• Iniciar uma instância Amazon EC2 (p. 100)• Encerramento de uma instância do Amazon EC2 (p. 105)• Uso de regiões e zonas de disponibilidade com Amazon EC2 (p. 106)• Uso de VPC endpoints com Amazon EC2 (p. 107)• Como usar endereços IP elásticos no Amazon EC2 (p. 109)
Criar um cliente do Amazon EC2Crie um cliente do Amazon EC2 para gerenciar os recursos do EC2, como instâncias e security groups.Este cliente é representado por um objeto AmazonEC2Client, que pode ser criado da seguinte forma:
var ec2Client = new AmazonEC2Client();
As permissões para o objeto do cliente são determinadas pela política anexada ao perfil especificado noarquivo App.config. Por padrão, usamos a região especificada em App.config. Para usar uma regiãodiferente, transmita o valor de RegionEndpoint apropriado para o construtor. Para obter mais informações,consulte Regiões e endpoints: EC2 no Referência geral do Amazon Web Services.
Criar um grupo de segurança no Amazon EC2No Amazon EC2, um security group atua como um firewall virtual que controla o tráfego de rede parauma ou mais instâncias do EC2. Por padrão, o Amazon EC2 associa as instâncias a um security groupque não permite tráfego de entrada. Você pode criar um security group que permita que as instâncias doEC2 aceitem um determinado tráfego. Por exemplo, se você precisar se conectar a uma instância do EC2em Windows, deverá configurar o security group para permitir tráfego RDP. É possível criar um grupo desegurança usando o console do Amazon EC2 ou o AWS SDK para .NET.
Um security group é criado para seu usado no EC2-Classic e EC2-VPC. Para obter mais informaçõessobre o EC2-Classic e o EC2-VPC, consulte Plataformas compatíveis no Guia do usuário do Amazon EC2para instâncias do Windows.
Como alternativa, você pode criar um security group usando o console do Amazon EC2. Para obter maisinformações, consulte Grupos de segurança do Amazon EC2 no Guia do usuário do Amazon EC2 parainstâncias do Windows.
Para obter informações sobre como criar um cliente do Amazon EC2, consulte Criar um cliente do AmazonEC2 (p. 94).
Enumerar seus security groupsVocê pode enumerar seus security groups e verificar se existe um security group.
Para enumerar seus security groups
Obtenha a lista completa dos grupos de segurança usando DescribeSecurityGroups sem parâmetros.
O exemplo a seguir enumera todos os security groups da região.
static void EnumerateSecurityGroups(AmazonEC2Client ec2Client){ var request = new DescribeSecurityGroupsRequest(); var response = ec2Client.DescribeSecurityGroups(request); List<SecurityGroup> mySGs = response.SecurityGroups; foreach (SecurityGroup item in mySGs) {
94
AWS SDK para .NET Guia do desenvolvedorExemplos de instâncias do Amazon EC2
Console.WriteLine("Security group: " + item.GroupId); Console.WriteLine("\tGroupId: " + item.GroupId); Console.WriteLine("\tGroupName: " + item.GroupName); Console.WriteLine("\tVpcId: " + item.VpcId);
Console.WriteLine(); }}
Para enumerar seus security groups para uma VPC específica
Use DescribeSecurityGroups com um filtro.
O exemplo a seguir recupera somente os security groups que pertencem à VPC especificada.
static void EnumerateVpcSecurityGroups(AmazonEC2Client ec2Client, string vpcID){ Filter vpcFilter = new Filter { Name = "vpc-id", Values = new List<string>() { vpcID } };
var request = new DescribeSecurityGroupsRequest(); request.Filters.Add(vpcFilter); var response = ec2Client.DescribeSecurityGroups(request); List<SecurityGroup> mySGs = response.SecurityGroups; foreach (SecurityGroup item in mySGs) { Console.WriteLine("Security group: " + item.GroupId); Console.WriteLine("\tGroupId: " + item.GroupId); Console.WriteLine("\tGroupName: " + item.GroupName); Console.WriteLine("\tVpcId: " + item.VpcId);
Console.WriteLine(); }}
Criar um grupo de segurançaSe você tentar criar um grupo de segurança com o nome de um grupo de segurança existente, oCreateSecurityGroup emitirá uma exceção. Para evitar isso, os exemplos a seguir pesquisam um grupo desegurança com o nome especificado e retornam o objeto de SecurityGroup apropriado, se for encontrado.
Para criar um security group para o EC2-Classic
Crie e inicialize um objeto CreateSecurityGroupRequest. Atribua um nome e uma descrição àspropriedades GroupName e Description, respectivamente.
O método CreateSecurityGroup retorna um objeto CreateSecurityGroupResponse. Você pode obtero identificador do novo grupo de segurança na resposta e então usar DescribeSecurityGroups com oidentificador do grupo de segurança para obter o objeto SecurityGroup para o grupo de segurança.
static SecurityGroup CreateEc2SecurityGroup( AmazonEC2Client ec2Client, string secGroupName){ // See if a security group with the specified name already exists Filter nameFilter = new Filter(); nameFilter.Name = "group-name"; nameFilter.Values= new List<string>() { secGroupName };
95
AWS SDK para .NET Guia do desenvolvedorExemplos de instâncias do Amazon EC2
var describeRequest = new DescribeSecurityGroupsRequest(); describeRequest.Filters.Add(nameFilter); var describeResponse = ec2Client.DescribeSecurityGroups(describeRequest);
// If a match was found, return the SecurityGroup object for the security group if(describeResponse.SecurityGroups.Count > 0) { return describeResponse.SecurityGroups[0]; }
// Create the security group var createRequest = new CreateSecurityGroupRequest(); createRequest.GroupName = secGroupName; createRequest.Description = "My sample security group for EC2-Classic";
var createResponse = ec2Client.CreateSecurityGroup(createRequest);
var Groups = new List<string>() { createResponse.GroupId }; describeRequest = new DescribeSecurityGroupsRequest() { GroupIds = Groups }; describeResponse = ec2Client.DescribeSecurityGroups(describeRequest); return describeResponse.SecurityGroups[0];}
Para criar um security group para o EC2-VPC
Crie e inicialize um objeto CreateSecurityGroupRequest. Atribua valores para as propriedadesGroupName, Description e VpcId.
O método CreateSecurityGroup retorna um objeto CreateSecurityGroupResponse. É possível obter oidentificador do novo grupo de segurança na resposta e, depois, usar DescribeSecurityGroups com oidentificador do grupo de segurança para obter o objeto SecurityGroup para o grupo de segurança.
static SecurityGroup CreateVpcSecurityGroup( AmazonEC2Client ec2Client, string vpcId, string secGroupName){ // See if a security group with the specified name already exists Filter nameFilter = new Filter(); nameFilter.Name = "group-name"; nameFilter.Values = new List<string>() { secGroupName };
var describeRequest = new DescribeSecurityGroupsRequest(); describeRequest.Filters.Add(nameFilter); var describeResponse = ec2Client.DescribeSecurityGroups(describeRequest);
// If a match was found, return the SecurityGroup object for the security group if (describeResponse.SecurityGroups.Count > 0) { return describeResponse.SecurityGroups[0]; }
// Create the security group var createRequest = new CreateSecurityGroupRequest(); createRequest.GroupName = secGroupName; createRequest.Description = "My sample security group for EC2-VPC"; createRequest.VpcId = vpcId;
var createResponse = ec2Client.CreateSecurityGroup(createRequest);
var Groups = new List<string>() { createResponse.GroupId }; describeRequest = new DescribeSecurityGroupsRequest() { GroupIds = Groups }; describeResponse = ec2Client.DescribeSecurityGroups(describeRequest); return describeResponse.SecurityGroups[0];
96
AWS SDK para .NET Guia do desenvolvedorExemplos de instâncias do Amazon EC2
}
Adicionar regras ao grupo de segurançaSiga este procedimento para adicionar uma regra para permitir tráfego de entrada na porta TCP 3389(RDP). Isso permite que você se conecte a uma instância do Windows. Se você executar uma instância doLinux, use a porta TCP 22 (SSH).
Note
Também é possível usar um serviço para obter o endereço IP público do seu computador local.Por exemplo, nós fornecemos o seguinte serviço: http://checkip.amazonaws.com/. Para localizaroutro serviço que forneça o endereço IP, use a frase de busca "qual é o meu endereço IP". Seestiver conectado por meio de um ISP ou atrás de um firewall sem um endereço IP estático,localize o intervalo de endereços IP usado por computadores cliente.
Os exemplos desta seção seguem os exemplos das seções anteriores. Eles pressupõem que secGroup éum security group existente.
Para adicionar uma regra ao security group
1. Crie e inicializa um objeto IpPermission.
string ipRange = "1.1.1.1/1";List<string> ranges = new List<string>() { ipRange };
var ipPermission = new IpPermission();ipPermission.IpProtocol = "tcp";ipPermission.FromPort = 3389;ipPermission.ToPort = 3389;ipPermission.IpRanges = ranges;
IpProtocol
O protocolo IP.FromPort e ToPort
O início e o final do intervalo de porta. Este exemplo especifica uma única porta, a 3389, usadapara se comunicar com Windows sobre RDP.
IpRanges
Os endereços IP ou intervalos de endereços, em notação CIDR. Para a conveniência, esteexemplo usa 72.21.198.64/24, que autoriza o tráfego de rede para um único endereço IP.Você pode usar http://checkip.amazonaws.com/ para determinar seu próprio endereço IP.
2. Crie e inicialize um objeto AuthorizeSecurityGroupIngressRequest.
var ingressRequest = new AuthorizeSecurityGroupIngressRequest();ingressRequest.GroupId = secGroup.GroupId;ingressRequest.IpPermissions.Add(ipPermission);
GroupId
O identificador do security group.IpPermissions
O objeto IpPermission da etapa 1.3. (Opcional) Você pode adicionar regras adicionais à coleção IpPermissions antes de passar para a
próxima etapa.
97
AWS SDK para .NET Guia do desenvolvedorExemplos de instâncias do Amazon EC2
4. Passe o objeto AuthorizeSecurityGroupIngressRequest para o métodoAuthorizeSecurityGroupIngress, que retornará um objeto AuthorizeSecurityGroupIngressResponse. Seuma regra correspondente já existir, será emitida uma AmazonEC2Exception.
try{ var ingressResponse = ec2Client.AuthorizeSecurityGroupIngress(ingressRequest); Console.WriteLine("New RDP rule for: " + ipRange);}catch (AmazonEC2Exception ex){ // Check the ErrorCode to see if the rule already exists if ("InvalidPermission.Duplicate" == ex.ErrorCode) { Console.WriteLine("An RDP rule for: {0} already exists.", ipRange); } else { // The exception was thrown for another reason, so re-throw the exception throw; }}
Trabalhar com pares de chaves do Amazon EC2O Amazon EC2 utiliza criptografia de chave pública para criptografar e descriptografar as informaçõesde login. A criptografia de chave pública utiliza uma chave pública para criptografar dados, em seguidao destinatário usa a chave privada para descriptografar os dados. As chaves pública e privada sãoconhecidas como par de chaves. É necessário especificar um par de chaves ao executar uma instância doEC2 e especificar a chave privada do par de chaves ao se conectar à instância. É possível criar um par dechaves ou usar algum que foi usado ao executar outras instâncias. Para obter mais informações, consultePares de chaves do Amazon EC2 no Guia do usuário do Amazon EC2 para instâncias do Windows. Esteexemplo mostra como criar um par de chaves, descrever pares de chaves e excluir um par de chavesusando estes métodos do AmazonEC2Client:
• CreateKeyPair• DeleteKeyPair• DescribeKeyPairs
Para obter informações sobre como criar um cliente do Amazon EC2, consulte Criar um cliente do AmazonEC2 (p. 94).
Criar um par de chaves e salvar a chave privada
Ao criar um novo par de chaves, é necessário salvar a chave privada retornada. Não é possível recuperara chave privada posteriormente.
Crie e inicialize um objeto CreateKeyPairRequest. Defina a propriedade KeyName como o nome do par dechaves.
Passe o objeto de requisição para o método CreateKeyPair, que retorna um objetoCreateKeyPairResponse. Se já existir um par de chaves com o nome especificado, é lançada umaAmazonEC2Exception.
O objeto de resposta inclui um objeto CreateKeyPairResponse que contém o objeto KeyPair da novachave. A propriedade KeyMaterial do objeto KeyPair contém a chave privada não criptografadado par de chaves. Salve a chave privada como um arquivo .pem em um local seguro. Este arquivo
98
AWS SDK para .NET Guia do desenvolvedorExemplos de instâncias do Amazon EC2
será necessário ao se conectar à instância. Este exemplo salva a chave privada no nome de arquivoespecificado.
public static void CreateKeyPair( AmazonEC2Client ec2Client, string keyPairName, string privateKeyFile){ var request = new CreateKeyPairRequest(); request.KeyName = keyPairName;
try { var response = ec2Client.CreateKeyPair(request); Console.WriteLine(); Console.WriteLine("New key: " + keyPairName);
// Save the private key in a .pem file using (FileStream s = new FileStream(privateKeyFile, FileMode.Create)) using (StreamWriter writer = new StreamWriter(s)) { writer.WriteLine(response.KeyPair.KeyMaterial); } } catch (AmazonEC2Exception ex) { // Check the ErrorCode to see if the key already exists if("InvalidKeyPair.Duplicate" == ex.ErrorCode) { Console.WriteLine("The key pair \"{0}\" already exists.", keyPairName); } else { // The exception was thrown for another reason, so re-throw the exception. throw; } }}
.. _enumerate-key-pairs:
Enumerar os pares de chavesEnumere os pares de chaves e verifique se um par de chaves existe.
Obtenha a lista completa dos pares de chaves usando o método DescribeKeyPairs sem parâmetros.
public static void EnumerateKeyPairs(AmazonEC2Client ec2Client){ var request = new DescribeKeyPairsRequest(); var response = ec2Client.DescribeKeyPairs(request);
foreach (KeyPairInfo item in response.KeyPairs) { Console.WriteLine("Existing key pair: " + item.KeyName); }}
.. _delete-key-pairs:
Excluir pares de chavesExclua um par de chaves ao chamar o DeleteKeyPair na instância do AmazonEC2Client.
99
AWS SDK para .NET Guia do desenvolvedorExemplos de instâncias do Amazon EC2
Transmita uma DeleteKeyPairRequest que contém o nome do par de chaves para o método DeleteKeyPairdo objeto AmazonEC2Client.
public static void DeleteKeyPair( AmazonEC2Client ec2Client, KeyPair keyPair){ try { // Delete key pair created for sample ec2Client.DeleteKeyPair(new DeleteKeyPairRequest { KeyName = keyPair.KeyName }); } catch (AmazonEC2Exception ex) { // Check the ErrorCode to see if the key already exists if ("InvalidKeyPair.NotFound" == ex.ErrorCode) { Console.WriteLine("The key pair \"{0}\" was not found.", keyPair.KeyName); } else { // The exception was thrown for another reason, so re-throw the exception throw; } }}
Iniciar uma instância Amazon EC2Use o procedimento a seguir para executar uma ou mais instâncias do Amazon EC2 configuradas deforma idêntica na mesma imagem de máquina da Amazon (AMI). Depois de criar as instâncias do EC2,você poderá verificar o status. Quando suas instâncias do EC2 estiverem sendo executadas, você poderáse conectar a elas.
Para obter informações sobre como criar um cliente do Amazon EC2, consulte Criar um cliente do AmazonEC2 (p. 94).
Executar uma instância do EC2 no EC2-Classic ou em uma VPCVocê pode executar uma instância no EC2-Classic ou em uma VPC. Para obter mais informações sobreo EC2-Classic e o EC2-VPC, consulte Plataformas compatíveis no Guia do usuário do Amazon EC2 parainstâncias do Windows.
Para obter uma lista de grupos de segurança e suas propriedades GroupId, consulte Enumerar seusgrupos de segurança (p. 94).
Para executar uma instância do EC2 no EC2-Classic
1. Crie e inicialize um objeto RunInstancesRequest. Certifique-se de que a AMI, o par de chaves e osecurity group que você especificar existem na região especificada ao criar o objeto do cliente.
string amiID = "ami-e189c8d1";string keyPairName = "my-sample-key";
List<string> groups = new List<string>() { mySG.GroupId };var launchRequest = new RunInstancesRequest(){ ImageId = amiID, InstanceType = InstanceType.T1Micro, MinCount = 1, MaxCount = 1,
100
AWS SDK para .NET Guia do desenvolvedorExemplos de instâncias do Amazon EC2
KeyName = keyPairName, SecurityGroupIds = groups};
ImageId
O ID da AMI. Para uma lista de AMIs públicas, consulte Amazon Machine Images.InstanceType
Um tipo de instância compatível com a AMI especificada. Para obter mais informações, consulteTipos de instância no Guia do usuário do Amazon EC2 para instâncias do Windows.
MinCount
O número mínimo de instâncias do EC2 a serem executadas. Se isso for mais instâncias do que oAmazon EC2 pode executar na zona de disponibilidade de destino, o Amazon EC2 não executaránenhuma instância.
MaxCount
O número máximo de instâncias do EC2 a serem executadas. Se isso for mais instâncias do queo Amazon EC2 pode executar na zona de disponibilidade de destino, o Amazon EC2 executará omaior número possível de instâncias acima de MinCount. É possível executar entre 1 e o númeromáximo de instâncias às quais você tem permissão para o tipo de instância. Para obter maisinformações, consulte How many instances can I run in Amazon EC2 (Quantas instâncias possoexecutar no Amazon EC2) nas perguntas frequentes gerais do Amazon EC2.
KeyName
O nome do par de chaves do EC2. Se você iniciar uma instância sem especificar um par dechaves, não poderá se conectar a ela. Para mais informações, consulte Trabalho com pares dechave do Amazon EC2 (p. 98).
SecurityGroupIds
Os identificadores de um ou mais security groups. Para obter mais informações, consulte Criaçãode um security group no Amazon EC2 (p. 94).
2. (Opcional) Para executar a instância com uma função do IAM (p. 138), especifique um perfil deinstância do IAM no objeto RunInstancesRequest.
Um usuário do IAM não pode executar uma instância com a função do IAM sem permissõesconcedidas pela política a seguir.
{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": [ "iam:PassRole", "iam:ListInstanceProfiles", "ec2:*" ], "Resource": "*" }] }
Por exemplo, o snippet a seguir instancia e configura um objeto IamInstanceProfileSpecification parauma função do IAM denominado winapp-instance-role-1.
var instanceProfile = new IamInstanceProfile();instanceProfile.Id = "winapp-instance-role-1";
101
AWS SDK para .NET Guia do desenvolvedorExemplos de instâncias do Amazon EC2
Para especificar esse perfil de instância no objeto RunInstancesRequest, adicione a linha a seguir.
launchRequest.IamInstanceProfile = instanceProfile;
3. Execute a instância passando o objeto da solicitação para o método RunInstances. Salve o ID deinstância, pois você precisará dele para gerenciar a instância.
Use o objeto RunInstancesResponse retornado para obter os IDs de instância para as novasinstâncias. A propriedade Reservation.Instances contém uma lista de objetos da Instance(Instância), um para cada instância do EC2 que você tiver implementado com êxito. Você poderecuperar o ID para cada instância na propriedade InstanceId do objeto da instância.
var launchResponse = ec2Client.RunInstances(launchRequest);var instances = launchResponse.Reservation.Instances;var instanceIds = new List<string>();foreach (Instance item in instances){ instanceIds.Add(item.InstanceId); Console.WriteLine(); Console.WriteLine("New instance: " + item.InstanceId); Console.WriteLine("Instance state: " + item.State.Name);}
Para executar uma instância do EC2 em uma VPC
1. Crie e inicialize uma interface de rede elástica em uma sub-rede da VPC.
string subnetID = "subnet-cb663da2";
List<string> groups = new List<string>() { mySG.GroupId };var eni = new InstanceNetworkInterfaceSpecification(){ DeviceIndex = 0, SubnetId = subnetID, Groups = groups, AssociatePublicIpAddress = true};List<InstanceNetworkInterfaceSpecification> enis = new List<InstanceNetworkInterfaceSpecification>() {eni};
DeviceIndex
O índice do dispositivo na instância para o anexo da interface de rede.SubnetId
O ID da sub-rede na qual a instância será executada.Groups
Um ou mais security groups. Para obter mais informações, consulte Criação de um security groupno Amazon EC2 (p. 94).
AssociatePublicIpAddress
Indica se um endereço IP público deve ou não ser atribuído automaticamente à instância em umaVPC.
2. Crie e inicialize um objeto RunInstancesRequest. Certifique-se de que a AMI, o par de chaves e osecurity group que você especificar existem na região especificada ao criar o objeto do cliente.
102
AWS SDK para .NET Guia do desenvolvedorExemplos de instâncias do Amazon EC2
string amiID = "ami-e189c8d1";string keyPairName = "my-sample-key";
var launchRequest = new RunInstancesRequest(){ ImageId = amiID, InstanceType = InstanceType.T1Micro, MinCount = 1, MaxCount = 1, KeyName = keyPairName, NetworkInterfaces = enis};
ImageId
O ID da AMI. Para uma lista de AMIs públicas fornecidas pela Amazon, consulte Amazon MachineImages (Imagens de máquina da Amazon).
InstanceType
Um tipo de instância compatível com a AMI especificada. Para obter mais informações, consulteTipos de instância no Guia do usuário do Amazon EC2 para instâncias do Windows.
MinCount
O número mínimo de instâncias do EC2 a serem executadas. Se isso for mais instâncias do que oAmazon EC2 pode executar na zona de disponibilidade de destino, o Amazon EC2 não executaránenhuma instância.
MaxCount
O número máximo de instâncias do EC2 a serem executadas. Se isso for mais instâncias do queo Amazon EC2 pode executar na zona de disponibilidade de destino, o Amazon EC2 executará omaior número possível de instâncias acima de MinCount. É possível executar entre 1 e o númeromáximo de instâncias às quais você tem permissão para o tipo de instância. Para obter maisinformações, consulte How many instances can I run in Amazon EC2 (Quantas instâncias possoexecutar no Amazon EC2) nas perguntas frequentes gerais do Amazon EC2.
KeyName
O nome do par de chaves do EC2. Se você iniciar uma instância sem especificar um par dechaves, não poderá se conectar a ela. Para mais informações, consulte Trabalho com pares dechave do Amazon EC2 (p. 98).
NetworkInterfaces
Uma ou mais interfaces de rede.3. (Opcional) Para executar a instância com uma função do IAM (p. 138), especifique um perfil de
instância do IAM no objeto RunInstancesRequest.
Um usuário do IAM não pode executar uma instância com a função do IAM sem permissõesconcedidas pela política a seguir.
{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": [ "iam:PassRole", "iam:ListInstanceProfiles", "ec2:*" ],
103
AWS SDK para .NET Guia do desenvolvedorExemplos de instâncias do Amazon EC2
"Resource": "*" }]}
Por exemplo, o snippet a seguir instancia e configura um objeto IamInstanceProfileSpecification parauma função do IAM denominado winapp-instance-role-1.
var instanceProfile = new IamInstanceProfileSpecification();instanceProfile.Name = "winapp-instance-role-1";
Para especificar esse perfil de instância no objeto RunInstancesRequest, adicione a linha a seguir.
launchRequest.IamInstanceProfile = instanceProfile;
4. Execute as instâncias passando o objeto da solicitação para o método RunInstances. Salve os IDs dasinstâncias, pois você precisará deles para gerenciar as instâncias.
Use o objeto RunInstancesResponse retornado para obter uma lista dos IDs de instância para asnovas instâncias. A propriedade Reservation.Instances contém uma lista de objetos da Instance(Instância), um para cada instância do EC2 que você tiver implementado com êxito. Você poderecuperar o ID para cada instância na propriedade InstanceId do objeto da instância.
RunInstancesResponse launchResponse = ec2Client.RunInstances(launchRequest);
List<String> instanceIds = new List<string>();foreach (Instance instance in launchResponse.Reservation.Instances){ Console.WriteLine(instance.InstanceId); instanceIds.Add(instance.InstanceId);}
Verifique o estado da sua instância
Use o procedimento a seguir para obter o estado atual da sua instância. Inicialmente, sua instância está noestado pending. Você pode se conectar à sua instância depois de ela entrar no estado running.
1. Crie e configure um objeto DescribeInstancesRequest e atribua o ID da sua instância à propriedadeInstanceIds. Você também pode usar a propriedade Filter para limitar a solicitação adeterminadas instâncias, como instâncias com uma tag especificada por um usuário específico.
var instanceRequest = new DescribeInstancesRequest();instanceRequest.InstanceIds = new List<string>();instanceRequest.InstanceIds.Add(instanceId);
2. Chame o método DescribeInstances e passe a ele o objeto da solicitação da etapa 1. O método retornaum objeto DescribeInstancesResponse, que contém informações sobre a instância.
var response = ec2Client.DescribeInstances(instanceRequest);
3. A propriedade DescribeInstancesResponse.Reservations contém uma lista de reservas. Nessecaso, há somente uma reserva. Cada reserva contém uma lista de objetos Instance. Novamente,neste caso, há somente uma instância. É possível obter o status da instância com a propriedade State.
Console.WriteLine(response.Reservations[0].Instances[0].State.Name);
104
AWS SDK para .NET Guia do desenvolvedorExemplos de instâncias do Amazon EC2
Conectar-se à sua instância em execução
Depois que uma instância estiver sendo executada, você pode conectar-se remotamente usando o clienteremoto apropriado.
Para instâncias Linux, use um cliente SSH. É necessário garantir que a porta SSH da instância (22) tenhasido aberta para o tráfego. Você precisará do endereço IP público da instância ou do nome DNS público eda parte privada do par de chaves usado para executar a instância. Para obter mais informações, consulteConectar-se à sua instância do Linux no Guia do usuário do Amazon EC2 para instâncias do Linux.
Para instâncias Windows, use um cliente RDP. É necessário garantir que a porta RDP da instância (3389)tenha sido aberta para o tráfego. Você terá o endereço IP público da instância ou o nome DNS públicoe a senha do administrador. A senha de administrador é obtida com os métodos GetPasswordData eGetPasswordDataResult.GetDecryptedPassword, que exigem a parte privada do par de chaves usadopara executar a instância. Para obter mais informações, consulte Conectar-se à sua instância do Windowsusando RDP no Guia do usuário do Amazon EC2 para instâncias do Windows. O exemplo a seguirdemonstra como obter a senha para uma instância do Windows.
public static string GetWindowsPassword( AmazonEC2Client ec2Client, string instanceId, FileInfo privateKeyFile){ string password = "";
var request = new GetPasswordDataRequest(); request.InstanceId = instanceId;
var response = ec2Client.GetPasswordData(request); if (null != response.PasswordData) { using (StreamReader sr = new StreamReader(privateKeyFile.FullName)) { string privateKeyData = sr.ReadToEnd(); password = response.GetDecryptedPassword(privateKeyData); } } else { Console.WriteLine("The password is not available. The password for " + "instance {0} is either not ready, or it is not a Windows instance.", instanceId); }
return password;}
Quando você não precisar mais da sua instância do EC2, consulte Encerramento de uma instância doAmazon EC2 (p. 105).
Encerramento de uma instância do Amazon EC2Quando uma ou mais instâncias do Amazon EC2 não forem mais necessárias, é possível encerrá-las.
Para obter informações sobre como criar um cliente do Amazon EC2, consulte Criar um cliente do AmazonEC2 (p. 94).
Como encerrar uma instância do EC2
1. Crie e inicialize um objeto TerminateInstancesRequest.
105
AWS SDK para .NET Guia do desenvolvedorExemplos de instâncias do Amazon EC2
2. Defina a propriedade TerminateInstancesRequest.InstanceIds para uma lista de um ou maisIDs de instâncias para as instâncias que deseja encerrar.
3. Transmita o objeto de solicitação ao método TerminateInstances. Se a instância especificada nãoexistir, será lançada uma AmazonEC2Exception.
4. Use o objeto TerminateInstancesResponse para listar as instâncias encerradas, conforme mostrado aseguir.
public static void TerminateInstance( AmazonEC2Client ec2Client, string instanceId){ var request = new TerminateInstancesRequest(); request.InstanceIds = new List<string>() { instanceId };
try { var response = ec2Client.TerminateInstances(request); foreach (InstanceStateChange item in response.TerminatingInstances) { Console.WriteLine("Terminated instance: " + item.InstanceId); Console.WriteLine("Instance state: " + item.CurrentState.Name); } } catch(AmazonEC2Exception ex) { // Check the ErrorCode to see if the instance does not exist. if ("InvalidInstanceID.NotFound" == ex.ErrorCode) { Console.WriteLine("Instance {0} does not exist.", instanceId); } else { // The exception was thrown for another reason, so re-throw the exception. throw; } }}
Uso de regiões e zonas de disponibilidade com Amazon EC2Este exemplo de .NET mostra como:
• Obter detalhes sobre as Zonas de disponibilidade• Obter detalhes sobre as regiões
O cenário
O Amazon EC2 está hospedado em vários locais no mundo todo. Esses locais são compostos por regiõese zonas de disponibilidade. Cada região é uma área geográfica separada possui vários locais isoladosconhecidos como Zonas de disponibilidade. O Amazon EC2 oferece a possibilidade de colocar instâncias edados em vários locais.
Use o AWS SDK para .NET para recuperar os detalhes sobre as regiões e as zonas de disponibilidadeusando os seguintes métodos da classe AmazonEC2Client:
• DescribeAvailabilityZones• DescribeRegions
106
AWS SDK para .NET Guia do desenvolvedorExemplos de instâncias do Amazon EC2
Para obter mais informações sobre regiões e zonas de disponibilidade, consulte Regiões e zonas dedisponibilidade no Guia do usuário do Amazon EC2 para instâncias do Windows.
Descrever as zonas de disponibilidadeCrie uma instância do AmazonEC2Client e chame o método DescribeAvailabilityZones. O objetoDescribeAvailabilityZonesResponse retornado contém uma lista das Zonas de disponibilidade.
public static void DescribeAvailabilityZones(){ Console.WriteLine("Describe Availability Zones"); AmazonEC2Client client = new AmazonEC2Client(); DescribeAvailabilityZonesResponse response = client.DescribeAvailabilityZones(); var availZones = new List<AvailabilityZone>(); availZones = response.AvailabilityZones; foreach (AvailabilityZone az in availZones) { Console.WriteLine(az.ZoneName); }}
Descrever as regiõesCrie uma instância do AmazonEC2Client e chame o método DescribeRegions. O objetoDescribeRegionsResponse retornado contém uma lista das regiões.
public static void DescribeRegions(){ Console.WriteLine("Describe Regions"); AmazonEC2Client client = new AmazonEC2Client(); DescribeRegionsResponse response = client.DescribeRegions(); var regions = new List<Region>(); regions = response.Regions; foreach (Region region in regions) { Console.WriteLine(region.RegionName); }}
Uso de VPC endpoints com Amazon EC2Este exemplo .NET mostra como criar, descrever, modificar e excluir VPC endpoints.
O cenárioUm endpoint permite criar uma conexão privada entre a VPC e outro serviço da AWS em sua conta.Especifique uma política para anexar ao endpoint que controlará o acesso ao serviço a partir da VPC.Também é possível especificar as tabelas de rotas da VPC que utilizam o endpoint.
Este exemplo usa os seguintes métodos do AmazonEC2Client:
• CreateVpcEndpoint• DescribeVpcEndpoints• ModifyVpcEndpoint• DeleteVpcEndpoints
Criar um VPC endpointO exemplo a seguir cria um VPC endpoint para um Amazon Simple Storage Service (S3).
107
AWS SDK para .NET Guia do desenvolvedorExemplos de instâncias do Amazon EC2
Crie uma instância do AmazonEC2Client. Você criará uma VPC para que seja possível criar um VPCendpoint.
Crie um objeto CreateVpcRequest especificando um bloco CIDR IPv4 como parâmetro do construtor.Usando este objeto CreateVpcRequest, use o método CreateVpc para criar uma VPC. Utilize estaVPC para instanciar um objeto CreateVpcEndpointRequest, especificando o nome do serviço para oendpoint. Em seguida, use este objeto de solicitação para chamar o método CreateVpcEndpoint e criar oVpcEndpoint.
public static void CreateVPCEndpoint(){ AmazonEC2Client client = new AmazonEC2Client(); CreateVpcRequest vpcRequest = new CreateVpcRequest("10.32.0.0/16"); CreateVpcResponse vpcResponse = client.CreateVpc(vpcRequest); Vpc vpc = vpcResponse.Vpc; CreateVpcEndpointRequest endpointRequest = new CreateVpcEndpointRequest(); endpointRequest.VpcId = vpc.VpcId; endpointRequest.ServiceName = "com.amazonaws.us-west-2.s3"; CreateVpcEndpointResponse cVpcErsp = client.CreateVpcEndpoint(endpointRequest); VpcEndpoint vpcEndPoint = cVpcErsp.VpcEndpoint;}
Descrever um VPC endpointCrie uma instância do AmazonEC2Client. Em seguida, crie um objeto DescribeVpcEndpointsRequest elimite o número máximo de resultados retornados a 5. Use este objeto DescribeVpcEndpointsRequestpara chamar o método DescribeVpcEndpoints. A DescribeVpcEndpointsResponse retornada contém a listados VPC endpoints.
public static void DescribeVPCEndPoints(){ AmazonEC2Client client = new AmazonEC2Client(); DescribeVpcEndpointsRequest endpointRequest = new DescribeVpcEndpointsRequest(); endpointRequest.MaxResults = 5; DescribeVpcEndpointsResponse endpointResponse = client.DescribeVpcEndpoints(endpointRequest); List<VpcEndpoint> endpointList = endpointResponse.VpcEndpoints; foreach (VpcEndpoint vpc in endpointList) { Console.WriteLine("VpcEndpoint ID = " + vpc.VpcEndpointId); List<string> routeTableIds = vpc.RouteTableIds; foreach (string id in routeTableIds) { Console.WriteLine("\tRoute Table ID = " + id); }
}}
Modificar um VPC endpointO exemplo a seguir modifica os atributos de um VPC endpoint especificado. É possível modificar a políticaassociada ao endpoint e adicionar ou remover tabelas de rotas associadas ao endpoint.
Crie uma instância do AmazonEC2Client. Crie um objeto ModifyVpcEndpointRequest usando o ID do VPCendpoint e o ID da tabela de rotas a ser adicionado. Chame o método ModifyVpcEndpoint usando o objetoModifyVpcEndpointRequest. O objeto ModifyVpcEndpointResponse retornado contém um código destatus HTTP que indica se a solicitação de modificação foi realizada com sucesso.
public static void ModifyVPCEndPoint()
108
AWS SDK para .NET Guia do desenvolvedorExemplos de instâncias do Amazon EC2
{ AmazonEC2Client client = new AmazonEC2Client(); ModifyVpcEndpointRequest modifyRequest = new ModifyVpcEndpointRequest(); modifyRequest.VpcEndpointId = "vpce-17b05a7e"; modifyRequest.AddRouteTableIds = new List<string> { "rtb-c46f15a3" }; ModifyVpcEndpointResponse modifyResponse = client.ModifyVpcEndpoint(modifyRequest); HttpStatusCode status = modifyResponse.HttpStatusCode; if (status.ToString() == "OK") Console.WriteLine("ModifyHostsRequest succeeded"); else Console.WriteLine("ModifyHostsRequest failed");
Excluir um VPC endpointÉ possível excluir um ou mais VPC endpoints especificados. Excluir o endpoint também exclui as rotas doendpoint na tabelas de rotas associadas ao endpoint.
Crie uma instância do AmazonEC2Client. Use o método DescribeVpcEndpoints para listar os VPCendpoints associados ao cliente do EC2. Utilize a lista de VPC endpoints para criar uma lista dos IDs deVPC endpoint. Use esta lista para criar um objeto DeleteVpcEndpointsRequest a ser usado pelo métodoDeleteVpcEndpoints.
private static void DeleteVPCEndPoint(){ AmazonEC2Client client = new AmazonEC2Client(); DescribeVpcEndpointsRequest endpointRequest = new DescribeVpcEndpointsRequest(); endpointRequest.MaxResults = 5; DescribeVpcEndpointsResponse endpointResponse = client.DescribeVpcEndpoints(endpointRequest); List<VpcEndpoint> endpointList = endpointResponse.VpcEndpoints; var vpcEndPointListIds = new List<string>(); foreach (VpcEndpoint vpc in endpointList) { Console.WriteLine("VpcEndpoint ID = " + vpc.VpcEndpointId); vpcEndPointListIds.Add(vpc.VpcEndpointId); } DeleteVpcEndpointsRequest deleteRequest = new DeleteVpcEndpointsRequest(); deleteRequest.VpcEndpointIds = vpcEndPointListIds; client.DeleteVpcEndpoints(deleteRequest);}
Como usar endereços IP elásticos no Amazon EC2Este exemplo de .NET mostra como:
• Recuperar descrições dos seus endereços IP elásticos• Alocar e associar um endereço IP elástico a uma instância do Amazon EC2• Liberar um endereço IP elástico
O cenárioUm endereço IP elástico é um endereço IP estático projetado para computação em nuvem dinâmica. Umendereço IP elástico é associado à sua conta da AWS e é um endereço IP público acessível pela Internet.
Se a sua instância do Amazon EC2 não tiver um endereço IP público, você poderá associar um endereçoIP elástico à sua instância para permitir a comunicação com a Internet.
Neste exemplo, o AWS SDK para .NET é usado para gerenciar endereços IP elásticos com esses métodosda classe de cliente do Amazon EC2:
109
AWS SDK para .NET Guia do desenvolvedorExemplos de instâncias do Amazon EC2
• DescribeAddresses• AllocateAddress• AssociateAddress• ReleaseAddress
Para obter informações sobre endereços IP elásticos no Amazon EC2, consulte Endereços IP elásticos noGuia do usuário do Amazon EC2 para instâncias do Windows.
Descrever endereços IP elásticosCrie um objeto AmazonEC2Client. Em seguida, crie um objeto DescribeAddressesRequest para passarcomo um parâmetro, filtrando os endereços retornados por aqueles na sua VPC. Para recuperar asdescrições de todos os endereços IP elásticos, omita o filtro dos parâmetros. Em seguida, chame o métodoDescribeAddresses do objeto AmazonEC2Client.
public void DescribeElasticIps(){ using (var client = new AmazonEC2Client(RegionEndpoint.USWest2)) { var addresses = client.DescribeAddresses(new DescribeAddressesRequest { Filters = new List<Filter> { new Filter { Name = "domain", Values = new List<string> { "vpc" } } } }).Addresses;
foreach(var address in addresses) { Console.WriteLine(address.PublicIp); Console.WriteLine("\tAllocation Id: " + address.AllocationId); Console.WriteLine("\tPrivate IP Address: " + address.PrivateIpAddress); Console.WriteLine("\tAssociation Id: " + address.AssociationId); Console.WriteLine("\tInstance Id: " + address.InstanceId); Console.WriteLine("\tNetwork Interface Owner Id: " + address.NetworkInterfaceOwnerId); } }}
Alocar e associar um endereço IP elásticoCrie um objeto AmazonEC2Client. Em seguida, crie um objeto AllocateAddressRequest para o parâmetrousado a fim de alocar um endereço IP elástico, que neste caso especifica que o domínio é um VPC.Chame o método AllocateAddress do objeto AmazonEC2Client.
Após a sucesso, o objeto retornado AllocateAddressResponse tem uma propriedade AllocationId queidentifica o endereço IP elástico alocado.
Crie um objeto AssociateAddressRequest para os parâmetros usados para associar um endereço IPelástico a uma instância do Amazon EC2. Inclua o AllocationId do endereço recém-alocado e oInstanceId da instância do Amazon EC2. Em seguida, chame o método AssociateAddress do objetoAmazonEC2Client.
public void AllocateAndAssociate(string instanceId){
110
AWS SDK para .NET Guia do desenvolvedorExemplos de instância spot do Amazon EC2
using (var client = new AmazonEC2Client(RegionEndpoint.USWest2)) { var allocationId = client.AllocateAddress(new AllocateAddressRequest { Domain = DomainType.Vpc }).AllocationId;
Console.WriteLine("Allocation Id: " + allocationId);
var associationId = client.AssociateAddress(new AssociateAddressRequest { AllocationId = allocationId, InstanceId = instanceId }).AssociationId;
Console.WriteLine("Association Id: " + associationId); }}
Liberar um endereço IP elásticoCrie um objeto AmazonEC2Client. Em seguida, crie um objeto ReleaseAddressRequest para osparâmetros usados para liberar um endereço IP elástico, que neste caso especifica o AllocationIdpara o endereço IP elástico. Liberar um endereço IP elástico também o dissocia de qualquer instância doAmazon EC2. Chame o método ReleaseAddress do objeto de serviço do Amazon EC2.
public void Release(string allocationId){ using (var client = new AmazonEC2Client(RegionEndpoint.USWest2)) { client.ReleaseAddress(new ReleaseAddressRequest { AllocationId = allocationId }); }}
Exemplos de instância spot do Amazon EC2Este tópico descreve como usar AWS SDK para .NET para criar, cancelar e encerrar uma instância spot doAmazon EC2.
Tópicos• Visão geral (p. 111)• Pré-requisitos (p. 112)• Definição das suas credenciais (p. 112)• Enviar sua solicitação spot (p. 112)• Determinação do estado da sua solicitação spot (p. 115)• Limpeza das suas solicitações spot e instâncias (p. 115)• Reunião de todos os componentes (p. 117)
Visão geralAs instâncias spot permitem que você solicite a capacidade não utilizada do Amazon EC2 e executetodas as instâncias adquiridas pelo tempo que sua solicitação exceder o preço spot atual. O Amazon EC2altera o preço spot periodicamente com base na oferta e na demanda, mas nunca excederá 90% do preçoda instância sob demanda. Os clientes com solicitações que atendam ou excedam esse preço ganham
111
AWS SDK para .NET Guia do desenvolvedorExemplos de instância spot do Amazon EC2
acesso às instâncias spot disponíveis. Assim como instâncias sob demanda e instâncias reservadas, asinstâncias spot são outra opção para obter mais capacidade computacional.
As instâncias spot podem reduzir significativamente os custos do Amazon EC2 para aplicativos, comoprocessamento em lote, pesquisa científica, processamento de imagens, codificação de vídeos, crawlingde dados e web, análise financeira e testes. Além disso, as instâncias spot são uma opção excelentequando você precisa de grandes quantidades de capacidade computacional, mas a necessidade dessacapacidade não é urgente.
Para obter mais informações sobre instâncias spot, consulte https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-spot-instances.html no Guia do usuário do Amazon EC2 para instâncias do Linux.
Para usar instâncias spot, faça uma solicitação de instância spot especificando o preço máximo que vocêestá disposto a pagar por hora de instância; essa é a sua solicitação. Se sua solicitação exceder o preçospot atual, ela será atendida e as instâncias serão executadas até que você opte por encerrá-las ou atéque o preço spot exceda sua solicitação (o que ocorrer primeiro). É possível encerrar uma instância spotde maneira programática, conforme mostrado neste tutorial, usando o Console de Gerenciamento da AWSou o AWS Toolkit for Visual Studio.
Também é possível especificar o valor que você está disposto a pagar pelas instâncias spot como umaporcentagem do preço da instância sob demanda. Se o preço especificado for excedido, a instância spotserá encerrada.
As instâncias spot funcionam exatamente como outras instâncias do Amazon EC2 durante a execução e,como outras instâncias do Amazon EC2, as instâncias spot poderão ser encerradas quando não foremmais necessárias.
O preço spot cobrado é o preço que está em vigor durante o período da execução das instâncias. Ospreços de instância spot são definidos pelo Amazon EC2 e são ajustados gradualmente de acordo comtendências de longo prazo da oferta e da demanda pela capacidade de instâncias spot. Também épossível especificar o valor que está disposto a pagar por uma instância spot como uma porcentagem dopreço da instância sob demanda.
Este tutorial dá uma visão geral de como usar o ambiente de programação .NET para fazer o seguinte.
• Enviar uma solicitação spot• Determinar quando a solicitação spot é atendida• Cancelar a solicitação spot• Encerrar as instâncias associadas
Pré-requisitosEste tutorial pressupõe que você se cadastrou na AWS, configurou seu ambiente dedesenvolvimento .NET e instalou o AWS SDK para .NET. Se você usar o ambiente de desenvolvimento doMicrosoft Visual Studio, recomendamos também instalar o AWS Toolkit for Visual Studio. Para instruçõessobre como configurar seu ambiente, consulte Conceitos básicos do AWS SDK para .NET (p. 14).
Definição das suas credenciaisPara obter informações sobre como usar suas credenciais da AWS com o SDK, consulte Configuração dascredenciais da AWS (p. 23).
Enviar sua solicitação spotPara enviar uma solicitação spot, é preciso primeiro determinar o tipo de instância, a imagem de máquinada Amazon (AMI) e a solicitação máxima que você deseja oferecer. Você também deve incluir um grupo desegurança, de modo que possa se cadastrar na instância, se desejar. Para obter mais informações sobrecomo criar security groups, consulte Criar um security group no Amazon EC2 (p. 94).
112
AWS SDK para .NET Guia do desenvolvedorExemplos de instância spot do Amazon EC2
Há vários tipos de instância a escolher; acesse Amazon EC2 Instance Types (Tipos de instância doAmazon EC2) para ver a lista completa. Para este tutorial, usaremos t1.micro. Você também precisado ID da AMI atual do Windows. Para obter mais informações, consulte Encontrar uma AMI no Guia dousuário do Amazon EC2 para instâncias do Windows.
Há muitas maneiras de abordar a solicitação de instâncias spot. Para começar, descreveremos trêsestratégias comuns:
• Solicitação para garantir que o custo seja menor do que a definição de preço sob demanda.• Solicitação com base no valor da computação resultante.• Solicitação para adquirir capacidade de computação o mais rápido possível.
Reduzir o custo abaixo de sob demanda
Você tem um job de processamento em lote que modera determinado número de horas ou dias paraser executado. Contudo, você tem flexibilidade em relação ao início e ao fim. Você quer ver se pode oconcluído por um custo inferior ao das instâncias sob demanda. Você examina o histórico de preçosspot para tipos de instância usando o Console de gerenciamento da AWS ou a API do Amazon EC2.Para obter mais informações, acesse Exibir histórico de preços spot. Depois de analisar o histórico depreços do tipo de instância desejado em determinada zona de disponibilidade, há duas abordagensalternativas para sua solicitação:• Especificar uma solicitação na extremidade superior do intervalo de preços spot, que ainda estão
abaixo do preço sob demanda, prevendo que sua solicitação spot única provavelmente seriacumprida e executada pelo tempo de computação consecutivo suficiente para concluir o trabalho.
• Especificar uma solicitação na extremidade inferior do intervalo de preço e planejar a combinaçãode várias instâncias executadas ao longo do tempo por meio de uma requisição persistente. Asinstâncias seriam executadas por tempo suficiente, ao todo, para concluir o trabalho com um custototal ainda inferior. (Explicaremos como automatizar essa tarefa ainda neste tutorial.)
Não pague mais que o valor do resultado
Você tem um job de processamento de dados para ser executado. Você entende o valordos resultados do trabalho bem o suficiente para saber o quanto valem em termos de custoscomputacionais. Após analisar o histórico de preços spot para seu tipo de instância, você escolhe umasolicitação na qual o custo do tempo computacional não é mais que o valor dos resultados do trabalho.Você cria uma requisição persistente e a deixa ser executada de forma intermitente, à medida que opreço spot flutua acima ou abaixo da sua solicitação.
Adquirir capacidade computacional rapidamente
Você tem a necessidade imprevista e de curto prazo por capacidade adicional indisponível pelasinstâncias sob demanda. Depois de analisar o histórico de preços spot para seu tipo de instância, vocêfaz uma solicitação acima do preço histórico mais alto para melhorar muito a probabilidade de suasolicitação ser atendida com rapidez e continuar a computação até a conclusão.
Depois de executar a análise, você estará pronto para solicitar uma instância spot. Para este tutorial, opreço máximo da instância spot padrão está definido para ser o mesmo que o preço da instância sobdemanda (que é 0,003 USD para este tutorial). Definir o preço desta forma maximiza as chances de que opedido seja atendido. Você pode determinar os tipos de instâncias disponíveis e os preços sob demandapara instâncias indo à Amazon EC2 Pricing page (página de definição de preços do Amazon EC2).
Primeiro, especifique os namespaces .NET usados no aplicativo.
using System;using System.Collections.Generic;using System.Threading;using Amazon;
113
AWS SDK para .NET Guia do desenvolvedorExemplos de instância spot do Amazon EC2
using Amazon.EC2;using Amazon.EC2.Model;
Para obter informações sobre como criar um cliente do Amazon EC2, consulte Criar um cliente do AmazonEC2 (p. 94).
Depois, para solicitar uma instância spot, é necessário criar a solicitação com os parâmetros queespecificamos até agora. Comece criando um objeto RequestSpotInstanceRequest. O objeto de solicitaçãoexige o valor da solicitação e o número de instâncias que você deseja iniciar. Além disso, é necessáriodefinir a LaunchSpecification para a solicitação, incluindo o tipo de instância, o ID da AMI e o nome dosgrupos de segurança que deseja usar para instâncias spot. Depois de a solicitação ser preenchida, chameo método RequestSpotInstances para criar a solicitação de instância spot. O exemplo a seguir demonstracomo solicitar uma instância spot.
/* Creates a spot instance * * Takes six args: * AmazonEC2Client ec2Client is the EC2 client through which the spot instance request is made * string amiId is the AMI of the instance to request * string securityGroupName is the name of the security group of the instance to request * InstanceType instanceType is the type of the instance to request * string spotPrice is the price of the instance to request * int instanceCount is the number of instances to request * * See https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/MEC2RequestSpotInstancesRequestSpotInstancesRequest.html */ private static SpotInstanceRequest RequestSpotInstance( AmazonEC2Client ec2Client, string amiId, string securityGroupName, InstanceType instanceType, string spotPrice, int instanceCount) { RequestSpotInstancesRequest request = new RequestSpotInstancesRequest { SpotPrice = spotPrice, InstanceCount = instanceCount };
LaunchSpecification launchSpecification = new LaunchSpecification { ImageId = amiId, InstanceType = instanceType };
launchSpecification.SecurityGroups.Add(securityGroupName);
request.LaunchSpecification = launchSpecification;
var result = ec2Client.RequestSpotInstancesAsync(request);
return result.Result.SpotInstanceRequests[0]; }
O ID da solicitação spot está contido no membro SpotInstanceRequestId do objetoSpotInstanceRequest.
Executar esse código iniciará uma nova solicitação de instância spot.
114
AWS SDK para .NET Guia do desenvolvedorExemplos de instância spot do Amazon EC2
Note
Você será cobrado por todas as instâncias spot que forem iniciadas, por isso cancele assolicitações e encerre todas as instâncias que iniciar para reduzir os encargos associados.
Há outras opções que você pode usar para configurar suas solicitações spot. Para saber mais, consulteRequestSpotInstances no AWS SDK para .NET.
Determinação do estado da sua solicitação spotEm seguida, precisamos esperar até que a solicitação spot alcance o estado Active antes decontinuar para a última etapa. Para determinar o estado de sua solicitação spot, usamos o métodoDescribeSpotInstanceRequests para obter o estado do ID da solicitação spot que queremos monitorar.
/* Gets the state of a spot instance request. * Takes two args: * AmazonEC2Client ec2Client is the EC2 client through which information about the state of the spot instance is made * string spotRequestId is the ID of the spot instance * * See https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/MEC2DescribeSpotInstanceRequests.html */ private static SpotInstanceState GetSpotRequestState( AmazonEC2Client ec2Client, string spotRequestId) { // Create the describeRequest object with all of the request ids // to monitor (e.g. that we started). var request = new DescribeSpotInstanceRequestsRequest(); request.SpotInstanceRequestIds.Add(spotRequestId);
// Retrieve the request we want to monitor. var describeResponse = ec2Client.DescribeSpotInstanceRequestsAsync(request);
SpotInstanceRequest req = describeResponse.Result.SpotInstanceRequests[0];
return req.State; }
Limpeza das suas solicitações spot e instânciasA etapa final é limpar suas solicitações e instâncias. É importante cancelar todas as solicitações pendentese encerrar as instâncias. Simplesmente cancelar as solicitações não encerrará as instâncias, o quesignifica que você continuará a ser cobrado por elas. Se você encerrar suas instâncias suas solicitaçõesspot poderão ser canceladas, mas há algumas situações, por exemplo, se você usar solicitaçõespersistentes, nas quais encerrar suas instâncias não basta para impedir que a solicitação seja atendidanovamente. Portanto, é uma prática recomendada cancelar todas as solicitações ativas e encerrar asinstâncias em execução.
Para cancelar uma solicitação spot, você usa o método CancelSpotInstanceRequests. O exemplo a seguirdemonstra como cancelar uma solicitação spot.
/* Cancels a spot instance request * Takes two args: * AmazonEC2Client ec2Client is the EC2 client through which the spot instance is cancelled * string spotRequestId is the ID of the spot instance * * See https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/MEC2CancelSpotInstanceRequestsCancelSpotInstanceRequestsRequest.html
115
AWS SDK para .NET Guia do desenvolvedorExemplos de instância spot do Amazon EC2
*/ private static void CancelSpotRequest( AmazonEC2Client ec2Client, string spotRequestId) { var cancelRequest = new CancelSpotInstanceRequestsRequest();
cancelRequest.SpotInstanceRequestIds.Add(spotRequestId);
ec2Client.CancelSpotInstanceRequestsAsync(cancelRequest); }
Para encerrar uma instância, você usa o método TerminateInstances. O exemplo a seguir demonstra comoobter o identificador da instância para uma instância spot ativa e encerrar a instância.
/* Terminates a spot instance request * Takes two args: * AmazonEC2Client ec2Client is the EC2 client through which the spot instance is terminated * string spotRequestId is the ID of the spot instance * * See https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/MEC2TerminateInstancesTerminateInstancesRequest.html */ private static void TerminateSpotInstance( AmazonEC2Client ec2Client, string spotRequestId) { var describeRequest = new DescribeSpotInstanceRequestsRequest(); describeRequest.SpotInstanceRequestIds.Add(spotRequestId);
// Retrieve the request we want to monitor. var describeResponse = ec2Client.DescribeSpotInstanceRequestsAsync(describeRequest);
if (SpotInstanceState.Active == describeResponse.Result.SpotInstanceRequests[0].State) { string instanceId = describeResponse.Result.SpotInstanceRequests[0].InstanceId;
var terminateRequest = new TerminateInstancesRequest(); terminateRequest.InstanceIds = new List<string>() { instanceId };
try { ec2Client.TerminateInstancesAsync(terminateRequest); } catch (AmazonEC2Exception ex) { // Check the ErrorCode to see if the instance does not exist. if ("InvalidInstanceID.NotFound" == ex.ErrorCode) { Console.WriteLine("Instance {0} does not exist.", instanceId); } else { // The exception was thrown for another reason, so re-throw the exception. throw; } } } }
116
AWS SDK para .NET Guia do desenvolvedorExemplos de instância spot do Amazon EC2
Para obter mais informações sobre como encerrar instâncias ativas, consulte Encerramento de umainstância do Amazon EC2 (p. 105).
Reunião de todos os componentesA rotina principal a seguir chama esses métodos na ordem mostrada para criar, cancelar e encerrar umasolicitação de instância spot. Como o comentário afirma, é necessário um argumento, a AMI.
/* Creates, cancels, and terminates a spot instance request * * AmazonEC2Client ec2Client is the EC2 client through which the spot instance is manipulated * string spotRequestId is the ID of the spot instance * * See https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/MEC2TerminateInstancesTerminateInstancesRequest.html */
// Displays information about the command-line args private static void Usage() { Console.WriteLine(""); Console.WriteLine("Usage:"); Console.WriteLine(""); Console.WriteLine("Ec2SpotCrud.exe AMI [-s SECURITY_GROUP] [-p SPOT_PRICE] [-c INSTANCE_COUNT] [-h]"); Console.WriteLine(" where:"); Console.WriteLine(" AMI is the AMI to use. No default value. Cannot be an empty string."); Console.WriteLine(" SECURITY_GROUP is the name of a security group. Default is default. Cannot be an empty string."); Console.WriteLine(" SPOT_PRICE is the spot price. Default is 0.003. Must be > 0.001."); Console.WriteLine(" INSTANCE_COUNT is the number of instances. Default is 1. Must be > 0."); Console.WriteLine(" -h displays this message and quits"); Console.WriteLine(); } /* Creates, cancels, and terminates a spot instance request * See Usage() for information about the command-line args */ static void Main(string[] args) { // Values that aren't easy to pass on the command line RegionEndpoint region = RegionEndpoint.USWest2; InstanceType instanceType = InstanceType.T1Micro; // Default values for optional command-line args string securityGroupName = "default"; string spotPrice = "0.003"; int instanceCount = 1;
// Placeholder for the only required command-line arg string amiId = "";
// Parse command-line args int i = 0; while (i < args.Length) { switch (args[i]) { case "-s": i++;
117
AWS SDK para .NET Guia do desenvolvedorExemplos de instância spot do Amazon EC2
securityGroupName = args[i]; if (securityGroupName == "") { Console.WriteLine("The security group name cannot be blank"); Usage(); return; } break; case "-p": i++; spotPrice = args[i]; double price; double.TryParse(spotPrice, out price); if (price < 0.001) { Console.WriteLine("The spot price must be > 0.001"); Usage(); return; } break; case "-c": i++; int.TryParse(args[i], out instanceCount); if (instanceCount < 1) { Console.WriteLine("The instance count must be > 0"); Usage(); return; } break; case "-h": Usage(); return; default: amiId = args[i]; break; }
i++; }
// Make sure we have an AMI if (amiId == "") { Console.WriteLine("You must supply an AMI"); Usage(); return; }
AmazonEC2Client ec2Client = new AmazonEC2Client(region: region);
Console.WriteLine("Creating spot instance request");
SpotInstanceRequest req = RequestSpotInstance(ec2Client, amiId, securityGroupName, instanceType, spotPrice, instanceCount);
string id = req.SpotInstanceRequestId;
// Wait for it to become active Console.WriteLine("Waiting for spot instance request with ID " + id + " to become active");
int wait = 1; int totalTime = 0;
while (true)
118
AWS SDK para .NET Guia do desenvolvedorArmazenar dados de arquivamento
usando o Amazon S3 Glacier
{ totalTime += wait; Console.Write(".");
SpotInstanceState state = GetSpotRequestState(ec2Client, id);
if (state == SpotInstanceState.Active) { Console.WriteLine(""); break; }
// wait a bit and try again Thread.Sleep(wait);
// wait longer next time // 1, 2, 4, ... wait = wait * 2; }
// Should be around 1000 (one second) Console.WriteLine("That took " + totalTime + " milliseconds");
// Cancel the request Console.WriteLine("Canceling spot instance request");
CancelSpotRequest(ec2Client, id);
// Clean everything up Console.WriteLine("Terminating spot instance request");
TerminateSpotInstance(ec2Client, id);
Console.WriteLine("Done. Press enter to quit");
Console.ReadLine(); }
Consulte o exemplo completo, incluindo informações sobre como compilar e executar o exemplo na linhade comando, no GitHub.
Armazenar dados de arquivamento usando oAmazon S3 Glacier
O AWS SDK para .NET oferece suporte ao Amazon S3 Glacier, que é um serviço de armazenamentopara dados raramente usados, ou dados frios. O serviço oferece armazenamento durável e de custoextremamente baixo com recursos de segurança para arquivamento de dados e backup. Para obter maisinformações, consulte o Guia do desenvolvedor do Amazon S3 Glacier.
As informações a seguir introduzem os modelos de programação do S3 Glacier no AWS SDK para .NET.
Modelos de programaçãoO AWS SDK para .NET oferece dois modelos de programação para trabalhar com o S3 Glacier. Asinformações a seguir descrevem estes modelos, porque e como utilizá-los.
Tópicos• APIs de baixo nível (p. 120)
119
AWS SDK para .NET Guia do desenvolvedorModelos de programação
• APIs de alto nível (p. 122)
APIs de baixo nívelO AWS SDK para .NET oferece APIs de baixo nível para a programação com o S3 Glacier. Estas APIs debaixo nível são mapeadas de maneira próxima para a API REST subjacente compatível com o S3 Glacier.Para cada operação REST do S3 Glacier, as APIs de baixo nível oferecem um método correspondente,um objeto de solicitação para fornecer informações da solicitação e um objeto de resposta para processara resposta do S3 Glacier. As APIs de baixo nível são a implementação mais completa das operaçõessubjacentes do S3 Glacier.
O exemplo a seguir mostra como usar as APIs de baixo nível para listar os cofres acessíveis no S3Glacier.
// using Amazon.Glacier;// using Amazon.Glacier.Model;
var client = new AmazonGlacierClient();var request = new ListVaultsRequest();var response = client.ListVaults(request);
foreach (var vault in response.VaultList){ Console.WriteLine("Vault: {0}", vault.VaultName); Console.WriteLine(" Creation date: {0}", vault.CreationDate); Console.WriteLine(" Size in bytes: {0}", vault.SizeInBytes); Console.WriteLine(" Number of archives: {0}", vault.NumberOfArchives); try { var requestNotifications = new GetVaultNotificationsRequest { VaultName = vault.VaultName }; var responseNotifications = client.GetVaultNotifications(requestNotifications);
Console.WriteLine(" Notifications:"); Console.WriteLine(" Topic: {0}", responseNotifications.VaultNotificationConfig.SNSTopic);
var events = responseNotifications.VaultNotificationConfig.Events;
if (events.Any()) { Console.WriteLine(" Events:");
foreach (var e in events) { Console.WriteLine("{0}", e); } } else { Console.WriteLine(" No events set."); } } catch (ResourceNotFoundException) { Console.WriteLine(" No notifications set."); }
120
AWS SDK para .NET Guia do desenvolvedorModelos de programação
var requestJobs = new ListJobsRequest{ VaultName = vault.VaultName }; var responseJobs = client.ListJobs(requestJobs); var jobs = responseJobs.JobList; if (jobs.Any()) { Console.WriteLine(" Jobs:");
foreach (var job in jobs) { Console.WriteLine(" For job ID: {0}", job.JobId); Console.WriteLine("Archive ID: {0}", job.ArchiveId); Console.WriteLine("Archive size in bytes: {0}", job.ArchiveSizeInBytes.ToString()); Console.WriteLine("Completed: {0}", job.Completed); Console.WriteLine("Completion date: {0}", job.CompletionDate); Console.WriteLine("Creation date: {0}", job.CreationDate); Console.WriteLine("Inventory size in bytes: {0}", job.InventorySizeInBytes); Console.WriteLine("Job description: {0}", job.JobDescription); Console.WriteLine("Status code: {0}", job.StatusCode.Value); Console.WriteLine("Status message: {0}", job.StatusMessage); }
} else { Console.WriteLine(" No jobs."); }
}
Para obter mais exemplos, consulte:
• Using the AWS SDK for .NET• Criação de um cofre• Recuperar metadados do cofre• Fazer download de um inventário de cofre• Configurar notificações de cofre• Exclusão de um cofre• Fazer upload de um arquivo em uma única operação• Upload de arquivos grandes em partes• Download de um arquivo• Exclusão de um arquivo
Para obter informações de referência relacionadas à API, consulte Amazon.Glacier e Amazon.Glacier.
121
AWS SDK para .NET Guia do desenvolvedorComo gerenciar usuários com o AWS IAM
APIs de alto nívelO AWS SDK para .NET oferece APIs de alto nível para a programação com o S3 Glacier. Para simplificarainda mais o desenvolvimento de aplicativos, essas APIs de alto nível oferecem uma abstração de nívelsuperior para algumas operações, incluindo o upload de um arquivo ou o download de um arquivo ouinventário do cofre.
Para obter exemplos, consulte os tópicos a seguir no Guia do desenvolvedor do Amazon S3 Glacier:
• Using the AWS SDK for .NET• Criação de um cofre• Exclusão de um cofre• Fazer upload de um arquivo em um cofre• Upload de um arquivo• Upload de arquivos grandes em partes• Fazer download de um arquivo em um cofre• Download de um arquivo• Excluir um arquivo de um cofre• Exclusão de um arquivo
Para obter informações de referência relacionadas à API, consulte Amazon.Glacier.Transfer em AWS SDKfor .NET API Reference.
Como gerenciar usuários com o AWS Identity andAccess Management (IAM)
O AWS SDK para .NET oferece suporte ao IAM, que é um web service que permite que clientes da AWSgerenciem usuários e suas permissões na AWS.
O código de exemplo é escrito em C#, mas é possível usar o AWS SDK para .NET com qualquerlinguagem compatível. Quando você instala o AWS Toolkit for Visual Studio, é instalada uma série demodelos de projetos C#. Por isso, a forma mais simples para iniciar esse projeto é abrir o Visual Studioe escolher File, New Project, AWS Sample Projects, Deployment and Management, AWS Identity andAccess Management User.
Para informações de referência da API relacionada, consulte Amazon.IdentityManagement eAmazon.IdentityManagement.Model.
Pré-requisitos
Para que você comece, é preciso ter criado uma conta da AWS e configurado suas credenciais da AWS.Para obter mais informações, consulte Configurar o AWS SDK para .NET (p. 14).
Tópicos• Como gerenciar aliases do IAM para o ID da conta da AWS (p. 123)• Gerenciar usuários do IAM (p. 125)• Gerenciar chaves de acesso do IAM (p. 127)• Trabalhar com políticas do IAM (p. 131)
122
AWS SDK para .NET Guia do desenvolvedorComo gerenciar aliases do IAM
• Trabalhar com certificados de servidor do IAM (p. 135)• Listar informações da conta do IAM (p. 137)• Como conceder acesso usando uma função do IAM (p. 138)
Como gerenciar aliases do IAM para o ID da conta daAWSEsses exemplos .NET mostram a você como:
• Crie um alias de conta para seu ID de conta da AWS• Liste um alias de conta para seu ID de conta da AWS• Exclua um alias de conta para seu ID de conta da AWS
O cenárioSe deseja que o URL para sua página de login contenha o nome da sua empresa (ou outro identificadoramigável) em vez do ID da sua conta da AWS, você pode criar um alias para o ID de sua conta da AWS.Se você criar um alias de conta da AWS, a URL da página de login será alterada para incorporar essealias.
Os exemplos a seguir demonstram como gerenciar seu alias da conta da AWS usando esses métodos daclasse AmazonIdentityManagementServiceClient:
• CreateAccountAlias• ListAccountAliases• DeleteAccountAlias
Para obter mais informações sobre alias de contas do IAM, consulte ID da sua conta da AWS e seu aliasno Guia do usuário do IAM.
Crie um alias da contaCrie um objeto AmazonIdentityManagementServiceClient. Em seguida, crie um objetoCreateAccountAliasRequest contendo o novo alias da conta que você deseja usar. Chame o métodoCreateAccountAlias do objeto AmazonIAMClient. Se o alias da conta for criado, exiba o novo alias noconsole. Se o nome já existir, escreva a mensagem de exceção para o console.
public static void CreateAccountAlias(){ try { var iamClient = new AmazonIdentityManagementServiceClient(); var request = new CreateAccountAliasRequest(); request.AccountAlias = "my-aws-account-alias-2017"; var response = iamClient.CreateAccountAlias(request); if (response.HttpStatusCode.ToString() == "OK") Console.WriteLine(request.AccountAlias + " created."); else Console.WriteLine("HttpStatusCode returned = " + response.HttpStatusCode.ToString()); } catch (Exception e) {
123
AWS SDK para .NET Guia do desenvolvedorComo gerenciar aliases do IAM
Console.WriteLine(e.Message); }}
Listar aliases de contasCrie um objeto AmazonIdentityManagementServiceClient. Em seguida, crie um objetoListAccountAliasesRequest. Chame o método ListAccountAliases do objeto AmazonIAMClient. Sehouver um alias de conta, exiba-o no console.
Se não houver alias de conta, grave a mensagem exceção no console.
Note
Só pode haver um alias de conta.
public static void ListAccountAliases(){ try { var iamClient = new AmazonIdentityManagementServiceClient(); var request = new ListAccountAliasesRequest(); var response = iamClient.ListAccountAliases(request); List<string> aliases = response.AccountAliases; foreach (string account in aliases) { Console.WriteLine("The account alias is: " + account); } } catch (Exception e) { Console.WriteLine(e.Message); }}
Exclua um alias de contaCrie um objeto AmazonIdentityManagementServiceClient. Em seguida, crie um objetoDeleteAccountAliasRequest contendo o alias da conta que você deseja excluir. Chame o métodoDeleteAccountAlias do objeto AmazonIAMClient. Se o alias de conta for excluído, exiba as informaçõesde exclusão no console. Se o nome não existir, escreva a mensagem de exceção para o console.
public static void DeleteAccountAlias(){ try { var iamClient = new AmazonIdentityManagementServiceClient(); var request = new DeleteAccountAliasRequest(); request.AccountAlias = "my-aws-account-alias-2017"; var response = iamClient.DeleteAccountAlias(request); if (response.HttpStatusCode.ToString() == "OK") Console.WriteLine(request.AccountAlias + " deleted."); else Console.WriteLine("HttpStatusCode returned = " + response.HttpStatusCode.ToString()); } catch (NoSuchEntityException e) { Console.WriteLine(e.Message); }
124
AWS SDK para .NET Guia do desenvolvedorGerenciar usuários do IAM
}
Gerenciar usuários do IAMEste exemplo .NET mostra como recuperar uma lista de usuários do IAM, criar e excluir usuários do IAM eatualizar um nome de usuário do IAM.
Crie e gerencie usuários no IAM usando estes métodos da classeAmazonIdentityManagementServiceClient:
• CreateUser• ListUsers• UpdateUser• GetUser• DeleteUser
Para obter mais informações sobre os usuários do IAM, consulte Usuários do IAM no Guia do usuário doIAM.
Para obter informações sobre as limitações no número de usuários do IAM que podem ser criados,consulte Limitações nas entidades do IAM no Guia do usuário do IAM.
Criar um usuário para a sua conta da AWSCrie um objeto AmazonIdentityManagementServiceClient. Em seguida, crie um objeto CreateUserRequestque contém o nome do usuário desejado para o novo usuário. Chame o método CreateUser do objetoAmazonIAMClient. Se o nome de usuário não existir atualmente, exiba o nome e o ARN do usuário noconsole. Se o nome já existe, escreva uma mensagem sobre esse efeito para o console.
var client = new AmazonIdentityManagementServiceClient();var request = new CreateUserRequest{ UserName = "DemoUser"};
try{ var response = client.CreateUser(request);
Console.WriteLine("User Name = '{0}', ARN = '{1}'", response.User.UserName, response.User.Arn);}catch (EntityAlreadyExistsException){ Console.WriteLine("User 'DemoUser' already exists.");}
Listar os usuários na sua conta da AWSEste exemplo lista os usuários do IAM que possuem o prefixo do caminho especificado. Se nenhum prefixodo caminho for especificado, a ação retornará todos os usuários na conta da AWS. Se não existiremusuários, a ação retornará uma lista vazia.
Crie um objeto AmazonIdentityManagementServiceClient. Em seguida, crie um objetoListUsersRequest que contém os parâmetros necessários para listar os usuários. Limite o númeroretornado ao definir o parâmetro MaxItems como 10. Chame o método ListUsers do objeto
125
AWS SDK para .NET Guia do desenvolvedorGerenciar usuários do IAM
AmazonIdentityManagementServiceClient. Grave cada nome de usuário e a data de criação noconsole.
public static void ListUsers(){ var iamClient = new AmazonIdentityManagementServiceClient(); var requestUsers = new ListUsersRequest() { MaxItems = 10 }; var responseUsers = iamClient.ListUsers(requestUsers);
foreach (var user in responseUsers.Users) { Console.WriteLine("User " + user.UserName + " Created: " + user.CreateDate.ToShortDateString()); }
}
Atualizar um nome de usuárioEste exemplo mostra como atualizar o nome ou o caminho do usuário do IAM especificado. Certifique-sede compreender as implicações da alteração do caminho ou do nome de um usuário do IAM. Para obtermais informações, consulte Renomear um usuário do IAM no Guia do usuário do IAM.
Crie um objeto AmazonIdentityManagementServiceClient. Em seguida, crie um objeto UpdateUserRequestespecificando os nomes de usuário novo e atual como parâmetros. Chame o método UpdateUser doobjeto AmazonIdentityManagementServiceClient.
public static void UpdateUser(){ var client = new AmazonIdentityManagementServiceClient(); var request = new UpdateUserRequest { UserName = "DemoUser", NewUserName = "NewUser" };
try { var response = client.UpdateUser(request);
} catch (EntityAlreadyExistsException) { Console.WriteLine("User 'NewUser' already exists."); }}
Obter informações sobre um usuárioEste exemplo mostra como recuperar informações sobre o usuário do IAM especificado incluindo a datade criação do usuário, o caminho, o ID exclusivo e o ARN. Se não especificar um nome de usuário, o IAMdeterminará o nome de usuário de forma implícita, com base no ID de chave de acesso da AWS usadopara assinar a solicitação nesta API.
Crie um objeto AmazonIdentityManagementServiceClient. Em seguida, crie um objeto GetUserRequestque contém o nome do usuário sobre o qual deseja obter informações. Chame o método GetUser doobjeto AmazonIdentityManagementServiceClient para obter as informações. Se o usuário nãoexistir, será lançada uma exceção.
public static void GetUser()
126
AWS SDK para .NET Guia do desenvolvedorGerenciar chaves de acesso do IAM
{ var client = new AmazonIdentityManagementServiceClient(); var request = new GetUserRequest() { UserName = "DemoUser" };
try { var response = client.GetUser(request); Console.WriteLine("Creation date: " + response.User.CreateDate.ToShortDateString()); Console.WriteLine("Password last used: " + response.User.PasswordLastUsed.ToShortDateString()); Console.WriteLine("UserId = " + response.User.UserId);
} catch (NoSuchEntityException) { Console.WriteLine("User 'DemoUser' does not exist."); }}
Excluir um usuárioEste exemplo mostra como excluir o usuário do IAM especificado. O usuário não deve pertencer aquaisquer grupos ou ter quaisquer chaves de acesso, certificados de assinatura ou políticas anexadas.
Crie um objeto AmazonIdentityManagementServiceClient. Em seguida, crie um objeto DeleteUserRequestque contém os parâmetros necessários, compostos pelo nome do usuário que deseja excluir. Chameo método DeleteUser do objeto AmazonIdentityManagementServiceClient para excluí-lo. Se ousuário não existir, será lançada uma exceção.
public static void DeleteUser(){ var client = new AmazonIdentityManagementServiceClient(); var request = new DeleteUserRequest() { UserName = "DemoUser" };
try { var response = client.DeleteUser(request);
} catch (NoSuchEntityException) { Console.WriteLine("User DemoUser' does not exist."); }}
Gerenciar chaves de acesso do IAMEsses exemplos .NET mostram a você como:
• Criar uma chave de acesso para um usuário• Obter a data em que a chave de acesso foi usada pela última vez• Atualizar o status de uma chave de acesso• Excluir uma chave de acesso
127
AWS SDK para .NET Guia do desenvolvedorGerenciar chaves de acesso do IAM
O cenárioOs usuários precisam de suas próprias chaves de acesso para fazer chamadas programáticas à AWSno AWS SDK para .NET. Para atender a essa necessidade, você pode criar, modificar, visualizar oumudar chaves de acesso (IDs de chave de acesso e chaves de acesso secretas) para os usuários do IAM.Quando você cria uma chave de acesso, seu status é ativo por padrão, o que significa que o usuário podeusá-la para chamadas à API.
O código C# usa o AWS SDK para .NET para gerenciar as chaves de acesso do IAM usando essesmétodos da classe AmazonIdentityManagementServiceClient:
• CreateAccessKey• ListAccessKeys• GetAccessKeyLastUsed• UpdateAccessKey• DeleteAccessKey
Para obter mais informações sobre as chaves de acesso do IAM, consulte Gerenciar chaves de acessopara usuários do IAM no Guia do usuário do IAM.
Crie chaves de acesso para um usuárioChame o método CreateAccessKey para criar uma chave de acesso de nomeS3UserReadOnlyAccess para os exemplos das chaves de acesso do IAM. O CreateAccessKeymethod first creates a user named :code:`S3UserReadOnlyAccess com apenasdireitos de acesso de leitura chamando o método CreateUser. Em seguida, ele cria um objetoAmazonIdentityManagementServiceClient e um objeto CreateAccessKeyRequest contendo o parâmetroUserName necessário para criar novas chaves de acesso. Depois, ele chama o método CreateAccessKeydo objeto AmazonIdentityManagementServiceClient.
public static void CreateAccessKey(){ try { CreateUser(); var iamClient = new AmazonIdentityManagementServiceClient(); // Create an access key for the IAM user that can be used by the SDK var accessKey = iamClient.CreateAccessKey(new CreateAccessKeyRequest { // Use the user created in the CreateUser example UserName = "S3UserReadOnlyAccess" }).AccessKey;
} catch (LimitExceededException e) { Console.WriteLine(e.Message); }}
public static User CreateUser(){ var iamClient = new AmazonIdentityManagementServiceClient(); try { // Create the IAM user var readOnlyUser = iamClient.CreateUser(new CreateUserRequest {
128
AWS SDK para .NET Guia do desenvolvedorGerenciar chaves de acesso do IAM
UserName = "S3UserReadOnlyAccess" }).User;
// Assign the read-only policy to the new user iamClient.PutUserPolicy(new PutUserPolicyRequest { UserName = readOnlyUser.UserName, PolicyName = "S3ReadOnlyAccess", PolicyDocument = S3_READONLY_POLICY }); return readOnlyUser; } catch (EntityAlreadyExistsException e) { Console.WriteLine(e.Message); var request = new GetUserRequest() { UserName = "S3UserReadOnlyAccess" };
return iamClient.GetUser(request).User;
}}
Listar as chaves de acesso de um usuárioCrie um objeto AmazonIdentityManagementServiceClient e um objeto ListAccessKeysRequest contendo osparâmetros necessários para recuperar as chaves de acesso do usuário. Isso inclui o nome do usuário doIAM e, opcionalmente, o número máximo de usuário de pares de chave de acesso que você deseja listar.Chame o método ListAccessKeys do objeto AmazonIdentityManagementServiceClient.
public static void ListAccessKeys(){
var iamClient = new AmazonIdentityManagementServiceClient(); var requestAccessKeys = new ListAccessKeysRequest { // Use the user created in the CreateAccessKey example UserName = "S3UserReadOnlyAccess", MaxItems = 10 }; var responseAccessKeys = iamClient.ListAccessKeys(requestAccessKeys); Console.WriteLine(" Access keys:");
foreach (var accessKey in responseAccessKeys.AccessKeyMetadata) { Console.WriteLine(" {0}", accessKey.AccessKeyId); }}
Obtenha a última data usada para chaves de acessoCrie um objeto AmazonIdentityManagementServiceClient e um objeto ListAccessKeysRequestcontendo o parâmetro UserName necessário para listar as chaves de acesso. Chame o métodoListAccessKeys do objeto AmazonIdentityManagementServiceClient. Faça o loop das chavesde acesso apresentadas, exibindo o AccessKeyId de cada chave e usando-o para criar um objetoGetAccessKeyLastUsedRequest. Chame o método GetAccessKeyLastUsed e exiba a hora que a chave foiusada pela última vez no console.
public static void GetAccessKeysLastUsed()
129
AWS SDK para .NET Guia do desenvolvedorGerenciar chaves de acesso do IAM
{
var iamClient = new AmazonIdentityManagementServiceClient(); var requestAccessKeys = new ListAccessKeysRequest { // Use the user we created in the CreateUser example UserName = "S3UserReadOnlyAccess" }; var responseAccessKeys = iamClient.ListAccessKeys(requestAccessKeys); Console.WriteLine(" Access keys:");
foreach (var accessKey in responseAccessKeys.AccessKeyMetadata) { Console.WriteLine(" {0}", accessKey.AccessKeyId); GetAccessKeyLastUsedRequest request = new GetAccessKeyLastUsedRequest() { AccessKeyId = accessKey.AccessKeyId }; var response = iamClient.GetAccessKeyLastUsed(request); Console.WriteLine("Key last used " + response.AccessKeyLastUsed.LastUsedDate.ToLongDateString()); }}
Atualize o status de uma chave de acessoCrie um objeto AmazonIdentityManagementServiceClient e um objeto ListAccessKeysRequestcontendo o nome do usuário para os quais listar as chaves de acesso. O nome de usuário desteexemplo é o usuário criado para os outros exemplos. Chame o método ListAccessKeys doAmazonIdentityManagementServiceClient. O ListAccessKeysResponse retornado contém umalista das chaves de acesso para esse usuário. Use a primeira chave de acesso na lista. Crie um objetoUpdateAccessKeyRequest, fornecendo os parâmetros UserName, AccessKeyId e Status. Chame ométodo UpdateAccessKey do objeto AmazonIdentityManagementServiceClient.
public static void UpdateKeyStatus(){ // This example changes the status of the key specified by its index in the list of access keys // Optionally, you could change the keynumber parameter to be an AccessKey ID var iamClient = new AmazonIdentityManagementServiceClient(); var requestAccessKeys = new ListAccessKeysRequest { UserName = "S3UserReadOnlyAccess" }; var responseAccessKeys = iamClient.ListAccessKeys(requestAccessKeys); UpdateAccessKeyRequest updateRequest = new UpdateAccessKeyRequest { UserName = "S3UserReadOnlyAccess", AccessKeyId = responseAccessKeys.AccessKeyMetadata[0].AccessKeyId, Status = StatusType.Active }; iamClient.UpdateAccessKey(updateRequest); Console.WriteLine(" Access key " + updateRequest.AccessKeyId + " updated");}
Excluir chaves de acessoCrie um objeto AmazonIdentityManagementServiceClient e um objeto ListAccessKeysRequestcontendo o nome do usuário como um parâmetro. Chame o método ListAccessKeys doAmazonIdentityManagementServiceClient. O ListAccessKeysResponse retornado contém umalista das chaves de acesso para esse usuário. Exclua cada chave de acesso na lista chamando o métodoDeleteAccessKey do AmazonIdentityManagementServiceClient.
130
AWS SDK para .NET Guia do desenvolvedorTrabalhar com políticas do IAM
public static void DeleteAccessKeys(){// Delete all the access keys created for the examples var iamClient = new AmazonIdentityManagementServiceClient(); var requestAccessKeys = new ListAccessKeysRequest { // Use the user created in the CreateUser example UserName = "S3UserReadOnlyAccess" }; var responseAccessKeys = iamClient.ListAccessKeys(requestAccessKeys); Console.WriteLine(" Access keys:");
foreach (var accessKey in responseAccessKeys.AccessKeyMetadata) { Console.WriteLine(" {0}", accessKey.AccessKeyId); iamClient.DeleteAccessKey(new DeleteAccessKeyRequest { UserName = "S3UserReadOnlyAccess", AccessKeyId = accessKey.AccessKeyId }); Console.WriteLine("Access Key " + accessKey.AccessKeyId + " deleted"); }
}
Trabalhar com políticas do IAMOs exemplos a seguir mostram como:
• Criar e excluir políticas do IAM.• Anexar e separar políticas do IAM das funções
O cenárioConceda permissões para um usuário ao criar uma política, que é um documento que lista as ações queum usuário pode executar e os recursos afetados por estas ações. Todas as ações ou recursos que nãosão explicitamente permitidos são negados por padrão. Crie políticas e anexe-as a usuários, grupos deusuários, funções assumidas por usuários e recursos.
Use o AWS SDK para .NET para criar e excluir políticas, associar e desanexar políticas de funções usandoestes métodos da classe AmazonIdentityManagementServiceClient:
• CreatePolicy• GetPolicy• AttachRolePolicy• DetachRolePolicy
Para obter mais informações sobre os usuários do IAM, consulte Visão geral do gerenciamento de acesso:permissões e políticas no Guia do usuário do IAM.
Criar uma política do IAMCrie um objeto AmazonIdentityManagementServiceClient. Em seguida, crie um objetoCreatePolicyRequest contendo os parâmetros necessários para criar uma nova política, que consistemno nome que deseja usar para a nova política e um documento de política. Crie o documento de política
131
AWS SDK para .NET Guia do desenvolvedorTrabalhar com políticas do IAM
chamando o método GenerateRolePolicyDocument fornecido. Ao retornar da chamada do métodoCreatePolicy, a CreatePolicyResponse contém o ARN da política, que é exibido no console. Anote-opara que possa usá-lo nos exemplos a seguir.
public static void CreatePolicyExample(){ var client = new AmazonIdentityManagementServiceClient(); // GenerateRolePolicyDocument is a custom method string policyDoc = GenerateRolePolicyDocument();
var request = new CreatePolicyRequest { PolicyName = "DemoEC2Permissions", PolicyDocument = policyDoc };
try { var createPolicyResponse = client.CreatePolicy(request); Console.WriteLine("Make a note, Policy named " + createPolicyResponse.Policy.PolicyName + " has Arn: : " + createPolicyResponse.Policy.Arn); } catch (EntityAlreadyExistsException) { Console.WriteLine ("Policy 'DemoEC2Permissions' already exits."); }
}
public static string GenerateRolePolicyDocument(){ // using Amazon.Auth.AccessControlPolicy;
// Create a policy that looks like this: /* { "Version" : "2012-10-17", "Id" : "DemoEC2Permissions", "Statement" : [ { "Sid" : "DemoEC2PermissionsStatement", "Effect" : "Allow", "Action" : [ "s3:Get*", "s3:List*" ], "Resource" : "*" } ] } */
var actionGet = new ActionIdentifier("s3:Get*"); var actionList = new ActionIdentifier("s3:List*"); var actions = new List<ActionIdentifier>();
actions.Add(actionGet); actions.Add(actionList);
var resource = new Resource("*"); var resources = new List<Resource>();
resources.Add(resource);
132
AWS SDK para .NET Guia do desenvolvedorTrabalhar com políticas do IAM
var statement = new Amazon.Auth.AccessControlPolicy.Statement(Amazon.Auth.AccessControlPolicy.Statement.StatementEffect.Allow) { Actions = actions, Id = "DemoEC2PermissionsStatement", Resources = resources }; var statements = new List<Amazon.Auth.AccessControlPolicy.Statement>();
statements.Add(statement);
var policy = new Policy { Id = "DemoEC2Permissions", Version = "2012-10-17", Statements = statements };
return policy.ToJson();}
Obter uma política do IAMCrie um objeto AmazonIdentityManagementServiceClient. Em seguida, crie um objeto GetPolicyRequestque contém o parâmetro necessário para obter a política, o ARN da política, que foi retornado pelo métodoCreatePolicy no exemplo anterior.
Chame o método GetPolicy.
public static void GetPolicy(){ var client = new AmazonIdentityManagementServiceClient(); var request = new GetPolicyRequest { PolicyArn = "arn:aws:iam::123456789:policy/DemoEC2Permissions" };
try { var response = client.GetPolicy(request); Console.WriteLine("Policy " + response.Policy.PolicyName + "successfully retrieved");
} catch (NoSuchEntityException) { Console.WriteLine ("Policy 'DemoEC2Permissions' does not exist."); }
}
Anexar uma política de função gerenciadaCrie um objeto AmazonIdentityManagementServiceClient. Em seguida, crie um objetoAttachRolePolicyRequest que contém os parâmetros necessários para anexar a política à função, o nomeda função e a política Jason retornada pelo método GenerateRolePolicyDocument. Use uma funçãoválida entre as funções associadas à sua conta da AWS.
public static void AttachRolePolicy()
133
AWS SDK para .NET Guia do desenvolvedorTrabalhar com políticas do IAM
{ var client = new AmazonIdentityManagementServiceClient(); string policy = GenerateRolePolicyDocument(); CreateRoleRequest roleRequest = new CreateRoleRequest() { RoleName = "tester", AssumeRolePolicyDocument = policy };
var request = new AttachRolePolicyRequest() { PolicyArn = "arn:aws:iam::123456789:policy/DemoEC2Permissions", RoleName = "tester" }; try { var response = client.AttachRolePolicy(request); Console.WriteLine("Policy DemoEC2Permissions attached to Role TestUser"); } catch (NoSuchEntityException) { Console.WriteLine ("Policy 'DemoEC2Permissions' does not exist"); } catch (InvalidInputException) { Console.WriteLine ("One of the parameters is incorrect"); }}
Separar uma política de função gerenciadaCrie um objeto AmazonIdentityManagementServiceClient. Em seguida, crie um objetoDetachRolePolicyRequest que contém os parâmetros necessários para anexar a política à função, o nomeda função e a política Jason retornada pelo método GenerateRolePolicyDocument. Use a funçãoutilizada para anexar a política no exemplo anterior.
public static void DetachRolePolicy(){ var client = new AmazonIdentityManagementServiceClient(); string policy = GenerateRolePolicyDocument(); CreateRoleRequest roleRequest = new CreateRoleRequest() { RoleName = "tester", AssumeRolePolicyDocument = policy };
var request = new DetachRolePolicyRequest() { PolicyArn = "arn:aws:iam::123456789:policy/DemoEC2Permissions", RoleName = "tester" }; try { var response = client.DetachRolePolicy(request); Console.WriteLine("Policy DemoEC2Permissions detached from Role 'tester'"); } catch (NoSuchEntityException e) { Console.WriteLine (e.Message); }
134
AWS SDK para .NET Guia do desenvolvedorTrabalhar com certificados de servidor do IAM
catch (InvalidInputException i) { Console.WriteLine (i.Message); }}
Trabalhar com certificados de servidor do IAMEsses exemplos .NET mostram a você como:
• Listar certificados do servidor• Obter certificados do servidor• Atualizar certificados do servidor• Excluir certificados do servidor
O cenárioNestes exemplos, você terá tarefas básicas para gerenciar certificados de servidores para conexõesHTTPS. Para habilitar conexões HTTPS com seu site ou aplicativo na AWS, você precisa de um certificadode servidor SSL/TLS. Para usar um certificado que você obteve de um provedor externo com seu siteou aplicativo na AWS, é necessário fazer upload desse certificado no IAM ou importá-lo para o AWSCertificate Manager.
Estes exemplos usam o AWS SDK para .NET para enviar e receber mensagens usando estes métodos daclasse AmazonIdentityManagementServiceClient:
• ListServerCertificates• GetServerCertificate• UpdateServerCertificate• DeleteServerCertificate
Para obter mais informações sobre certificados de servidor, consulte Trabalhar com certificados deservidor no Guia do usuário do IAM.
Listar seus certificados do servidorCrie um objeto AmazonIdentityManagementServiceClient. Em seguida, crie um objetoListServerCertificatesRequest.
Não há parâmetros obrigatórios. Chame o método ListServerCertificates do objetoAmazonIdentityManagementServiceClient.
public static void ListCertificates(){ try { var iamClient = new AmazonIdentityManagementServiceClient(); var request = new ListServerCertificatesRequest(); var response = iamClient.ListServerCertificates(request); foreach (KeyValuePair<string, string> kvp in response.ResponseMetadata.Metadata) { Console.WriteLine("Key = {0}, Value = {1}", kvp.Key, kvp.Value); }
135
AWS SDK para .NET Guia do desenvolvedorTrabalhar com certificados de servidor do IAM
} catch(Exception e) { Console.WriteLine(e.Message); }}
Obter um certificado do servidorCrie um objeto AmazonIdentityManagementServiceClient. Em seguida, crie um objetoGetServerCertificateRequest, especificando o ServerCertificateName. Chame o métodoGetServerCertificate do objeto AmazonIdentityManagementServiceClient.
public static void GetCertificate(){ try { var iamClient = new AmazonIdentityManagementServiceClient(); var request = new GetServerCertificateRequest(); request.ServerCertificateName = "CERTIFICATE_NAME"; var response = iamClient.GetServerCertificate(request); Console.WriteLine("CertificateName = " + response.ServerCertificate.ServerCertificateMetadata.ServerCertificateName); Console.WriteLine("Certificate Arn = " + response.ServerCertificate.ServerCertificateMetadata.Arn); } catch (Exception e) { Console.WriteLine(e.Message); }}
Atualizar um certificado do servidorCrie um objeto AmazonIdentityManagementServiceClient. Em seguida, crie umobjeto UpdateServerCertificateRequest, especificando ServerCertificateName eNewServerCertificateName. Chame o método UpdateServerCertificate do objetoAmazonIdentityManagementServiceClient.
public static void UpdateCertificate(){ try { var iamClient = new AmazonIdentityManagementServiceClient(); var request = new UpdateServerCertificateRequest(); request.ServerCertificateName = "CERTIFICATE_NAME"; request.NewServerCertificateName = "NEW_Certificate_NAME"; var response = iamClient.UpdateServerCertificate(request); if (response.HttpStatusCode.ToString() == "OK") Console.WriteLine("Update succesful"); else Console.WriteLine("HTTpStatusCode returned = " + response.HttpStatusCode.ToString()); } catch (Exception e) { Console.WriteLine(e.Message); }
}
136
AWS SDK para .NET Guia do desenvolvedorListar informações da conta do IAM
Excluir um certificado do servidorCrie um objeto AmazonIdentityManagementServiceClient. Em seguida, crie um objetoDeleteServerCertificateRequest, especificando o ServerCertificateName. Chame o métodoDeleteServerCertificate do objeto AmazonIdentityManagementServiceClient.
public static void DeleteCertificate(){ try { var iamClient = new AmazonIdentityManagementServiceClient(); var request = new DeleteServerCertificateRequest(); request.ServerCertificateName = "CERTIFICATE_NAME"; var response = iamClient.DeleteServerCertificate(request); if (response.HttpStatusCode.ToString() == "OK") Console.WriteLine(request.ServerCertificateName + " deleted"); else Console.WriteLine("HTTpStatusCode returned = " + response.HttpStatusCode.ToString()); } catch (Exception e) { Console.WriteLine(e.Message); }}
Listar informações da conta do IAMO AWS SDK para .NET oferece suporte ao IAM, que é um web service que permite que clientes da AWSgerenciem usuários e suas permissões na AWS.
O exemplo a seguir mostra como listar contas de usuário acessíveis no IAM. Para cada conta de usuário,são listados também seus grupos, políticas e IDs associados, bem como os IDs da chave de acesso.
public static void ListUsersAndGroups(){ var iamClient = new AmazonIdentityManagementServiceClient(); var requestUsers = new ListUsersRequest(); var responseUsers = iamClient.ListUsers(requestUsers);
foreach (var user in responseUsers.Users) { Console.WriteLine("For user {0}:", user.UserName); Console.WriteLine(" In groups:");
var requestGroups = new ListGroupsForUserRequest { UserName = user.UserName }; var responseGroups = iamClient.ListGroupsForUser(requestGroups);
foreach (var group in responseGroups.Groups) { Console.WriteLine(" {0}", group.GroupName); }
Console.WriteLine(" Policies:");
var requestPolicies = new ListUserPoliciesRequest { UserName = user.UserName
137
AWS SDK para .NET Guia do desenvolvedorComo conceder acesso usando uma função do IAM
}; var responsePolicies = iamClient.ListUserPolicies(requestPolicies);
foreach (var policy in responsePolicies.PolicyNames) { Console.WriteLine(" {0}", policy); }
var requestAccessKeys = new ListAccessKeysRequest { UserName = user.UserName }; var responseAccessKeys = iamClient.ListAccessKeys(requestAccessKeys);
Console.WriteLine(" Access keys:");
foreach (var accessKey in responseAccessKeys.AccessKeyMetadata) { Console.WriteLine(" {0}", accessKey.AccessKeyId); } }}
Para informações de referência da API relacionada, consulte Amazon.IdentityManagement eAmazon.IdentityManagement.Model.
Como conceder acesso usando uma função do IAMEste exemplo de .NET mostra como:
• Criar um programa de exemplo que recupere um objeto do Amazon S3• Criar uma função do IAM• Iniciar uma instância do Amazon EC2 e especificar a função do IAM• Executar o exemplo na instância do Amazon EC2
O cenárioTodas as solicitações à AWS devem ser assinadas criptograficamente usando as credenciais emitidas pelaAWS. Portanto, você precisa de uma estratégia para gerenciar credenciais para software em execução nasinstâncias do Amazon EC2. Você tem de distribuir, armazenar e girar essas credenciais com segurança,mas também mantendo-as acessível ao software.
As funções do IAM permitem que você gerencie efetivamente as credenciais da AWS para software emexecução nas instâncias do EC2. Você cria uma função do IAM e a configura com as permissões exigidaspelo software. Para obter mais informações sobre os benefícios de usar as funções do IAM, consulteFunções do IAM para o Amazon EC2 no Guia do usuário do Amazon EC2 para instâncias do Windows eFunções (delegação e federação) no Guia do usuário do IAM.
Para usar as permissões, o software cria um objeto do cliente para o serviço da AWS. As construtorpesquisa as credenciais na cadeia do provedor de credenciais. Para .NET, a cadeia de provedor decredenciais é a seguinte:
• O arquivo App.config• Metadados de instância associados com a função do IAM para a instância do EC2
Se o cliente não encontrar as credenciais em App.config, ele recuperará as credenciais temporáriascom as mesmas permissões que as associadas à função do IAM pelos metadados da instância. As
138
AWS SDK para .NET Guia do desenvolvedorComo conceder acesso usando uma função do IAM
credenciais são armazenadas pelo construtor em nome do software de aplicativo e usadas para fazerchamadas para a AWS a partir desse objeto do cliente. Embora as credenciais sejam temporárias e, porfim, expirem, o cliente do SDK as atualiza periodicamente para que continuem para habilitar o acesso.Essa atualização periódica é totalmente transparente ao software do aplicativo.
Os exemplos a seguir mostram o programa de exemplo que recupera um objeto do Amazon S3 usando ascredenciais da AWS que você configurar. Você cria uma função do IAM para fornecer as credenciais daAWS. Por fim, você executar uma instância com uma função do IAM que fornece as credenciais da AWSao programa de exemplo executado na instância.
Criar um exemplo que recupera um objeto do Amazon S3O código de exemplo a seguir exige um arquivo de texto no bucket do Amazon S3 ao qual você tenhaacesso e credenciais da AWS que forneçam a você acesso ao bucket do Amazon S3.
Para obter mais informações sobre como criar um bucket do Amazon S3 e carregar um objeto, consulteo Guia de conceitos básicos do Amazon S3. Para obter mais informações sobre credenciais da AWS,consulte Configuração de credenciais da AWS (p. 23).
using System;using System.IO;using System.Threading;using System.Threading.Tasks;
using Amazon;using Amazon.S3;using Amazon.S3.Model;
namespace S3ShowTextItem{ class S3Sample { static async Task<GetObjectResponse> MyGetObjectAsync(string region, string bucket, string item) { RegionEndpoint reg = RegionEndpoint.GetBySystemName(region); AmazonS3Client s3Client = new AmazonS3Client(reg);
Console.WriteLine("Retrieving (GET) an object");
GetObjectResponse response = await s3Client.GetObjectAsync(bucket, item, new CancellationToken());
return response; }
public static void Main(string[] args) { if (args.Length < 4) { Console.WriteLine("You must supply a region, bucket name, text file name, and output file name"); return; }
try { Task<GetObjectResponse> response = MyGetObjectAsync(args[0], args[1], args[2]);
Stream responseStream = response.Result.ResponseStream; StreamReader reader = new StreamReader(responseStream);
139
AWS SDK para .NET Guia do desenvolvedorComo conceder acesso usando uma função do IAM
string responseBody = reader.ReadToEnd();
using(FileStream s = new FileStream(args[3], FileMode.Create)) using(StreamWriter writer = new StreamWriter(s)) { writer.WriteLine(responseBody); } } catch (AmazonS3Exception s3Exception) { Console.WriteLine(s3Exception.Message, s3Exception.InnerException); }
Console.WriteLine("Press enter to continue"); Console.ReadLine(); } }}
Para testar o código de exemplo
1. Abra o Visual Studio e crie um projeto Console App (.NET Framework) usando o .NET Framework 4.5ou posterior.
2. Adicione o pacote AWSSDK.S3 NuGet ao seu projeto.3. Substitua o código no arquivo Program.cs pelo código de exemplo mostrado acima.4. Compile e execute o programa de exemplo. Se o programa tiver êxito, exibirá a saída a seguir e criará
um arquivo no disco local que contém texto recuperado do arquivo de texto no Amazon S3.
Retrieving (GET) an object
Se o programa falhar, verifique se você está usando as credenciais que forneceram acesso ao bucket.5. (Opcional) Transfira o programa de exemplo para uma instância do Windows em execução na
qual você não tenha configurado credenciais. Execute o programa e verifique se ele falha por nãoconseguir localizar as credenciais.
Criar uma função do IAMCrie uma função do IAM com as permissões apropriadas acessar o Amazon S3.
Para criar a função do IAM
1. Abra o console do IAM.2. No painel de navegação, escolha Roles e depois Create New Role.3. Digite um nome para a função e escolha Next Step. Lembre-se desse nome, pois você precisará dele
quando executar sua instância do EC2.4. Em AWS Service Roles, selecione Amazon EC2. Em Select Policy Template, escolha Amazon S3
Read Only Access. Analise a política e depois escolha Next Step.5. Revise as informações da função e escolha Create Role.
Executar uma instância do EC2 e especificar a função do IAMÉ possível usar o console do Amazon EC2 ou o AWS SDK para .NET para executar uma instância do EC2com uma função do IAM.
140
AWS SDK para .NET Guia do desenvolvedorComo conceder acesso usando uma função do IAM
• Uso do console: siga as instruções em Iniciar uma instância do Windows no Guia do usuário do AmazonEC2 para instâncias do Windows. Quando você chegar à página Review Instance Launch, escolhaEdit instance details. Em IAM role, especifique a função do IAM criada anteriormente. Conclua oprocedimento conforme indicado. Será necessário criar ou usar um grupo de segurança existente e umpar de chaves para se conectar à instância.
• Uso do AWS SDK para .NET: consulte Iniciar uma instância do Amazon EC2 (p. 100).
Um usuário do IAM não pode iniciar uma instância com a função do IAM sem permissões concedidas pelapolítica a seguir.
{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": [ "iam:PassRole", "iam:ListInstanceProfiles", "ec2:*" ], "Resource": "*" }]}
Executar o programa de exemplo na instância do EC2Para transferir o programa de exemplo à sua instância do EC2, conecte-se à instância usando o Consolede gerenciamento da AWS como descrito no procedimento a seguir.
Note
Você também pode se conectar usando o Toolkit for Visual Studio (consulte Conectar-se a umainstância do Amazon EC2 no AWS Toolkit for Visual Studio) e copie os arquivos da sua unidadelocal para a instância. A sessão de Área de Trabalho Remota é configurada automaticamentepara que suas unidades locais estejam disponíveis para a instância.
Para executar o programa de exemplo na instância do EC2
1. Abra o console do Amazon EC2.2. Obtenha a senha para sua instância do EC2:
a. No painel de navegação, escolha Instances. Selecione a instância e escolha Connect (Conectar).b. Na caixa de diálogo Conectar à sua instância, escolha Obter senha. (Levará alguns minutos
depois que a instância for iniciada para que a senha esteja disponível.)c. Escolha Browse e navegue até o arquivo de chave privada que você criou quando lançou a
instância. Escolha o arquivo e, depois, selecione Open (Abrir) para copiar o conteúdo do arquivona caixa de conteúdo.
d. Escolha Decrypt Password. O console exibe a senha padrão do administrador para a instânciana caixa de diálogo Connect To Your Instance, substituindo o link para Get Password mostradoanteriormente pela senha.
e. Registre a senha padrão do administrador ou copie-a para a área de transferência. Vocêprecisará dessa senha para se conectar à instância.
3. Conecte-se à sua instância do EC2:
a. Escolha Download Remote Desktop File. Quando seu navegador solicitar, salve o arquivo .rdp.Quando você terminar, escolha Close para fechar a caixa de diálogo Connect To Your Instance.
141
AWS SDK para .NET Guia do desenvolvedorUsar chaves do AWS KMS com o
AmazonS3EncryptionClient no AWS SDK para .NET
b. Vá até o diretório de downloads, clique com o botão direito sobre o arquivo .rdp e escolha Edit.Na guia Local Resources, em Local devices and resources, escolha More. Escolha Drives paradisponibilizar seus discos locais para sua instância. Em seguida, selecione OK.
c. Escolha Connect para conectar-se à sua instância. Talvez você receba um aviso de que opublicador da conexão remota é desconhecido.
d. Faça login na instância quando solicitado, usando a conta Administrator padrão e a senha doadministrador que você registrou ou copiou anteriormente.
Às vezes, quando se copia e cola conteúdo, os dados podem ser corrompidos. Se você encontraro erro "Password Failed" (Ocorreu uma falha na senha) ao fazer login, experimente digitar asenha manualmente. Para obter mais informações, consulte Estabelecer uma conexão com asua instância do Windows usando o RDP e Solução de problemas das instâncias do Windows emGuia do usuário do Amazon EC2 para instâncias do Windows.
4. Copie o programa e os conjuntos da AWS (AWSSDK.Core.dll e AWSSDK.S3.dll) do seu discolocal para a instância.
5. Execute o programa e verifique se ele tem sucesso ao usar as credenciais fornecidas pela função doIAM.
Retrieving (GET) an object
Usar chaves do AWS KMS com oAmazonS3EncryptionClient no AWS SDKpara .NET
A classe AmazonS3EncryptionClient implementa a mesma interface do AmazonS3Client padrão. Issosignifica que é fácil alternar para a classe AmazonS3EncryptionClient. Na verdade, o código doaplicativo não terá ciência da criptografia e da descriptografia acontecendo automaticamente no cliente.
Você pode usar uma chave do AWS KMS como a chave mestra ao usar a classeAmazonS3EncryptionClient na criptografia no lado do cliente. Tudo o que você precisa fazer é criarum objeto EncryptionMaterials que contenha um ID da chave do KMS. Em seguida, você passa oobjeto EncryptionMaterials para o construtor do AmazonS3EncryptionClient.
A principal vantagem de usar uma chave do AWS KMS como a chave mestra é que não é necessárioarmazenar e gerenciar as próprias chaves mestras. Isso é feito pela AWS. A segunda vantagem é que elatorna a classe do AWS SDK para .NET AmazonS3EncryptionClient interoperável com a classe doAWS SDK for Java AmazonS3EncryptionClient. Isso significa que é possível criptografar com o AWSSDK for Java e descriptografar com o AWS SDK para .NET e vice-versa.
Note
O AWS SDK para .NET do AmazonS3EncryptionClient só é compatível com chavesmestras do KMS quando executado no modo de metadados. O modo de arquivo da instruçãoAmazonS3EncryptionClient do AWS SDK para .NET continua incompatível comAmazonS3EncryptionClient do AWS SDK for Java
Para obter mais informações sobre a criptografia no lado do cliente com a classeAmazonS3EncryptionClient e como a criptografia de envelope funciona, consulte Client Side DataEncryption with AWS SDK for .NET and Amazon S3 (Criptografia de dados do lado do cliente com AWSSDK para .NET e Amazon S3).
O exemplo a seguir demonstra como usar chaves do AWS KMS com a classe AmazonS3EncryptionClient.
142
AWS SDK para .NET Guia do desenvolvedorUsar chaves do AWS KMS com o
AmazonS3EncryptionClient no AWS SDK para .NET
No Visual Studio, crie um projeto Console App (.NET Framework) usando o .NET Framework 4.5ou posterior e faça referência às versões apropriadas dos seguintes pacotes NuGet: AWSSDK.S3 eAWSSDK.KeyManagementService. Ao executar o aplicativo, inclua o código Region, o nome de um bucketdo Amazon S3 existente e um nome para o novo objeto do Amazon S3.
using System;using System.IO;using System.Threading.Tasks;
using Amazon;using Amazon.KeyManagementService;using Amazon.KeyManagementService.Model;using Amazon.S3.Encryption;using Amazon.S3.Model;
namespace KmsS3Encryption{ class S3Sample { static async Task<CreateKeyResponse> MyCreateKeyAsync(string regionName) { RegionEndpoint region = RegionEndpoint.GetBySystemName(regionName);
AmazonKeyManagementServiceClient kmsClient = new AmazonKeyManagementServiceClient(region);
CreateKeyResponse response = await kmsClient.CreateKeyAsync(new CreateKeyRequest());
return response; }
static async Task<GetObjectResponse> MyPutObjectAsync(EncryptionMaterials materials, string bucketName, string keyName) { // CryptoStorageMode.ObjectMetadata is required for KMS EncryptionMaterials var config = new AmazonS3CryptoConfiguration() { StorageMode = CryptoStorageMode.ObjectMetadata };
AmazonS3EncryptionClient s3Client = new AmazonS3EncryptionClient(config, materials);
// encrypt and put object var putRequest = new PutObjectRequest { BucketName = bucketName, Key = keyName, ContentBody = "object content" };
await s3Client.PutObjectAsync(putRequest);
// get object and decrypt var getRequest = new GetObjectRequest { BucketName = bucketName, Key = keyName };
GetObjectResponse response = await s3Client.GetObjectAsync(getRequest);
return response; }
143
AWS SDK para .NET Guia do desenvolvedorGerenciar recursos do Domain Name
System (DNS) usando o Amazon Route 53
public static void Main(string[] args) { if (args.Length < 3) { Console.WriteLine("You must supply a Region, bucket name, and item name:"); Console.WriteLine("Usage: KmsS3Encryption REGION BUCKET ITEM"); return; }
string regionName = args[0]; string bucketName = args[1]; string itemName = args[2];
Task<CreateKeyResponse> response = MyCreateKeyAsync(regionName);
KeyMetadata keyMetadata = response.Result.KeyMetadata; string kmsKeyId = keyMetadata.KeyId;
// An object that contains information about the CMK created by this operation. EncryptionMaterials kmsEncryptionMaterials = new EncryptionMaterials(kmsKeyId);
Task<GetObjectResponse> goResponse = MyPutObjectAsync(kmsEncryptionMaterials, bucketName, itemName);
Stream stream = goResponse.Result.ResponseStream; StreamReader reader = new StreamReader(stream);
Console.WriteLine(reader.ReadToEnd());
Console.WriteLine("Press any key to continue..."); Console.ReadKey(); } }}
Veja o exemplo completo no GitHub.
Gerenciar recursos do Domain Name System(DNS) usando o Amazon Route 53
O AWS SDK para .NET oferece suporte ao Amazon Route 53, que é um web service de Domain NameSystem (DNS) que oferece roteamento seguro e confiável para a sua infraestrutura que utiliza os produtosda Amazon Web Services (AWS), como o Amazon Elastic Compute Cloud (Amazon EC2), o Elastic LoadBalancing ou o Amazon Simple Storage Service (Amazon S3). Também use o Route 53 para rotearusuários de fora da AWS para a sua infraestrutura. Este tópico descreve como usar o AWS SDK para .NETpara criar um Route 53 :r53-dg:` hosted zone <AboutHZWorkingWith>` e adicionar um novo conjunto deregistro de recurso a essa zona.
Note
Este tópico assume que você já esteja familiarizado com o uso do Route 53 e já tenha instalado oAWS SDK para .NET. Para obter mais informações sobre o Route 53, consulte o Amazon Route53 Developer Guide (Guia do desenvolvedor do Amazon Route 53). Para obter informações sobrecomo instalar o AWS SDK para .NET, consulte Configurar o AWS SDK para .NET (p. 14).
O procedimento básico é como se segue.
Para criar uma zona hospedada e atualizar os conjuntos de registros
1. Crie uma zona hospedada.
144
AWS SDK para .NET Guia do desenvolvedorGerenciar recursos do Domain Name
System (DNS) usando o Amazon Route 53
2. Crie um lote de alterações que contém um ou mais conjuntos de registros, e instruções sobre qual açãoexecutar para cada conjunto.
3. Envie uma solicitação de alteração à zona hospedada que contém o lote de alterações.4. Monitore a alteração para verificar a sua conclusão.
O exemplo é um aplicativo simples do console que mostra como usar o AWS SDK para .NET paraimplementar esse procedimento em um conjunto de registros básico.
Para executar este exemplo
1. No menu Arquivo do Visual Studio, selecione Novo e, em seguida, selecione Projeto.2. Selecione o modelo Projeto vazio da AWS e especifique o nome e o local do projeto.3. Especifique o perfil de credenciais e a região da AWS padrões do aplicativo, adicionados ao arquivo
App.config do projeto. Este exemplo assume que a região está definida como Leste dos EUA (Norteda Virgínia) e o perfil está definido como padrão. Para obter mais informações sobre os perfis, consulteConfiguração das credenciais da AWS (p. 23).
4. Abra o program.cs e substitua as declarações using e o código em Main pelo códigocorrespondente do exemplo a seguir. Se estiver usando a região e o perfil de credenciais padrões,compile e execute o aplicativo como está. Caso contrário, forneça um perfil e região apropriados,conforme discutido nas observações que acompanham o exemplo.
using System;using System.Collections.Generic;using System.Threading;
using Amazon;using Amazon.Route53;using Amazon.Route53.Model;
namespace Route53_RecordSet{ //Create a hosted zone and add a basic record set to it class recordset { public static void Main(string[] args) { string domainName = "www.example.org";
//[1] Create an Amazon Route 53 client object var route53Client = new AmazonRoute53Client();
//[2] Create a hosted zone var zoneRequest = new CreateHostedZoneRequest() { Name = domainName, CallerReference = "my_change_request" };
var zoneResponse = route53Client.CreateHostedZone(zoneRequest);
//[3] Create a resource record set change batch var recordSet = new ResourceRecordSet() { Name = domainName, TTL = 60, Type = RRType.A, ResourceRecords = new List<ResourceRecord> { new ResourceRecord { Value = "192.0.2.235" }
145
AWS SDK para .NET Guia do desenvolvedorGerenciar recursos do Domain Name
System (DNS) usando o Amazon Route 53
} };
var change1 = new Change() { ResourceRecordSet = recordSet, Action = ChangeAction.CREATE };
var changeBatch = new ChangeBatch() { Changes = new List<Change> { change1 } };
//[4] Update the zone's resource record sets var recordsetRequest = new ChangeResourceRecordSetsRequest() { HostedZoneId = zoneResponse.HostedZone.Id, ChangeBatch = changeBatch };
var recordsetResponse = route53Client.ChangeResourceRecordSets(recordsetRequest);
//[5] Monitor the change status var changeRequest = new GetChangeRequest() { Id = recordsetResponse.ChangeInfo.Id };
while (ChangeStatus.PENDING == route53Client.GetChange(changeRequest).ChangeInfo.Status) { Console.WriteLine("Change is pending."); Thread.Sleep(15000); }
Console.WriteLine("Change is complete."); Console.ReadKey(); } }}
Os números nas seções a seguir estão relacionados aos comentários do exemplo anterior.
[1] Criar um objeto de cliente
O objeto deve ter as seguintes informações:Uma região da AWS
Ao chamar um método do cliente, a solicitação HTTP subjacente é enviada para esse endpoint.Um perfil de credenciais
O perfil deve conceder permissões para as ações que pretende usar — neste caso, as açõesdo Route 53. Tentativas de chamar ações sem as devidas permissões falharão. Para obter maisinformações, consulte Configuração das credenciais da AWS (p. 23).
A classe AmazonRoute53Client oferece suporte a um conjunto de métodos públicos usados parainvocar as Amazon Route 53 actions (ações do Amazon Route 53). Crie o objeto de cliente aoinstanciar uma nova instância da classe AmazonRoute53Client. Existem vários construtores.
146
AWS SDK para .NET Guia do desenvolvedorGerenciar recursos do Domain Name
System (DNS) usando o Amazon Route 53
[2] Criar uma zona hospedada
Uma zona hospedada atende o mesmo propósito que um arquivo de zona DNS tradicional. Elarepresenta uma coleção de conjuntos de registro de recurso gerenciados juntos sob um único nomede domínio.
Para criar uma hosted zone1. Crie um objeto CreateHostedZoneRequest e especifique os parâmetros de solicitação a seguir.
Existem também dois parâmetros opcionais que não são usados neste exemplo.Name
(Obrigatório) O nome de domínio que deseja registrar, www.example.com para este exemplo.Este nome de domínio é destinado somente para exemplos. Ele não pode ser registrado com umregistrador de nome de domínio, mas pode ser usado para a criação de uma zona hospedadapara fins de aprendizado.
CallerReference
(Obrigatório) Uma string arbitrária definida pelo usuário que serve como um ID de solicitação podeser usada para realizar novas tentativas de solicitações com falha. Se executar este aplicativovárias vezes, é necessário alterar o valor CallerReference.
1. Transmita o objeto CreateHostedZoneRequest para o método CreateHostedZone do objeto decliente. O método retorna um objeto CreateHostedZoneResponse que contém informações sobre asolicitação, incluindo a propriedade HostedZone.Id que identifica a zona.
[3] Criar um lote de alterações do conjunto de registro de recurso
Uma zona hospedada pode ter vários conjuntos de registro de recurso. Cada conjunto especificacomo um subconjunto do tráfego de domínio, como solicitações do e-mail, deve ser roteado. Épossível atualizar os conjuntos de registros de recurso de uma zona com uma única solicitação.A primeira etapa é empacotar todas as atualizações em um objeto ChangeBatch. Este exemploespecifica apenas uma atualização, adicionar um conjunto de registro de recurso básico à zona, masum objeto ChangeBatch pode conter atualizações para vários conjuntos de registro de recurso.
Para criar um objeto ChangeBatch1. Crie um objeto ResourceRecordSet para cada conjunto de registro de recurso que deseja atualizar.
O grupo de propriedades especificado depende do tipo de conjunto de registro de recurso. Paraobter uma descrição completa das propriedades usadas pelos diferentes conjuntos de registro derecurso, consulte Values that You Specify When You Create or Edit Amazon Route 53 ResourceRecord Sets (Valores especificados ao criar ou editar conjuntos de registro de recurso do AmazonRoute 53). O objeto ResourceRecordSet de exemplo representa um basic resource record set(conjunto de registro de recurso básico), e especifica as propriedades necessárias a seguir.Name
O nome do domínio ou subdomínio, www.example.com para este exemplo.TTL
A quantidade de tempo, em segundos, em que os resolvedores recursivos de DNS devemarmazenar em cache as informações sobre esse conjunto de registro de recurso, 60 segundosneste exemplo.
Type
O tipo de registro de DNS, A para este exemplo. Para obter uma lista completa, consulteSupported DNS Resource Record Types (Tipos de registro de recurso de DNS com suporte).
ResourceRecords
Uma lista de um ou mais objetos ResourceRecord, cada um contendo um valor de registro deDNS que depende do tipo de registro de DNS. Para um tipo de registro A, o valor de registros
147
AWS SDK para .NET Guia do desenvolvedorGerenciar recursos do Domain Name
System (DNS) usando o Amazon Route 53
é um endereço IPv4, que para este exemplo está definido como um endereço de exemplopadrão, 192.0.2.235.
2. Crie um objeto Change (Altere) para cada conjunto de registro de recurso, e defina as propriedadesa seguir.ResourceRecordSet
O objeto ResourceRecordSet criado na etapa anterior.Action
A ação a ser executada para esse conjunto de registro de recurso: CREATE, DELETE ouUPSERT. Para obter mais informações sobre essas ações, consulte Elements (Elementos). Esteexemplo cria um novo conjunto de registro de recurso na zona hospedada, portanto Actionestá definida como CREATE.
3. Crie um objeto ChangeBatch e defina a propriedade Changes para uma lista dos objetos Changecriados na etapa anterior.
[4] Atualizar os conjuntos de registro de recurso da zona
Para atualizar os conjuntos de registro de recurso, transmita o objeto ChangeBatch para a zonahospedada, conforme mostrado a seguir.
Como atualizar os conjuntos de registro de recurso da zona hospedada1. Crie um objeto ChangeResourceRecordSetsRequest com as seguintes configurações de
propriedade.HostedZoneId
O ID da zona hospedada, definido no exemplo como o ID retornado no objetoCreateHostedZoneResponse. Para obter o ID de uma zona hospedada existente, chameListHostedZones.
ChangeBatch
Um objeto ChangeBatch que contém as atualizações.2. Transmita o objeto ChangeResourceRecordSetsRequest para o método
ChangeResourceRecordSets do objeto de cliente. Ele retorna um objetoChangeResourceRecordSetsResponse, que contém um ID de solicitação usado para monitorar oandamento da solicitação.
[5] Monitorar o status da atualização
As atualizações dos conjuntos de registro de recurso geralmente demoram em torno de um minutopara se propagarem no sistema. É possível monitorar o andamento da atualização e verificar a suaconclusão da seguinte forma.
Para monitorar o status da atualização1. Crie um objeto GetChangeRequest e defina a propriedade Id como ID de solicitação retornado pelo
ChangeResourceRecordSets.2. Utilize um loop de espera para chamar periodicamente o método GetChange do objeto de cliente.
GetChange retorna PENDING enquanto a atualização estiver em progresso, e INSYNC após aconclusão. Use o mesmo objeto GetChangeRequest para todas as chamadas do método.
148
AWS SDK para .NET Guia do desenvolvedorUsar o armazenamento na Internetdo Amazon Simple Storage Service
Usar o armazenamento na Internet do AmazonSimple Storage Service
O AWS SDK para .NET oferece suporte ao Amazon Simple Storage Service (Amazon S3), que éarmazenamento para a Internet. Ele foi projetado para facilitar a computação de escala na web para osdesenvolvedores. Para obter mais informações, consulte Amazon S3.
Os links a seguir fornecem exemplos de programação do Amazon S3 com o AWS SDK para .NET:
• Uso do AWS SDK para .NET para programação do Amazon S3• Fazer solicitações usando a conta da AWS ou as credenciais de usuário do IAM• Fazer solicitações usando as credenciais temporárias do usuário do IAM• Fazer solicitações usando as credenciais temporárias de usuário federado• Gerenciar ACLs• Criação de um bucket• Upload de um objeto• Multipart Upload com a API de alto nível• Multipart Upload com a API de baixo nível• Listar objetos• Chaves de listagem• Obter um objeto• Copiar um objeto• Copiar um objeto com a API do Multipart Upload• Exclusão de um objeto• Excluir de vários objetos• Restaurar um objeto• Configurar um bucket para notificações• Gerenciar o ciclo de vida de um objeto• Gerenciar um URL de objeto pré-assinado• Gerenciamento de sites• Ativação do compartilhamento de recursos de origem cruzada (CORS)• Especificar a criptografia no lado do servidor• Especificar a criptografia do lado do servidor com chaves de criptografia fornecidas pelo cliente
Enviar notificações da nuvem usando o AmazonSimple Notification Service
O AWS SDK para .NET é compatível com o Amazon Simple Notification Service (Amazon SNS), um webservice que permite que aplicativos, usuários finais e dispositivos enviem instantaneamente notificações danuvem. Para obter mais informações, consulte Amazon SNS.
Listar os tópicos do Amazon SNSO exemplo a seguir mostra como listar os tópicos do Amazon SNS, as assinaturas de cada tópico e osatributos de cada tópico. Este exemplo usa o AmazonSimpleNotificationServiceClient padrão, que carregacredenciais da configuração padrão.
149
AWS SDK para .NET Guia do desenvolvedorEnviar uma mensagem para um tópico do Amazon SNS
// using Amazon.SimpleNotificationService;// using Amazon.SimpleNotificationService.Model;
var client = new AmazonSimpleNotificationServiceClient();var request = new ListTopicsRequest();var response = new ListTopicsResponse();
do{ response = client.ListTopics(request);
foreach (var topic in response.Topics) { Console.WriteLine("Topic: {0}", topic.TopicArn);
var subs = client.ListSubscriptionsByTopic( new ListSubscriptionsByTopicRequest { TopicArn = topic.TopicArn });
var ss = subs.Subscriptions;
if (ss.Any()) { Console.WriteLine(" Subscriptions:");
foreach (var sub in ss) { Console.WriteLine(" {0}", sub.SubscriptionArn); } }
var attrs = client.GetTopicAttributes( new GetTopicAttributesRequest { TopicArn = topic.TopicArn }).Attributes;
if (attrs.Any()) { Console.WriteLine(" Attributes:");
foreach (var attr in attrs) { Console.WriteLine(" {0} = {1}", attr.Key, attr.Value); } }
Console.WriteLine(); }
request.NextToken = response.NextToken;
} while (!string.IsNullOrEmpty(response.NextToken));
Enviar uma mensagem para um tópico do AmazonSNSO exemplo a seguir mostra como enviar uma mensagem para um tópico do Amazon SNS. O exemplo usaum argumento, o ARN do tópico do Amazon SNS.
150
AWS SDK para .NET Guia do desenvolvedorEnviar uma mensagem SMS para um número de telefone
using System;using System.Linq;using System.Threading.Tasks;
using Amazon;using Amazon.SimpleNotificationService;using Amazon.SimpleNotificationService.Model;
namespace SnsSendMessage{ class Program { static void Main(string[] args) { /* Topic ARNs must be in the correct format: * arn:aws:sns:REGION:ACCOUNT_ID:NAME * * where: * REGION is the region in which the topic is created, such as us-west-2 * ACCOUNT_ID is your (typically) 12-character account ID * NAME is the name of the topic */ string topicArn = args[0]; string message = "Hello at " + DateTime.Now.ToShortTimeString();
var client = new AmazonSimpleNotificationServiceClient(region: Amazon.RegionEndpoint.USWest2);
var request = new PublishRequest { Message = message, TopicArn = topicArn };
try { var response = client.Publish(request);
Console.WriteLine("Message sent to topic:"); Console.WriteLine(message); } catch (Exception ex) { Console.WriteLine("Caught exception publishing request:"); Console.WriteLine(ex.Message); } } }}
Consulte o exemplo completo, incluindo informações sobre como compilar e executar o exemplo na linhade comando, no GitHub.
Enviar uma mensagem SMS para um número detelefoneO exemplo a seguir mostra como enviar uma mensagem SMS para um número de telefone. O exemplousa um argumento, o número de telefone, que deve estar em um dos dois formatos descritos noscomentários.
using System;
151
AWS SDK para .NET Guia do desenvolvedorEnviar mensagens usando o Amazon SQS
using System.Linq;using System.Threading.Tasks;using Amazon;using Amazon.SimpleNotificationService;using Amazon.SimpleNotificationService.Model;
namespace SnsPublish{ class Program { static void Main(string[] args) { // US phone numbers must be in the correct format: // +1 (nnn) nnn-nnnn OR +1nnnnnnnnnn string number = args[0]; string message = "Hello at " + DateTime.Now.ToShortTimeString();
var client = new AmazonSimpleNotificationServiceClient(region: Amazon.RegionEndpoint.USWest2); var request = new PublishRequest { Message = message, PhoneNumber = number };
try { var response = client.Publish(request);
Console.WriteLine("Message sent to " + number + ":"); Console.WriteLine(message); } catch (Exception ex) { Console.WriteLine("Caught exception publishing request:"); Console.WriteLine(ex.Message); } } }}
Consulte o exemplo completo, incluindo informações sobre como compilar e executar o exemplo na linhade comando, no GitHub.
Enviar mensagens usando o Amazon SQSO AWS SDK para .NET oferece suporte ao Amazon SQS, um serviço de enfileiramento de mensagens quegerencia mensagens e fluxos de trabalho entre componentes de um sistema. Para obter mais informações,consulte Amazon SQS.
Os exemplos a seguir demonstram como usar o AWS SDK para .NET para criar e usar filas do AmazonSQS.
O código de exemplo é escrito em C#, mas é possível usar o AWS SDK para .NET com qualquerlinguagem compatível. O AWS SDK para .NET instala um conjunto de modelos de projeto C#.
Tarefas de pré-requisito
Para que você comece, é preciso ter criado uma conta da AWS e configurado suas credenciais da AWS.Para obter mais informações, consulte Configurar o AWS SDK para .NET (p. 14).
152
AWS SDK para .NET Guia do desenvolvedorCriação de um cliente do Amazon SQS
Para obter informações de referência relacionadas à API, consulte Amazon.SQS, Amazon.SQS.Model eAmazon.SQS.Util no AWS SDK for .NET API Reference.
Tópicos• Criação de um cliente do Amazon SQS (p. 153)• Criação de uma fila do Amazon SQS (p. 154)• Construção de URLs de fila do Amazon SQS (p. 154)• Envio de uma mensagem do Amazon SQS (p. 155)• Envio de um lote de mensagens do Amazon SQS (p. 155)• Recebendo uma mensagem de uma fila do Amazon SQS (p. 156)• Exclusão de uma mensagem de uma fila do Amazon SQS (p. 157)• Habilitar sondagem longa no Amazon SQS (p. 158)• Usando filas do Amazon SQS (p. 159)• Usar Amazon SQS fila de mensagens mortas (p. 160)
Criação de um cliente do Amazon SQSÉ necessário um cliente do Amazon SQS para criar e usar uma fila do Amazon SQS. Antes de configurar ocliente, crie um arquivo App.Config para especificar as suas credenciais da AWS.
Especifique as credenciais ao referenciar o perfil apropriado na seção appSettings do arquivo.
O exemplo a seguir especifica um perfil chamado my_profile. Para obter mais informações sobre ascredenciais e os perfis, consulte Configuração do aplicativo AWS SDK para .NET (p. 19).
<?xml version="1.0"?><configuration> <configSections> <section name="aws" type="Amazon.AWSSection, AWSSDK.Core"/> </configSections> <aws profileName="my_profile"/> <startup> <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.0"/> </startup></configuration>
Após a criação deste arquivo, você estará pronto para criar e inicializar o cliente do Amazon SQS.
Para criar e inicializar um cliente do Amazon SQS
1. Crie e inicialize uma instância do AmazonSQSConfig e, em seguida, configure a propriedadeServiceURL com o protocolo e o endpoint de serviço, conforme mostrado a seguir.
var sqsConfig = new AmazonSQSConfig();
sqsConfig.ServiceURL = "http://sqs.us-west-2.amazonaws.com";
2. Use a instância AmazonSQSConfig para criar e inicializar uma instância do AmazonSQSClient, daseguinte forma.
var sqsClient = new AmazonSQSClient(sqsConfig);
Agora é possível usar o cliente para criar uma fila do Amazon SQS. Para obter informações sobre acriação de uma fila, consulte Criação de uma fila do Amazon SQS (p. 154).
153
AWS SDK para .NET Guia do desenvolvedorCriação de uma fila do Amazon SQS
Criação de uma fila do Amazon SQSCriar uma fila do Amazon SQS é uma tarefa administrativa que pode ser feita ao usar o SQS ManagementConsole (Console de gerenciamento do SQS). Contudo, também é possível usar o AWS SDK para .NETpara criar programaticamente uma fila do Amazon SQS.
Para criar uma fila do Amazon SQS
1. Crie e inicialize uma instância de CreateQueueRequest. Forneça o nome da fila e especifique umtempo limite de visibilidade para suas mensagens de fila, da forma a seguir.
var createQueueRequest = new CreateQueueRequest();
createQueueRequest.QueueName = "MySQSQueue";var attrs = new Dictionary<string, string>();attrs.Add(QueueAttributeName.VisibilityTimeout, "10");createQueueRequest.Attributes = attrs;
O nome da fila deve ser composto somente de caracteres alfanuméricos, hifens e sublinhados.
Todas as mensagens da fila permanecem aí, a menos que o tempo limite de visibilidade especificadoseja excedido. O tempo limite de visibilidade padrão para uma fila é de 30 segundos. Para obtermais informações sobre tempos limite de visibilidade, consulte Visibility Timeout (Tempo limite devisibilidade). Para obter mais informações sobre os diferentes atributos de fila que você pode definir,consulte SetQueueAttributes.
2. Após criar a solicitação, transmita-a como um parâmetro para o método CreateQueue. O métodoretornará um objeto CreateQueueResponse, da seguinte forma;
var createQueueResponse = sqsClient.CreateQueue(createQueueRequest);
Para obter informações sobre como as filas funcionam no Amazon SQS, consulte How SQS Queues Work(Como as filas SQS funcionam).
Para obter informações sobre o URL da fila, consulte Construção de URLs de fila do AmazonSQS (p. 154).
Construção de URLs de fila do Amazon SQSVocê precisa de um URL de fila para enviar, receber e excluir mensagens da fila. Você pode obter o URLda fila usando o método GetQueueUrl.
Note
Para .NET Core, PCL e Unity, essa operação só está disponível na forma assíncrona usandoGetQueueUrlAsync.
var client = new AmazonSQSClient();var request = new GetQueueUrlRequest{ QueueName = "MyTestQueue", QueueOwnerAWSAccountId = "80398EXAMPLE"};var response = client.GetQueueUrl(request);Console.WriteLine("Queue URL: " + response.QueueUrl);
Para descobrir seu número de conta da AWS, visite Security Credentials (Credenciais de segurança). Seunúmero de conta está localizado em Account Number na parte superior direita da página.
154
AWS SDK para .NET Guia do desenvolvedorEnvio de uma mensagem do Amazon SQS
Para obter informações sobre o envio de uma mensagem para uma fila, consulte Envio de uma mensagemdo Amazon SQS (p. 155).
Para obter informações sobre o recebimento de mensagens de uma fila, consulte Recebimento de umamensagem de uma fila do Amazon SQS (p. 156).
Para obter informações sobre a exclusão de mensagens de uma fila, consulte Exclusão de umamensagem de uma fila do Amazon SQS (p. 157).
Envio de uma mensagem do Amazon SQSÉ possível usar o AWS SDK para .NET para enviar uma mensagem para uma fila do Amazon SQS.
Important
Devido à natureza distribuída da fila, o Amazon SQS não garante que as mensagens serãorecebidas na ordem exata de envio. Se for necessário manter a ordem de mensagens, use umafila FIFO do Amazon SQS. Para obter informações sobre filas FIFO, consulte Filas FIFO (First-In-First-Out, primeiro a entrar, primeiro a sair) do Amazon SQS.
Para enviar uma mensagem a uma fila do Amazon SQS
1. Crie e inicialize uma instância do SendMessageRequest. Especifique o nome da fila e a mensagemque deseja enviar, conforme mostrado a seguir.
sendMessageRequest.QueueUrl = myQueueURL; sendMessageRequest.MessageBody = "{YOUR_QUEUE_MESSAGE}";
Para obter mais informações sobre o URL da fila, consulte Construção de URLs de fila do AmazonSQS (p. 154).
Cada mensagem da fila deve ser composta somente por caracteres Unicode, com tamanho máximode 64 KB. Para obter mais informações sobre mensagens de fila, consulte SendMessage no AmazonSimple Queue Service API Reference.
2. Após criar a solicitação, transmita-a como um parâmetro para o método SendMessage. O métodoretorna um objeto SendMessageResponse, como mostrado a seguir.
var sendMessageResponse = sqsClient.SendMessage(sendMessageRequest);
A mensagem enviada permanecerá na fila até que o tempo limite de visibilidade seja excedido ouaté que ela seja excluída da fila. Para obter mais informações sobre os tempos limite de visibilidade,acesse Visibility Timeout (Tempo limite de visibilidade).
Para obter informações sobre a exclusão de mensagens de uma fila, consulte Exclusão de umamensagem de uma fila do Amazon SQS (p. 157).
Para obter informações sobre o recebimento de mensagens de uma fila, consulte Recebimento de umamensagem de uma fila do Amazon SQS (p. 156).
Envio de um lote de mensagens do Amazon SQSÉ possível usar o AWS SDK para .NET para enviar mensagens em lote a uma fila do Amazon SQS. Ométodo SendMessageBatch entrega até 10 mensagens à fila especificada. Esta é uma versão de lote doSendMessage.
Para uma fila FIFO, várias mensagens de um único lote são enfileiradas na ordem de envio.
155
AWS SDK para .NET Guia do desenvolvedorRecebendo uma mensagem de uma fila do Amazon SQS
Para obter mais informações sobre o envio de mensagens em lote, consulte SendMessageBatch noAmazon Simple Queue Service API Reference.
Para enviar mensagens em lote a uma fila do Amazon SQS
1. Crie uma instância do AmazonSQSClient e inicialize um objeto SendMessageBatchRequest.Especifique o nome da fila e a mensagem que deseja enviar, conforme mostrado a seguir.
AmazonSQSClient client = new AmazonSQSClient();var sendMessageBatchRequest = new SendMessageBatchRequest{ Entries = new List<SendMessageBatchRequestEntry> { new SendMessageBatchRequestEntry("message1", "FirstMessageContent"), new SendMessageBatchRequestEntry("message2", "SecondMessageContent"), new SendMessageBatchRequestEntry("message3", "ThirdMessageContent") }, QueueUrl = "SQS_QUEUE_URL"};
Para obter mais informações sobre o URL da fila, consulte Construção de URLs de fila do AmazonSQS (p. 154).
Cada mensagem da fila deve ser composta somente por caracteres Unicode, com tamanho máximode 64 KB. Para obter mais informações sobre mensagens de fila, consulte SendMessage no AmazonSimple Queue Service API Reference.
2. Após criar a solicitação, transmita-a como um parâmetro para o método SendMessageBatch. Ométodo retorna um objeto SendMessageBatchResponse, que contém o ID exclusivo de cadamensagem e o conteúdo de cada mensagem enviada com sucesso. Ele também retorna o ID e oconteúdo da mensagem além de um marcador de falha do remetente caso o envio da mensagemfalhe.
SendMessageBatchResponse response = client.SendMessageBatch(sendMessageBatchRequest);Console.WriteLine("Messages successfully sent:");foreach (var success in response.Successful){ Console.WriteLine(" Message id : {0}", success.MessageId); Console.WriteLine(" Message content MD5 : {0}", success.MD5OfMessageBody);}
Console.WriteLine("Messages failed to send:");foreach (var failed in response.Failed){ Console.WriteLine(" Message id : {0}", failed.Id); Console.WriteLine(" Message content : {0}", failed.Message); Console.WriteLine(" Sender's fault? : {0}", failed.SenderFault);}
Recebendo uma mensagem de uma fila do AmazonSQSÉ possível usar o AWS SDK para .NET para receber mensagens de uma fila do Amazon SQS.
Para receber uma mensagem de uma fila do Amazon SQS
1. Crie e inicialize uma instância do ReceiveMessageRequest. Especifique o URL da fila do qual receberuma mensagem, da seguinte forma.
156
AWS SDK para .NET Guia do desenvolvedorExclusão de uma mensagem de uma fila do Amazon SQS
var receiveMessageRequest = new ReceiveMessageRequest();
receiveMessageRequest.QueueUrl = myQueueURL;
Para obter mais informações sobre o URL da sua fila, consulte URL da fila do seu AmazonSQS (p. 154).
2. Transmita o objeto de solicitação como um parâmetro para o método ReceiveMessage, da seguinteforma.
var receiveMessageResponse = sqsClient.ReceiveMessage(receiveMessageRequest);
O método retorna uma instância de ReceiveMessageResponse, contendo a lista de mensagens que afila contém.
3. A propriedade ReceiveMessageResponse.ReceiveMessageResult contém um objetoReceiveMessageResponse, que contém uma lista de mensagens recebidas. Faça a iteração dessalista e chame o método ProcessMessage para processar cada mensagem.
foreach (var message in result.Messages){ ProcessMessage(message); // Go to a method to process messages.}
O método ProcessMessage pode usar a propriedade ReceiptHandle para obter um identificadorde recebimento para a mensagem. Você pode usar esse identificador de recebimento para alteraro tempo limite de visibilidade da mensagem ou para excluir a mensagem da fila. Para obtermais informações sobre como alterar o tempo limite de visibilidade de uma mensagem, consulteChangeMessageVisibility.
Para obter informações sobre o envio de uma mensagem para sua fila, consulte Envio de uma mensagemdo Amazon SQS (p. 155).
Para obter mais informações sobre a exclusão de uma mensagem da fila, consulte Exclusão da mensagemde uma fila do Amazon SQS (p. 157).
Exclusão de uma mensagem de uma fila do AmazonSQSÉ possível usar o AWS SDK para .NET para excluir mensagens de uma fila do Amazon SQS.
Para excluir uma mensagem de uma fila do Amazon SQS
1. Crie e inicialize um objeto DeleteMessageRequest. Especifique a fila do Amazon SQS da qual desejaexcluir uma mensagem e o identificador de recebimento da mensagem a ser excluída, como mostradoa seguir.
var deleteMessageRequest = new DeleteMessageRequest();
deleteMessageRequest.QueueUrl = queueUrl;deleteMessageRequest.ReceiptHandle = receiptHandle;
2. Transmita o objeto de solicitação como um parâmetro ao método DeleteMessage. O método retornaráum objeto DeleteMessageResponse, conforme se segue.
157
AWS SDK para .NET Guia do desenvolvedorHabilitar sondagem longa no Amazon SQS
var response = sqsClient.DeleteMessage(deleteMessageRequest);
Chamar o método DeleteMessage remove a mensagem da fila incondicionalmente, qualquer queseja a configuração do tempo limite de visibilidade. Para obter mais informações sobre tempos limitede visibilidade, consulte Visibility Timeout (Tempo limite de visibilidade).
Para obter informações sobre o envio de uma mensagem para uma fila, consulte Envio de uma mensagemdo Amazon SQS (p. 155).
Para obter informações sobre o recebimento de mensagens de uma fila, consulte Recebimento de umamensagem de uma fila do Amazon SQS (p. 156).
Habilitar sondagem longa no Amazon SQSA sondagem longa reduz o número de respostas vazias ao permitir que o Amazon SQS espere um tempoespecificado para que uma mensagem se torne disponível na fila antes de enviar uma resposta. Alémdisso, a sondagem longa elimina respostas vazias falsas ao consultar todos os servidores em vez deapenas uma amostragem de servidores. Para habilitar a sondagem longa, é necessário especificar umtempo de espera diferente de zero para mensagens recebidas. Faça isso configurando o parâmetroReceiveMessageWaitTimeSeconds de uma fila ou o parâmetro WaitTimeSeconds em umamensagem assim que ela for recebida. Este exemplo .NET mostra como habilitar a sondagem longa noAmazon SQS para uma fila recém-criada ou existente, ou após o recebimento de uma mensagem.
Estes exemplos usam os métodos a seguir da classe AmazonSQSClient para habilitar a sondagem longa:
• CreateQueue• SetQueueAttributes• ReceiveMessage
Para obter mais informações sobre a sondagem longa, consulte Sondagem longa do Amazon SQS noGuia do desenvolvedor do Amazon Simple Queue Service.
Habilitar a sondagem longa ao criar uma filaCrie um objeto de serviço do AmazonSQSClient. Crie um objeto CreateQueueRequest que contém aspropriedades necessárias para criar uma fila, incluindo um valor diferente de zero para a propriedadeReceiveMessageWaitTimeSeconds.
Chame o método CreateQueue. A sondagem longa será habilitada para a fila.
AmazonSQSClient client = new AmazonSQSClient();var request = new CreateQueueRequest{ QueueName = "SQS_QUEUE_NAME", Attributes = new Dictionary<string, string> { { "ReceiveMessageWaitTimeSeconds", "20"} }};var response = client.CreateQueue(request);Console.WriteLine("Created a queue with URL : {0}", response.QueueUrl);
158
AWS SDK para .NET Guia do desenvolvedorUsando filas do Amazon SQS
Habilitar a sondagem longa em uma fila existenteCrie um objeto de serviço do AmazonSQSClient. Crie um objeto SetQueueAttributesRequest que contémas propriedades necessárias para definir os atributos da fila, incluindo um valor diferente de zero para apropriedade ReceiveMessageWaitTimeSeconds e o URL da fila. Chame o método SetQueueAttributes.A sondagem longa será habilitada para a fila.
AmazonSQSClient client = new AmazonSQSClient();
var request = new SetQueueAttributesRequest{ Attributes = new Dictionary<string, string> { { "ReceiveMessageWaitTimeSeconds", "20"} }, QueueUrl = "SQS_QUEUE_URL"};
var response = client.SetQueueAttributes(request);
Receber uma mensagemCrie um objeto de serviço do AmazonSQSClient. Crie um objeto ReceiveMessageRequest que contémas propriedades necessárias para receber uma mensagem, incluindo um valor diferente de zero para oparâmetro WaitTimeSeconds e o URL da fila. Chame o método ReceiveMessage.
public void OnMessageReceipt(){ AmazonSQSClient client = new AmazonSQSClient();
var request = new ReceiveMessageRequest { AttributeNames = { "SentTimestamp" }, MaxNumberOfMessages = 1, MessageAttributeNames = { "All" }, QueueUrl = "SQS_QUEUE_URL", WaitTimeSeconds = 20 };
var response = client.ReceiveMessage(request);}
Usando filas do Amazon SQSO Amazon SQS oferece padrão como o tipo de fila padrão. Uma fila padrão permite que você tenhaum número quase ilimitado de transações por segundo. As filas padrão oferecem suporte à entrega demensagens pelo menos uma vez. No entanto, ocasionalmente, mais de uma cópia de uma mensagempode ser entregue fora de ordem. As filas standard oferecem a melhor ordenação possível, o que garantea entrega das mensagens na mesma ordem em que foram enviadas.
Use as filas de mensagens padrão em diversos cenários, contanto que o aplicativo possa processar asmensagens que chegam mais de uma vez e fora de ordem.
Este exemplo de código demonstra como usar as filas com estes métodos da classe AmazonSQSClient:
• ListQueues: obtém uma lista das filas de mensagens• GetQueueUrl: obtém o URL de uma fila específica• DeleteQueue: exclui uma fila
159
AWS SDK para .NET Guia do desenvolvedorUsar Amazon SQS fila de mensagens mortas
Para obter mais informações sobre mensagens do Amazon SQS, consulte Como as filas do Amazon SQSfuncionam no Guia do desenvolvedor do Amazon Simple Queue Service.
Listar as filasCrie um objeto ListQueuesRequest que contém as propriedades necessárias para listar as filas, que é umobjeto vazio por padrão. Chame o método ListQueues com o ListQueuesRequest como um parâmetropara recuperar a lista de filas. O objeto ListQueuesResponse retornado pela chamada contém os URLs detodas as filas.
AmazonSQSClient client = new AmazonSQSClient();
ListQueuesResponse response = client.ListQueues(new ListQueuesRequest());foreach (var queueUrl in response.QueueUrls){ Console.WriteLine(queueUrl);}
Obter o URL de uma filaCrie um objeto GetQueueUrlRequest que contém as propriedades necessárias para identificar a sua fila,que deve incluir o nome da fila para a qual deseja obter o URL. Chame o método GetQueueUrl usando oobjeto GetQueueUrlRequest como um parâmetro. A chamada retorna um objeto GetQueueUrlResponseque contém o URL da fila especificada.
AmazonSQSClient client = new AmazonSQSClient();
var request = new GetQueueUrlRequest{ QueueName = "SQS_QUEUE_NAME"};
GetQueueUrlResponse response = client.GetQueueUrl(request);Console.WriteLine("The SQS queue's URL is {1}", response.QueueUrl);
Excluir uma filaCrie um objeto DeleteQueueRequest que contém o URL da fila que deseja excluir. Chame o métodoDeleteQueue com o objeto DeleteQueueRequest como parâmetro.
AmazonSQSClient client = new AmazonSQSClient();
var request = new DeleteQueueRequest{ QueueUrl = "SQS_QUEUE_URL"};
client.DeleteQueue(request);
Usar Amazon SQS fila de mensagens mortasEste exemplo mostra como usar uma fila para receber e guardar mensagens de outras filas que as filasnão consigam processar.
Uma fila de mensagens mortas é aquela fila para a qual outras filas (de origem) podem direcionarmensagens que não podem ser processadas com êxito. Você pode separar e isolar essas mensagens
160
AWS SDK para .NET Guia do desenvolvedorMonitoramento de seus recursos daAWS usando o Amazon CloudWatch
na dead letter queue para determinar por que o processamento não teve sucesso. Você deve configurarindividualmente cada fila de origem que envia mensagens para uma dead letter queue. Várias filas podemvisar uma única dead letter queue.
Neste exemplo, o objeto AmazonSQSClient usa o método SetQueueAttributesRequest para configuraruma fila de origem para usar uma fila de mensagens mortas.
Para obter mais informações sobre as filas de mensagens mortas do Amazon SQS, consulte Usar filas demensagens mortas do Amazon SQS no Guia do desenvolvedor do Amazon Simple Queue Service.
Configurar uma fila de origemEste exemplo de código pressupõe que você tenha criado uma fila para atuar como dead letter queue.Consulte Criar uma fila do Amazon SQS (p. 154) para obter informações sobre a criação de uma fila.Após ter criado a dead letter queue, você deverá configurar outras filas para rotear mensagens nãoprocessadas para a dead letter queue. Para isso, especifique a política de redrive que identifica a fila aser usada como dead letter queue e o número máximo que recebe por mensagens individuais antes deroteada para a dead letter queue.
Crie um objeto AmazonSQSClient para configurar os atributos da fila. Crie um objetoSetQueueAttributesRequest contendo as propriedades necessárias para atualizar os atributos da fila,inclusive a propriedade RedrivePolicy, que especifica o nome de recurso da Amazon e a dead letterqueue, além do valor de maxReceiveCount. Especifique também a fila de origem do URL que vocêdeseja configurar. Chame o método SetQueueAttributes.
AmazonSQSClient client = new AmazonSQSClient();
var setQueueAttributeRequest = new SetQueueAttributesRequest{ Attributes = new Dictionary<string, string> { {"RedrivePolicy", @"{ ""deadLetterTargetArn"" : ""DEAD_LETTER_QUEUE_ARN"", ""maxReceiveCount"" : ""10""}" } }, QueueUrl = "SOURCE_QUEUE_URL"};
client.SetQueueAttributes(setQueueAttributeRequest)
Monitoramento de seus recursos da AWS usando oAmazon CloudWatch
O Amazon CloudWatch é um serviço web que monitora seus recursos da AWS e os aplicativos que vocêexecuta na AWS em tempo real. É possível usar o CloudWatch para coletar e monitorar métricas, que sãoas variáveis que podem ser medidas para avaliar seus recursos e aplicativos. Os alarmes do CloudWatchenviam notificações ou fazem alterações automaticamente nos recursos que você está monitorando combase nas regras definidas.
O código desses exemplos é escrito em C#, mas você pode usar o AWS SDK para .NET com qualquerlinguagem compatível. Quando você instala o AWS Toolkit for Visual Studio, é instalada uma série demodelos de projetos C#. A forma mais simples para iniciar esse projeto é abrir o Visual Studio e selecionarArquivo, Novo Projeto, Projetos de exemplo da AWS, Implantação e Gerenciamento, Exemplo do AWSCloudWatch.
Tarefas de pré-requisito
161
AWS SDK para .NET Guia do desenvolvedorDescrição, criação e exclusão dealarmes no Amazon CloudWatch
Para que você comece, é preciso ter criado uma conta da AWS e configurado suas credenciais da AWS.Para obter mais informações, consulte Configurar o AWS SDK para .NET (p. 14).
Tópicos• Descrição, criação e exclusão de alarmes no Amazon CloudWatch (p. 162)• Uso de alarmes no Amazon CloudWatch (p. 164)• Obtenção de métricas do Amazon CloudWatch (p. 165)• Envio de eventos para Amazon CloudWatch Events (p. 167)• Uso de filtros de assinatura no Amazon CloudWatch Logs (p. 170)
Descrição, criação e exclusão de alarmes no AmazonCloudWatchEste exemplo de .NET mostra como:
• Descrever um alarme do CloudWatch• Criar um alarme do CloudWatch com base em uma métrica• Excluir um alarme do CloudWatch
O cenárioO alarme observa uma única métrica em um período especificado. Ele executa uma ou mais ações combase no valor da métrica, relativa a um limite especificado em um número de períodos. Os exemplos aseguir mostram como descrever, criar e excluir alarmes no CloudWatch usando esses métodos da classeAmazonCloudWatchClient:
• DescribeAlarms• PutMetricAlarm• DeleteAlarms
Para obter mais informações sobre alarmes do CloudWatch, consulte Criar alarmes do AmazonCloudWatch no Guia do usuário do Amazon CloudWatch.
Tarefas de pré-requisitoPara configurar e executar este exemplo, você deve primeiro:
• Get set up to use Amazon CloudWatch (Configurar para usar o Amazon CloudWatch).• Definir configurar o AWS SDK para .NET. (p. 14)
Descrição de um alarmeCrie uma instância de AmazonCloudWatchClient e um objeto DescribeAlarmsRequest, limitando osalarmes retornados àquelas com estado de INSUFFICIENT_DATA. Em seguida, chame o método deDescribeAlarms do objeto AmazonCloudWatchClient.
using (var cloudWatch = new AmazonCloudWatchClient(RegionEndpoint.USWest2)){ var request = new DescribeAlarmsRequest(); request.StateValue = "INSUFFICIENT_DATA";
162
AWS SDK para .NET Guia do desenvolvedorDescrição, criação e exclusão dealarmes no Amazon CloudWatch
request.AlarmNames = new List<string> { "Alarm1", "Alarm2" }; do { var response = cloudWatch.DescribeAlarms(request); foreach(var alarm in response.MetricAlarms) { Console.WriteLine(alarm.AlarmName); } request.NextToken = response.NextToken; } while (request.NextToken != null);}
Criação de um alarme baseado em uma métricaCrie uma instância de AmazonCloudWatchClient e um objeto PutMetricAlarmRequest para os parâmetrosnecessários para criar um alarme baseado em uma métrica. Nesse caso, a utilização de CPU de umainstância do Amazon EC2.
Os demais parâmetros são definidos para acionar o alarme quando a métrica exceder o limite de 70%.
Em seguida, chame o método PutMetricAlarm do objeto AmazonCloudWatchClient.
var client = new AmazonCloudWatchClient(RegionEndpoint.USWest2);client.PutMetricAlarm( new PutMetricAlarmRequest { AlarmName = "Web_Server_CPU_Utilization", ComparisonOperator = ComparisonOperator.GreaterThanThreshold, EvaluationPeriods = 1, MetricName = "CPUUtilization", Namespace = "AWS/EC2", Period = 60, Statistic = Statistic.Average, Threshold = 70.0, ActionsEnabled = true, AlarmActions = new List<string> { "arn:aws:swf:us-west-2:" + "customerAccount" + ":action/actions/AWS_EC2.InstanceId.Reboot/1.0" }, AlarmDescription = "Alarm when server CPU exceeds 70%", Dimensions = new List<Dimension> { new Dimension { Name = "InstanceId", Value = "INSTANCE_ID" } }, Unit = StandardUnit.Seconds });
Exclusão de um alarmeCrie uma instância do AmazonCloudWatchClient e um objeto DeleteAlarmsRequest para guardaros nomes dos alarmes que deseja excluir. Em seguida, chame o método DeleteAlarms do objetoAmazonCloudWatchClient.
using (var cloudWatch = new AmazonCloudWatchClient(RegionEndpoint.USWest2)){ var response = cloudWatch.DeleteAlarms( new DeleteAlarmsRequest { AlarmNames = new List<string> { "Alarm1", "Alarm2" }; });}
163
AWS SDK para .NET Guia do desenvolvedorUso de alarmes no Amazon CloudWatch
Uso de alarmes no Amazon CloudWatchEste exemplo .NET mostra como alterar automaticamente o estado das instâncias do Amazon EC2 combase em um alarme do CloudWatch.
O cenárioAo usar ações de alarme, é possível criar alarmes que param, encerram, reiniciam ou recuperam asinstâncias do Amazon EC2 automaticamente. Use as ações parar ou encerrar quando não for maisnecessário que uma instância seja executada. Use as ações reiniciar e recuperar para reiniciar essasinstâncias automaticamente.
Neste exemplo, o .NET é usado para definir uma ação de alarme no CloudWatch que acionaráa reinicialização de uma instância do Amazon EC2. Os métodos utilizam o AWS SDK para .NETpara gerenciar as instâncias do Amazon EC2, usando os seguintes métodos da classeAmazonCloudWatchClient:
• PutMetricAlarm• EnableAlarmActions• DisableAlarmActions
Para obter mais informações sobre as ações de alarme do CloudWatch, consulte Criar alarmes para parar,encerrar, reinicializar ou recuperar uma instância no Guia do usuário do Amazon CloudWatch.
Tarefas de pré-requisitoPara configurar e executar este exemplo, você deve primeiro:
• Get set up to use Amazon CloudWatch (Configurar para usar o Amazon CloudWatch).• Definir configurar o AWS SDK para .NET. (p. 14)
Criar e ativar ações em um alarme1. Crie uma instância do AmazonCloudWatchClient e um objeto PutMetricAlarmRequest para manter
os parâmetros da criação de um alarme especificando ActionsEnabled como verdadeiro e umamatriz de ARNs para as ações que o alarme acionará. Chame o método PutMetricAlarm do objetoAmazonCloudWatchClient. Isso criará o alarme caso não ele exista ou o atualizará caso já exista.
using (var client = new AmazonCloudWatchClient(RegionEndpoint.USWest2)){ client.PutMetricAlarm(new PutMetricAlarmRequest { AlarmName = "Web_Server_CPU_Utilization", ComparisonOperator = ComparisonOperator.GreaterThanThreshold, EvaluationPeriods = 1, MetricName = "CPUUtilization", Namespace = "AWS/EC2", Period = 60, Statistic = Statistic.Average, Threshold = 70.0, ActionsEnabled = true, AlarmActions = new List<string> { "arn:aws:swf:us-west-2:" + "customerAccount" + ":action/actions/AWS_EC2.InstanceId.Reboot/1.0" }, AlarmDescription = "Alarm when server CPU exceeds 70%", Dimensions = new List<Dimension> { new Dimension { Name = "InstanceId", Value = "instanceId" }
164
AWS SDK para .NET Guia do desenvolvedorObtenção de métricas do Amazon CloudWatch
} });}
2. Quando o método PutMetricAlarm concluir com sucesso, crie um objeto EnableAlarmActionsRequestque contém o nome do alarme do CloudWatch. Chame o método EnableAlarmActions para ativar aação do alarme.
client.EnableAlarmActions(new EnableAlarmActionsRequest{ AlarmNames = new List<string> { "Web_Server_CPU_Utilization" }});
3. Crie um objeto MetricDatum que contém a métrica personalizada CPUUtilization. Crie um objetoPutMetricDataRequest que contém o parâmetro MetricData necessário para enviar um ponto dedados para a métrica CPUUtilization. Chame o método PutMetricData.
MetricDatum metricDatum = new MetricDatum{ MetricName = "CPUUtilization" };PutMetricDataRequest putMetricDatarequest = new PutMetricDataRequest{ MetricData = new List<MetricDatum> { metricDatum }};client.PutMetricData(putMetricDatarequest);
Desativar ações de um alarmeCrie uma instância do AmazonCloudWatchClient e um objeto DisableAlarmActionsRequest que contém onome do alarme do CloudWatch. Chame o método DisableAlarmActions para desativar as ações dessealarme.
using (var client = new AmazonCloudWatchClient(RegionEndpoint.USWest2)){ client.DisableAlarmActions(new DisableAlarmActionsRequest { AlarmNames = new List<string> { "Web_Server_CPU_Utilization" } });}
Obtenção de métricas do Amazon CloudWatchEste exemplo mostra como:
• Recuperar uma lista de métricas do CloudWatch• Publicar métricas personalizadas do CloudWatch
O cenárioMétricas são dados sobre o desempenho de seus sistemas. É possível habilitar o monitoramentodetalhado de alguns recursos, como instâncias do Amazon EC2 ou suas próprias métricas deaplicativos. Neste exemplo, use o .NET para recuperar uma lista de métricas do CloudWatch publicadase para publicar pontos de dados nas métricas do CloudWatch usando estes métodos da classeAmazonCloudWatchClient:
• ListMetrics• PutMetricData
165
AWS SDK para .NET Guia do desenvolvedorObtenção de métricas do Amazon CloudWatch
Para obter mais informações sobre as métricas do CloudWatch, consulte Usar as métricas do AmazonCloudWatch no Guia do usuário do Amazon CloudWatch.
Tarefas de pré-requisitoPara configurar e executar este exemplo, você deve primeiro:
• Get set up to use Amazon CloudWatch (Configurar para usar o Amazon CloudWatch).• Definir configurar o AWS SDK para .NET. (p. 14)
Listar as métricasCrie um objeto ListMetricsRequest que contém os parâmetros necessários para listar as métricas dentro donamespace AWS/Logs. Chame o método ListMetrics de uma instância do AmazonCloudWatchClient paralistar a métrica IncomingLogEvents.
var logGroupName = "LogGroupName";DimensionFilter dimensionFilter = new DimensionFilter(){ Name = logGroupName};var dimensionFilterList = new List<DimensionFilter>();dimensionFilterList.Add(dimensionFilter);
var dimension = new Dimension{ Name = "UniquePages", Value = "URLs"};using (var cw = new AmazonCloudWatchClient(RegionEndpoint.USWest2)){ var listMetricsResponse = cw.ListMetrics(new ListMetricsRequest { Dimensions = dimensionFilterList, MetricName = "IncomingLogEvents", Namespace = "AWS/Logs" }); Console.WriteLine(listMetricsResponse.Metrics);}
Enviar métricas personalizadasCrie um objeto PutMetricDataRequest que contém os parâmetros necessários para enviar um ponto dedados para a métrica personalizada PAGES_VISITED. Chame o método PutMetricData da instânciaAmazonCloudWatchClient.
using (var cw = new AmazonCloudWatchClient(RegionEndpoint.USWest2)){ cw.PutMetricData(new PutMetricDataRequest { MetricData = new List<MetricDatum>{new MetricDatum { MetricName = "PagesVisited", Dimensions = new List<Dimension>{dimension}, Unit = "None", Value = 1.0 }}, Namespace = "SITE/TRAFFIC" });
166
AWS SDK para .NET Guia do desenvolvedorEnvio de eventos para Amazon CloudWatch Events
}
Envio de eventos para Amazon CloudWatch EventsEste exemplo de código .NET mostra como:
• Criar e atualizar uma regra programada para acionar um evento• Adicionar um destino da função do AWS Lambda para responder a um evento• Enviar eventos correspondentes aos destinos
O cenárioO Eventos do Amazon CloudWatch entrega um fluxo quase em tempo real dos eventos do sistemaque descrevem alterações nos recursos da AWS aos vários destinos. Com regras simples, é possívelcorresponder eventos e roteá-los para um ou mais fluxos ou funções de destino. Este exemplo de .NETmostra a você como criar e atualizar uma regra usada para acionar um evento, definir um ou mais destinospara responder a um evento e enviar eventos correspondentes aos destinos para manipulação.
O código gerencia as instâncias usando esses métodos da classe AmazonCloudWatchEventsClient:
• PutRule• PutTargets• PutEvents
Para obter mais informações sobre o Eventos do Amazon CloudWatch, consulte Adicionar eventos comPutEvents no Guia do usuário do Eventos do Amazon CloudWatch.
Tarefas de pré-requisitoPara configurar e executar este exemplo, você deve primeiro:
• Get set up to use Amazon CloudWatch (Configurar para usar o Amazon CloudWatch).• Definir configurar o AWS SDK para .NET. (p. 14)• Crie uma função Lambda usando o modelo hello-world para servir como destino para eventos. Para
saber como, consulte Etapa 1: Criar uma função do AWS Lambda no Guia do usuário do Eventos doAmazon CloudWatch.
Criar uma função do IAM para executar exemplosOs exemplos a seguir exigem uma função do IAM cuja política conceda permissão para o CloudWatchEvents e inclua events.amazonaws.com como entidade confiável. Este exemplo cria uma função denome CWEvents, definindo o relacionamento de confiança e a política de funções.
static void Main(){ var client = new AmazonIdentityManagementServiceClient(); // Create a role and it's trust relationship policy var role = client.CreateRole(new CreateRoleRequest { RoleName = "CWEvents", AssumeRolePolicyDocument = @"{""Statement"":[{""Principal"":{""Service"":[""events.amazonaws.com""]}," + @"""Effect"":""Allow"",""Action"":[""sts:AssumeRole""]}]}" }).Role;
167
AWS SDK para .NET Guia do desenvolvedorEnvio de eventos para Amazon CloudWatch Events
// Create a role policy and add it to the role string policy = GenerateRolePolicyDocument(); var request = new CreatePolicyRequest { PolicyName = "DemoCWPermissions", PolicyDocument = policy }; try { var createPolicyResponse = client.CreatePolicy(request); } catch (EntityAlreadyExistsException) { Console.WriteLine ("Policy 'DemoCWPermissions' already exits."); } var request2 = new AttachRolePolicyRequest() { PolicyArn = "arn:aws:iam::192484417122:policy/DemoCWPermissions", RoleName = "CWEvents" }; try { var response = client.AttachRolePolicy(request2); //managedpolicy Console.WriteLine("Policy DemoCWPermissions attached to Role TestUser"); } catch (NoSuchEntityException) { Console.WriteLine ("Policy 'DemoCWPermissions' does not exist"); } catch (InvalidInputException) { Console.WriteLine ("One of the parameters is incorrect"); }
}public static string GenerateRolePolicyDocument(){ /* This method produces the following managed policy: "Version": "2012-10-17", "Statement": [ { "Sid": "CloudWatchEventsFullAccess", "Effect": "Allow", "Action": "events:*", "Resource": "*" }, { "Sid": "IAMPassRoleForCloudWatchEvents", "Effect": "Allow", "Action": "iam:PassRole", "Resource": "arn:aws:iam::*:role/AWS_Events_Invoke_Targets" } ] } */ var actionList = new ActionIdentifier("events:*"); var actions = new List<ActionIdentifier>(); actions.Add(actionList); var resource = new Resource("*"); var resources = new List<Resource>(); resources.Add(resource); var statement = new Amazon.Auth.AccessControlPolicy.Statement (Amazon.Auth.AccessControlPolicy.Statement.StatementEffect.Allow)
168
AWS SDK para .NET Guia do desenvolvedorEnvio de eventos para Amazon CloudWatch Events
{ Actions = actions, Id = "CloudWatchEventsFullAccess", Resources = resources }; var statements = new List<Amazon.Auth.AccessControlPolicy.Statement>(); statements.Add(statement); var actionList2 = new ActionIdentifier("iam:PassRole"); var actions2 = new List<ActionIdentifier>(); actions2.Add(actionList2); var resource2 = new Resource("arn:aws:iam::*:role/AWS_Events_Invoke_Targets"); var resources2 = new List<Resource>(); resources2.Add(resource2); var statement2 = new Amazon.Auth.AccessControlPolicy.Statement(Amazon.Auth.AccessControlPolicy.Statement.StatementEffect.Allow) { Actions = actions2, Id = "IAMPassRoleForCloudWatchEvents", Resources = resources2 };
statements.Add(statement2); var policy = new Policy { Id = "DemoEC2Permissions", Version = "2012-10-17", Statements = statements }; return policy.ToJson();}
Criar uma regra programadaCrie uma instância AmazonCloudWatchEventsClient e um objeto PutRuleRequest contendo os parâmetrosnecessários para especificar a nova regra programada, que inclui o seguinte:
• Um nome para a regra• O ARN da função do IAM que você criou anteriormente• Uma expressão para programar o acionamento da regra a cada cinco minutos
Chame o método PutRule para criar a regra. O objeto PutRuleResponse retorna o ARN da regra nova ouatualizada.
AmazonCloudWatchEventsClient client = new AmazonCloudWatchEventsClient();
var putRuleRequest = new PutRuleRequest{ Name = "DEMO_EVENT", RoleArn = "IAM_ROLE_ARN", ScheduleExpression = "rate(5 minutes)", State = RuleState.ENABLED};
var putRuleResponse = client.PutRule(putRuleRequest);Console.WriteLine("Successfully set the rule {0}", putRuleResponse.RuleArn);
Adicionar o destino da função LambdaCrie uma instância AmazonCloudWatchEventsClient e um objeto PutTargetsRequest contendoos parâmetros necessários para especificar a regra à qual você deseja anexar o destino,
169
AWS SDK para .NET Guia do desenvolvedorUso de filtros de assinatura no Amazon CloudWatch Logs
incluindo o ARN da função do Lambda que você criou. Chame o método PutTargets da instânciaAmazonCloudWatchClient.
AmazonCloudWatchEventsClient client = new AmazonCloudWatchEventsClient();
var putTargetRequest = new PutTargetsRequest{ Rule = "DEMO_EVENT", Targets = { new Target { Arn = "LAMBDA_FUNCTION_ARN", Id = "myCloudWatchEventsTarget"} }};client.PutTargets(putTargetRequest);
Enviar eventosCrie uma instância AmazonCloudWatchEventsClient e um objeto PutEventsRequest contendo osparâmetros necessários para enviar eventos. Para cada caso, inclua a fonte do evento, os ARNs de todosos recursos afetados pelo evento e os detalhes do evento. Chame o método PutEvents da instânciaAmazonCloudWatchClient.
AmazonCloudWatchEventsClient client = new AmazonCloudWatchEventsClient();
var putEventsRequest = new PutEventsRequest{ Entries = new List<PutEventsRequestEntry> { new PutEventsRequestEntry { Detail = @"{ ""key1"" : ""value1"", ""key2"" : ""value2"" }", DetailType = "appRequestSubmitted", Resources = { "RESOURCE_ARN" }, Source = "com.compnay.myapp" } }};client.PutEvents(putEventsRequest);
Uso de filtros de assinatura no Amazon CloudWatchLogsEsses exemplos .NET mostram a você como:
• Listar filtros de assinatura existentes no CloudWatch Logs• Criar um filtro de assinatura no CloudWatch Logs• Excluir um filtro de assinatura do CloudWatch Logs
O cenárioAs assinaturas dão acesso a um feed em tempo real de eventos de log do CloudWatch Logs e entregaesse feed a outros serviços, como um stream do Amazon Kinesis Data Streams ou AWS Lambda paraprocessamento personalizado, análise ou carregamento para outros sistemas. Um filtro de assinatura
170
AWS SDK para .NET Guia do desenvolvedorUso de filtros de assinatura no Amazon CloudWatch Logs
define o padrão a ser usado para filtrar quais eventos de log são entregues ao seu recurso da AWS. Esteexemplo como listar, criar e excluir um filtro de assinatura no CloudWatch Logs. O destino para os eventosdo log é uma função do Lambda.
Este exemplo usa o AWS SDK para .NET para gerenciar filtros de assinatura usando esses métodos daclasse AmazonCloudWatchLogsClient:
• DescribeSubscriptionFilters• PutSubscriptionFilter• DeleteSubscriptionFilter
Para obter mais informações sobre as assinaturas do CloudWatch Logs, consulte Processamento emtempo real dos dados de log com assinaturas no Amazon CloudWatch Logs User Guide.
Tarefas de pré-requisitoPara configurar e executar este exemplo, você deve primeiro:
• Get set up to use Amazon CloudWatch (Configurar para usar o Amazon CloudWatch).• Definir configurar o AWS SDK para .NET. (p. 14)
Descreva os filtros de assinatura existentesCrie um objeto AmazonCloudWatchLogsClient. Crie um objeto DescribeSubscriptionFiltersRequestcontendo os parâmetros necessários para descrever os filtros existentes. Inclua o nome do grupo de log eo número máximo de filtros que você deseja descrever. Chame o método DescribeSubscriptionFilters.
public static void DescribeSubscriptionFilters(){ var client = new AmazonCloudWatchLogsClient(); var request = new Amazon.CloudWatchLogs.Model.DescribeSubscriptionFiltersRequest() { LogGroupName = "GROUP_NAME", Limit = 5 }; try { var response = client.DescribeSubscriptionFilters(request); } catch (Amazon.CloudWatchLogs.Model.ResourceNotFoundException e) { Console.WriteLine(e.Message); } finally { client?.Dispose(); }}
Criar um filtro de assinaturaCrie um objeto AmazonCloudWatchLogsClient. Crie um objeto PutSubscriptionFilterRequest contendo osparâmetros necessários para criar um filtro, incluindo o ARN da função Lambda de destino, o nome defiltro, padrão de strings para filtrar e o nome do grupo de log. Chame o método PutSubscriptionFilter.
public static void PutSubscriptionFilters()
171
AWS SDK para .NET Guia do desenvolvedorProgramar o AWS OpsWorks paratrabalhar com pilhas e aplicativos
{ var client = new AmazonCloudWatchLogsClient(); var request = new Amazon.CloudWatchLogs.Model.PutSubscriptionFilterRequest() { DestinationArn = "LAMBDA_FUNCTION_ARN", FilterName = "FILTER_NAME", FilterPattern = "ERROR", LogGroupName = "Log_Group" }; try { var response = client.PutSubscriptionFilter(request); } catch (InvalidParameterException e) { Console.WriteLine(e.Message); } finally { client?.Dispose(); }}
Excluir um filtro de assinaturaCrie um objeto AmazonCloudWatchLogsClient. Crie um objeto DeleteSubscriptionFilterRequest contendoos parâmetros necessários para excluir um filtro, incluindo os nomes do filtro e o grupo de log. Chame ométodo DeleteSubscriptionFilter.
public static void DeleteSubscriptionFilter(){ var client = new AmazonCloudWatchLogsClient(); var request = new Amazon.CloudWatchLogs.Model.DeleteSubscriptionFilterRequest() { LogGroupName = "GROUP_NAME", FilterName = "FILTER" }; try { var response = client.DeleteSubscriptionFilter(request); } catch (Amazon.CloudWatchLogs.Model.ResourceNotFoundException e) { Console.WriteLine(e.Message); } finally { client?.Dispose(); }}
Programar o AWS OpsWorks para trabalhar compilhas e aplicativos
O AWS SDK para .NET oferece suporte ao AWS OpsWorks, o que oferece uma forma simples e flexívelpara criar e gerenciar pilhas e aplicativos. Com o AWS OpsWorks, é possível provisionar recursosda AWS, gerenciar as suas configurações, implantar aplicativos para esses recursos e monitorar aintegridade. Para obter mais informações, consulte OpsWorks.
172
AWS SDK para .NET Guia do desenvolvedorProgramar suporte para serviços da AWS adicionais
O SDK fornece APIs para programação com o AWS OpsWorks. Normalmente, essas APIs consistem emconjuntos de objetos correspondentes de solicitação e resposta que correspondem a chamadas da APIbaseadas em HTTP, com foco nos conceitos de nível de serviço correspondentes.
Para obter informações de referência de API relacionadas, consulte Amazon.OpsWorks eAmazon.OpsWorks.Model no AWS SDK for .NET API Reference.
Programar suporte para serviços da AWSadicionais
O AWS SDK para .NET oferece suporte à programação de serviços da AWS, além dos descritos nosexemplos de código. Para obter informações sobre programação de serviços específicos com o AWS SDKpara .NET, consulte AWS SDK for .NET API Reference.
Além dos namespaces para serviços individuais da AWS, o AWS SDK para .NET também fornece asseguintes APIs:
Área Descrição Recursos
AWS Support Acesso programático a casosda AWS Support e recursos doTrusted Advisor.
Consulte Amazon.AWSSupport eAmazon.AWSSupport.Model.
Geral Classes auxiliares eenumerações.
Consulte Amazon e Amazon.Util.
Outras informações de programação gerais para o AWS SDK para .NET incluem o seguinte:
• Substituição de endpoints do AWS SDK para .NET• Ciclos de vida do objeto .NET
173
AWS SDK para .NET Guia do desenvolvedorProteção de dados
Segurança do this AWS Product orService
Cloud security at Amazon Web Services (AWS) is the highest priority. As an AWS customer, youbenefit from a data center and network architecture that is built to meet the requirements of the mostsecurity-sensitive organizations. Security is a shared responsibility between AWS and you. The SharedResponsibility Model describes this as Security of the Cloud and Security in the Cloud.
Security of the Cloud – AWS is responsible for protecting the infrastructure that runs all of the servicesoffered in the AWS Cloud and providing you with services that you can use securely. Our securityresponsibility is the highest priority at AWS, and the effectiveness of our security is regularly tested andverified by third-party auditors as part of the AWS Compliance Programs.
Security in the Cloud – Your responsibility is determined by the AWS service you are using, and otherfactors including the sensitivity of your data, your organization’s requirements, and applicable laws andregulations.
This AWS product or service follows the shared responsibility model through the specific Amazon WebServices (AWS) services it supports. For AWS service security information, see the AWS service securitydocumentation page and AWS services that are in scope of AWS compliance efforts by complianceprogram.
Tópicos• Proteção de dados no this AWS Product or Service (p. 174)• Identity and Access Management for this AWS Product or Service (p. 175)• Compliance Validation for this AWS Product or Service (p. 175)• Resilience for this AWS Product or Service (p. 176)• Infrastructure Security for this AWS Product or Service (p. 176)• Impor o TLS 1.2 em this AWS Product or Service (p. 177)
Proteção de dados no this AWS Product or ServiceO This AWS product or service está em conformidade com o modelo de responsabilidade compartilhada,que inclui regulamentos e diretrizes de proteção de dados. A Amazon Web Services (AWS) é responsávelpor proteger a infraestrutura global que executa todos os serviços da AWS. A AWS mantém controle dosdados hospedados nessa infraestrutura, incluindo os controles de configuração de segurança para lidarcom o conteúdo e com os dados pessoais do cliente. Os clientes da AWS e os parceiros do APN, atuandocomo controladores ou processadores de dados, são responsáveis por todos os dados pessoais quecolocam na Nuvem AWS.
Para fins de proteção de dados, recomendamos que você proteja as credenciais da sua conta da AWSe configure contas de usuário individuais com o AWS Identity and Access Management (IAM), de modoque cada usuário receba somente as permissões necessárias para cumprir suas funções. Recomendamostambém que você proteja seus dados das seguintes formas:
• Use uma autenticação multifator (MFA) com cada conta.
174
AWS SDK para .NET Guia do desenvolvedorIdentity and Access Management
• Use SSL/TLS para se comunicar com os recursos da AWS. Para usar uma versão mínima 1.2 do TLS,consulte Impor o TLS 1.2 (p. 177).
• Configure a API e o registro em log das atividades do usuário com o AWS CloudTrail.• Use as soluções de criptografia da AWS, juntamente com todos os controles de segurança padrão nos
serviços da AWS.• Use serviços gerenciados de segurança avançada, como o Amazon Macie, que ajuda a localizar e
proteger dados pessoais que são armazenados no Amazon S3.
É altamente recomendável que você nunca coloque informações de identificação confidenciais, comonúmeros de conta dos seus clientes, em campos de formato livre, como um campo Name (Nome). Issoinclui quando você trabalhar com o this AWS product or service ou outros serviços da AWS usando oconsole, a API, a AWS CLI ou os AWS SDKs. Todos os dados inseridos por você no this AWS product orservice ou em outros serviços podem ser separados para inclusão em logs de diagnóstico. Ao fornecer umURL para um servidor externo, não inclua informações de credenciais no URL para validar a solicitação aesse servidor.
Para obter mais informações sobre proteção de dados, consulte a publicação AWS Shared ResponsibilityModel and GDPR no Blog de segurança da AWS.
Identity and Access Management for this AWSProduct or Service
AWS Identity and Access Management (IAM) is an Amazon Web Services (AWS) service that helpsan administrator securely control access to AWS resources. IAM administrators control who can beauthenticated (signed in) and authorized (have permissions) to use resources in AWS services. IAM is anAWS service that you can use with no additional charge.
To use this AWS product or service to access AWS, you need an AWS account and AWS credentials. Toincrease the security of your AWS account, we recommend that you use an IAM user to provide accesscredentials instead of using your AWS account credentials.
For details about working with IAM, see AWS Identity and Access Management.
For an overview of IAM users and why they are important for the security of your account, see AWSSecurity Credentials in the Amazon Web Services General Reference.
This AWS product or service follows the shared responsibility model through the specific Amazon WebServices (AWS) services it supports. For AWS service security information, see the AWS service securitydocumentation page and AWS services that are in scope of AWS compliance efforts by complianceprogram.
Compliance Validation for this AWS Product orService
This AWS product or service follows the shared responsibility model through the specific Amazon WebServices (AWS) services it supports. For AWS service security information, see the AWS service securitydocumentation page and AWS services that are in scope of AWS compliance efforts by complianceprogram.
The security and compliance of AWS services is assessed by third-party auditors as part of multiple AWScompliance programs. These include SOC, PCI, FedRAMP, HIPAA, and others. AWS provides a frequently
175
AWS SDK para .NET Guia do desenvolvedorResilience
updated list of AWS services in scope of specific compliance programs at AWS Services in Scope byCompliance Program.
Third-party audit reports are available for you to download using AWS Artifact. For more information, seeDownloading Reports in AWS Artifact.
For more information about AWS compliance programs, see AWS Compliance Programs.
Your compliance responsibility when using this AWS product or service to access an AWS service isdetermined by the sensitivity of your data, your organization’s compliance objectives, and applicable lawsand regulations. If your use of an AWS service is subject to compliance with standards such as HIPAA,PCI, or FedRAMP, AWS provides resources to help:
• Security and Compliance Quick Start Guides – Deployment guides that discuss architecturalconsiderations and provide steps for deploying security-focused and compliance-focused baselineenvironments on AWS.
• Architecting for HIPAA Security and Compliance Whitepaper – A whitepaper that describes howcompanies can use AWS to create HIPAA-compliant applications.
• AWS Compliance Resources – A collection of workbooks and guides that might apply to your industryand location.
• AWS Config – A service that assesses how well your resource configurations comply with internalpractices, industry guidelines, and regulations.
• AWS Security Hub – A comprehensive view of your security state within AWS that helps you check yourcompliance with security industry standards and best practices.
Resilience for this AWS Product or ServiceThe Amazon Web Services (AWS) global infrastructure is built around AWS Regions and AvailabilityZones.
AWS Regions provide multiple physically separated and isolated Availability Zones, which are connectedwith low-latency, high-throughput, and highly redundant networking.
With Availability Zones, you can design and operate applications and databases that automatically fail overbetween Availability Zones without interruption. Availability Zones are more highly available, fault tolerant,and scalable than traditional single or multiple data center infrastructures.
For more information about AWS Regions and Availability Zones, see AWS Global Infrastructure.
This AWS product or service follows the shared responsibility model through the specific Amazon WebServices (AWS) services it supports. For AWS service security information, see the AWS service securitydocumentation page and AWS services that are in scope of AWS compliance efforts by complianceprogram.
Infrastructure Security for this AWS Product orService
This AWS product or service follows the shared responsibility model through the specific Amazon WebServices (AWS) services it supports. For AWS service security information, see the AWS service securitydocumentation page and AWS services that are in scope of AWS compliance efforts by complianceprogram.
176
AWS SDK para .NET Guia do desenvolvedorImpor o TLS 1.2
Impor o TLS 1.2 em this AWS Product or ServicePara aumentar a segurança ao comunicar-se com serviços da AWS, você deve configurar o this AWSproduct or service para usar o TLS 1.2 ou posterior.
O AWS SDK para .NET usa o tempo de execução do .NET subjacente para determinar qual protocolo desegurança usar. Por padrão, as versões atuais do .NET usam o protocolo configurado mais recentementeque for compatível com o sistema operacional. Seu aplicativo pode substituir esse comportamento do SDK,mas não é recomendado fazê-lo.
.NET CorePor padrão, o .NET Core usa o protocolo configurado mais recentemente que for compatível com osistema operacional. O AWS SDK para .NET não fornece um mecanismo para substituir isso.
Se você estiver usando uma versão do .NET Core anterior à 2.1, recomendamos veementemente queatualize sua versão do .NET Core.
Consulte os itens a seguir para obter informações específicas sobre cada sistema operacional.
Windows
As distribuições modernas do Windows têm o suporte para TLS 1.2 habilitado por padrão. Caso estejaexecutando o Windows 7 SP1 ou o Windows Server 2008 R2 SP1, você precisa garantir que o suportepara TLS 1.2 esteja habilitado no registro, conforme descrito em https://docs.microsoft.com/en-us/windows-server/security/tls/tls-registry-settings#tls-12. Se estiver executando uma distribuição anterior, você deveráatualizar seu sistema operacional.
macOS
Se estiver executando o .NET Core 2.1 ou posterior, o TLS 1.2 estará habilitado por padrão. O TLS 1.2é compatível com o OS X Mavericks v10.9 ou posterior. O .NET Core versão 2.1 e versões posterioresrequerem versões mais recentes do macOS, conforme descrito em https://docs.microsoft.com/en-us/dotnet/core/install/dependencies?tabs=netcore21&pivots=os-macos.
Caso você esteja usando o .NET Core 1.0, o .NET Core usa OpenSSL no macOS, uma dependênciaque deve ser instalada separadamente. O OpenSSL adicionou suporte para TLS 1.2 na versão 1.0.1(14/03/2012).
Linux
O .NET Core no Linux requer OpenSSL, que é fornecido junto com muitas distribuições Linux. Mastambém pode ser instalado separadamente. O OpenSSL adicionou suporte para TLS 1.2 na versão 1.0.1(14/03/2012). Caso você esteja usando uma versão moderna do .NET Core (2.1 ou posterior) e tenhainstalado um gerenciador de pacotes, é provável que uma versão mais moderna do OpenSSL tenha sidoinstalada para você.
Para ter certeza, você pode executar o openssl version em um terminal e verificar se a versão éposterior à 1.0.1.
.NET FrameworkSe você estiver executando uma versão moderna do .NET Framework (4.7 ou posterior) e uma versãomoderna do Windows (pelo menos o Windows 8 para clientes, o Windows Server 2012 ou posterior paraservidores), o TLS 1.2 será habilitado e usado por padrão.
Se você estiver usando um tempo de execução do .NET Framework que não usa as configurações dosistema operacional (.NET Framework 3.5 a 4.5.2), o AWS SDK para .NET tentará adicionar suporte
177
AWS SDK para .NET Guia do desenvolvedorAWS Tools para PowerShell
para TLS 1.1 e TLS 1.2 aos protocolos compatíveis. Se você estiver usando o .NET Framework 3.5, esseprocesso só será bem-sucedido se o hot patch apropriado estiver instalado, da seguinte forma:
• Windows 10 versão 1511 e Windows Server 2016 – KB3156421• Windows 8.1 e Windows Server 2012 R2 – KB3154520• Windows Server 2012 – KB3154519• Windows 7 SP1 e Server 2008 R2 SP1 – KB3154518
Se o seu aplicativo estiver sendo executado em um .NET Framework mais recente no Windows 7 SP1 ouno Windows Server 2008 R2 SP1, você precisará garantir que o suporte para TLS 1.2 esteja habilitado noregistro, conforme descrito em https://docs.microsoft.com/en-us/windows-server/security/tls/tls-registry-settings#tls-12. Nas versões mais recentes do Windows, ele está habilitado por padrão.
Para obter práticas recomendadas detalhadas para usar TLS com .NET Framework, consulte o artigo daMicrosoft em https://docs.microsoft.com/en-us/dotnet/framework/network-programming/tls.
AWS Tools para PowerShellO AWS Tools para PowerShell usa o AWS SDK para .NET para todas as chamadas a serviços da AWS. Ocomportamento do seu ambiente depende da versão do Windows PowerShell que você está executando,da seguinte forma.
Windows PowerShell 2.0 a 5.x
O Windows PowerShell 2.0 a 5.x é executado no .NET Framework. Você pode verificar qual tempo deexecução do .NET (2.0 ou 4.0) está sendo usado pelo PowerShell usando o comando a seguir.
$PSVersionTable.CLRVersion
• Ao usar o .NET Runtime 2.0, siga as instruções fornecidas anteriormente em relação ao AWS SDKpara .NET e ao .NET Framework 3.5.
• Ao usar o .NET Runtime 4.0, siga as instruções fornecidas anteriormente em relação ao AWS SDKpara .NET e ao .NET Framework 4+.
Windows PowerShell 6.0
O Windows PowerShell 6.0 e versões mais recentes são executados no .NET Core. Você pode verificarqual versão do .NET Core está sendo usada executando o comando a seguir.
[System.Reflection.Assembly]::GetEntryAssembly().GetCustomAttributes([System.Runtime.Versioning.TargetFrameworkAttribute], $true).FrameworkName
Siga as instruções fornecidas anteriormente em relação ao AWS SDK para .NET e à versão relevantedo .NET Core.
XamarinPara Xamarin, consulte as instruções em https://docs.microsoft.com/en-us/xamarin/cross-platform/app-fundamentals/transport-layer-security. Em resumo:
Para Android
• Requer o Android 5.0 ou posterior.
178
AWS SDK para .NET Guia do desenvolvedorUnity
• Project Properties (Propriedades do projeto), Android Options (Opções do Android): a implementação doHttpClient deve ser definida como Android e a implementação do SSL/TLS, definida como Native TLS1.2+ (TLS 1.2+ nativo).
Para iOS
• Requer o iOS 7 ou posterior.• Project Properties (Propriedades do projeto), iOS Build (Compilação do iOS): a implementação do
HttpClient deve ser definida como NSUrlSession.
No macOS
• Requer o macOS 10.9 ou posterior.• Project Options (Opções do projeto), Build (Compilação), Mac Build (Compilação do Mac): a
implementação do HttpClient deve ser definida como NSUrlSession.
UnityVocê deve usar o Unity 2018.2 ou posterior e usar o tempo de execução de scripts equivalenteao .NET 4.x. Você pode definir isso em Project Settings (Configurações do projeto), Configuration(Configuração), Player, conforme descrito em https://docs.unity3d.com/2019.1/Documentation/Manual/ScriptingRuntimeUpgrade.html. O tempo de execução de scripts equivalente ao .NET 4.x habilita o suportea TLS 1.2 para todas as plataformas Unity que executam Mono ou IL2CPP. Para obter mais informações,consulte https://blogs.unity3d.com/2018/07/11/scripting-runtime-improvements-in-unity-2018-2/.
Navegador (para Blazor WebAssembly)O WebAssembly é executado no navegador em vez de no servidor e usa o navegador para lidar com otráfego HTTP. Portanto, o suporte a TLS é determinado pelo suporte do navegador.
O Blazor WebAssembly, na demonstração do ASP.NET Core 3.1, tem suporte apenas em navegadorescompatíveis com o WebAssembly, conforme descrito em https://docs.microsoft.com/en-us/aspnet/core/blazor/supported-platforms?view=aspnetcore-3.1. Todos os navegadores convencionais ofereciam suportea TLS 1.2 antes do suporte a WebAssembly. Se esse for o caso do seu navegador, se o seu aplicativo forexecutado, ele poderá se comunicar por TLS 1.2.
Consulte a documentação do seu navegador para obter mais informações e verificação.
179
AWS SDK para .NET Guia do desenvolvedor
Recursos adicionaisPágina inicial para o AWS SDK para .NET
Para obter mais informações sobre o AWS SDK para .NET, acesse a página inicial do SDK em http://aws.amazon.com/sdk-for-net/.
Documentação de referência do SDK
A documentação de referência do SDK inclui a capacidade de pesquisar e buscar todos os códigosinclusos no SDK. Ela fornece documentação completa, exemplos de uso e até mesmo a capacidadede pesquisar a origem do método. Para obter mais informações, consulte o AWS SDK for .NET APIReference.
Fóruns da AWS
Visite os fóruns da AWS para tirar dúvidas ou fazer comentários sobre a AWS. Cada página dedocumentação possui um botão Ir para os fóruns na parte superior da página, que o direciona até o fórumassociado. Os engenheiros da AWS monitoram os fóruns e respondem as questões, os comentários e osproblemas. Você também pode assinar os feeds RSS para qualquer fórum.
AWS Toolkit for Visual Studio
Se você usar o Microsoft Visual Studio IDE, deverá verificar o Guia do usuário do AWS Toolkit for VisualStudio.
Extensões, bibliotecas e ferramentas úteis
Acesse aws/dotnet no Github para obter links para bibliotecas, ferramentas e recursos que você pode usarpara ajudar a criar serviços e aplicativos.NET na AWS.
Veja alguns destaques do repositório:
• Extensão de configuração do AWS.NET para Systems Manager• Configuração do .NET Core para extensões da AWS• Registro .NET da AWS• Biblioteca de extensão de autenticação do Amazon Cognito• SDK do AWS X-Ray para .NET
180
AWS SDK para .NET Guia do desenvolvedor
Histórico do documentoA tabela a seguir descreve as alterações importantes desde a última versão do Guia do desenvolvedor doAWS SDK para .NET. Para receber notificações sobre atualizações dessa documentação, inscreva-se emum feed RSS.
update-history-change update-history-description update-history-date
Migração do .NET Standard1.3 (p. 64)
Adicionadas informações sobrecomo terminar o suporte parao .NET Standard 1.3 no final de2020.
May 18, 2020
Início rápido (p. 4) Adição de uma seção de iníciorápido com configuração básicae tutoriais para apresentar o leitorao AWS SDK para .NET.
March 27, 2020
Impor o TLS 1.2 (p. 177) Foram adicionadas informaçõessobre como impor o TLS 1.2 noSDK.
March 10, 2020
Versão 3.5 do AWS SDKpara .NET (p. 62)
(Esta é a documentação de pré-lançamento para um recurso emversão de visualização. Ela estásujeita a alterações.) Adição deinformações sobre a versão 3.5do AWS SDK para .NET
February 17, 2020
Nova versão do SDK (p. 181) Versão 3 do AWS SDKpara .NET lançada.
July 28, 2015
181