AWS SDK para
183
AWS SDK for .NET Developer Guide AWS SDK for .NET: Developer Guide Copyright © Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
Transcript of AWS SDK para
AWS SDK for .NETDeveloper Guide
AWS SDK for .NET: Developer GuideCopyright © Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
AWS SDK for .NET Developer Guide
Las marcas comerciales y la imagen comercial de Amazon no se pueden utilizar en relación con ningún producto oservicio que no sea de Amazon de ninguna manera que pueda causar confusión entre los clientes y que menosprecieo desacredite a Amazon. Todas las demás marcas comerciales que no son propiedad de Amazon son propiedad desus respectivos propietarios, que pueden o no estar afiliados, conectados o patrocinados por Amazon.
AWS SDK for .NET Developer Guide
Table of Contents....................................................................................................................................................... vii
¿Qué es AWS SDK for .NET? .............................................................................................................. 1Acerca de esta versión ................................................................................................................ 1Mantenimiento y soporte para las versiones principales del SDK ........................................................ 1Casos de uso común .................................................................................................................. 1Temas adicionales de esta sección ............................................................................................... 2RelacionadoAWSHerramientas de ................................................................................................. 2
Herramientas para Windows PowerShell y Tools for PowerShell Core ......................................... 2Toolkit for VS Code ............................................................................................................ 2Toolkit for Visual Studio ....................................................................................................... 2Kit de herramientas para operaciones de desarrollo de Azure .................................................... 3
Recursos adicionales .................................................................................................................. 3Inicio rápido ....................................................................................................................................... 5
Aplicación multiplataforma sencilla ................................................................................................ 5Steps ................................................................................................................................ 5Configuración para este tutorial ............................................................................................ 5Creación del proyecto ......................................................................................................... 6Crear el código .................................................................................................................. 7Ejecución de la aplicación .................................................................................................... 9Eliminar recursos ................................................................................................................ 9Pasos siguientes ................................................................................................................ 9
Aplicación sencilla basada en Windows ......................................................................................... 9Steps .............................................................................................................................. 10Configuración para este tutorial ........................................................................................... 10Creación del proyecto ........................................................................................................ 11Crear el código ................................................................................................................. 12Ejecución de la aplicación .................................................................................................. 13Eliminar recursos .............................................................................................................. 14Pasos siguientes ............................................................................................................... 14
Pasos siguientes ....................................................................................................................... 14Configuración del entorno .................................................................................................................. 15
Crear una cuenta de AWS ......................................................................................................... 15Paso siguiente .................................................................................................................. 15Información adicional ......................................................................................................... 15
Instalación y configuración de la cadena de herramientas ............................................................... 16Para el desarrollo multiplataforma ....................................................................................... 16Windows con Visual Studio y .NET Core .............................................................................. 16
Configuración del proyecto ................................................................................................................. 17Inicio de un nuevo proyecto ....................................................................................................... 17Crear usuarios y roles ............................................................................................................... 18
Cuentas de usuario ........................................................................................................... 18Roles de servicio .............................................................................................................. 19
ConfiguraciónAWScredenciales ................................................................................................... 20Advertencias y directrices importantes .................................................................................. 20Uso delAWSarchivo de credenciales .................................................................................... 21Uso de SDK Store (solo Windows) ...................................................................................... 23Credenciales y resolución de perfiles ................................................................................... 25
Configuración delAWSRegión ..................................................................................................... 27Crear un cliente de servicio con una región determinada ........................................................ 27Especificar una región para todos los clientes de servicio ....................................................... 28Nueva información acerca de la región de China (Pekín) ........................................................ 29Nueva información acerca deAWSServicios de ...................................................................... 29
Instalar paquetes AWSSDK con NuGet ........................................................................................ 29Uso de NuGet desde el símbolo del sistema o terminal .......................................................... 30
iii
AWS SDK for .NET Developer Guide
Uso de NuGet desde el Explorador de soluciones Visual Studio ............................................... 30Uso de NuGet desde la Consola del administrador de paquetes ............................................... 31
Instalar ensamblados AWSSDK sin NuGet ................................................................................... 31Configuración avanzada ............................................................................................................. 32
AWSSDK.Extensions.NETCore.Setup e Iconfiguration ............................................................ 32Características del SDK ..................................................................................................................... 36
API asincrónicas ....................................................................................................................... 36Reintentos y tiempos de espera .................................................................................................. 37
Retries ............................................................................................................................ 38Timeouts ......................................................................................................................... 39Example .......................................................................................................................... 40
Paginators ............................................................................................................................... 40¿Dónde encontrar paginadores? ......................................................................................... 40¿Qué me dan los paginadores? .......................................................................................... 40Paginación síncrona frente a asincrónica .............................................................................. 41Example .......................................................................................................................... 41Consideraciones adicionales para los paginadores ................................................................. 43
Habilitación de SDK Metrics ...................................................................................................... 44Habilite las métricas del SDK paraAWS SDK for .NET ............................................................ 44Actualizar un agente de CloudWatch ................................................................................... 45Deshabilitación de SDK Metrics .......................................................................................... 46Definiciones para métricas del SDK ..................................................................................... 47
Herramientas adicionales ........................................................................................................... 49AWSHerramienta de implementación de.NET ........................................................................ 49
Migración del proyecto ....................................................................................................................... 50Novedades ............................................................................................................................... 50Plataformas admitidas ............................................................................................................... 50
.NET Core ....................................................................................................................... 50
.NET Standard 2.0 ............................................................................................................ 51
.NET Framework 4.5 ......................................................................................................... 51
.NET Framework 3.5 ......................................................................................................... 51Biblioteca de clases portable .............................................................................................. 51Soporte de Unity ............................................................................................................... 51Más información ............................................................................................................... 51
Migración a la versión 3.5 .......................................................................................................... 51¿Qué ha cambiado para la versión 3.5 ................................................................................ 52Migración de código síncrono ............................................................................................. 53
Migración a la versión 3.7 .......................................................................................................... 53Migración desde .NET Standard 1.3 ............................................................................................. 54
Uso deAWSServicios de .................................................................................................................... 55AWS CloudFormation ................................................................................................................ 55
APIs ................................................................................................................................ 55Prerequisites .................................................................................................................... 55Topics ............................................................................................................................. 56ListaAWSrecursos ............................................................................................................. 56
Amazon EC2 ............................................................................................................................ 57APIs ................................................................................................................................ 57Prerequisites .................................................................................................................... 57Acerca de los ejemplos ..................................................................................................... 58Grupos de seguridad ......................................................................................................... 58Pares de claves ................................................................................................................ 70Regiones y zonas de disponibilidad ..................................................................................... 77Instancias EC2 ................................................................................................................. 78Aprendizaje de instancias de spot ....................................................................................... 90
IAM ......................................................................................................................................... 98APIs ................................................................................................................................ 98Prerequisites .................................................................................................................... 98
iv
AWS SDK for .NET Developer Guide
Topics ............................................................................................................................. 98Creación de usuarios ........................................................................................................ 99Eliminación de usuarios ................................................................................................... 104Crear políticas administradas a partir de JSON .................................................................... 108Visualización de documentos de políticas ........................................................................... 112Conceder acceso con un rol ............................................................................................. 115
Amazon S3 ............................................................................................................................ 120APIs .............................................................................................................................. 120Prerequisites .................................................................................................................. 120Ejemplos de este documento ............................................................................................ 120Ejemplos en otros documentos ......................................................................................... 121Uso de claves KMS para el cifrado S3 ............................................................................... 121
Amazon SQS ......................................................................................................................... 126APIs .............................................................................................................................. 127Prerequisites .................................................................................................................. 127Topics ........................................................................................................................... 127Creación de colas ........................................................................................................... 127Actualizar colas ............................................................................................................... 133Eliminación de colas ........................................................................................................ 138Envío de mensajes .......................................................................................................... 142Recepción de mensajes ................................................................................................... 145
AWS OpsWorks ...................................................................................................................... 148APIs .............................................................................................................................. 149Prerequisites .................................................................................................................. 149
Otros servicios y configuración .................................................................................................. 149Herramientas adicionales ................................................................................................................. 150
Herramienta de implementación ................................................................................................ 150Configuración del entorno ................................................................................................. 151Configuración de la herramienta ........................................................................................ 152Configuración de las credenciales ...................................................................................... 152Ejecución de la herramienta ............................................................................................. 153Implementación: Tutoriales ............................................................................................... 154Volver a implementar ....................................................................................................... 158Configuración de implementación ...................................................................................... 159
Seguridad ...................................................................................................................................... 161Protección de los datos ............................................................................................................ 161Identity and Access Management .............................................................................................. 162Validación de la conformidad .................................................................................................... 162Resiliencia .............................................................................................................................. 163Seguridad de la infraestructura .................................................................................................. 164Aplicación de TLS 1.2 .............................................................................................................. 164
.NET Core ...................................................................................................................... 164
.NET Framework ............................................................................................................. 165AWS Tools for PowerShell ............................................................................................... 165Xamarin ......................................................................................................................... 166Unity ............................................................................................................................. 166Navegador (para Blazor WebAssembly) .............................................................................. 166
Migración de clientes de cifrado de S3 ....................................................................................... 167Información general sobre migración .................................................................................. 167Actualizar clientes existentes a clientes de transición V1 para leer nuevos formatos ................... 167Migración de clientes de transición V1 a clientes V2 para escribir nuevos formatos .................... 168Actualizar clientes V2 para que ya no lean los formatos V1 ................................................... 170
Consideraciones especiales .............................................................................................................. 171Obtención de ensamblados de AWSSDK .................................................................................... 171
Descargue y extraiga archivos de ...................................................................................... 171Instalar el MSI en Windows .............................................................................................. 171
Acceso a credenciales y perfiles en una aplicación ...................................................................... 172
v
AWS SDK for .NET Developer Guide
Ejemplos de la clase CredentialProfileStoreChain ................................................................. 172Ejemplos de clases SharedCredentialsFile y awScredentialsFactory ........................................ 173
Soporte de Unity ..................................................................................................................... 174Xamarin Soporte ..................................................................................................................... 175
Historial de revisión ......................................................................................................................... 176
vi
AWS SDK for .NET Developer Guide
HolaAWS.NET! Por favor, comparta su experiencia y ayúdenos a mejorar elAWS SDK for .NETy susrecursos de aprendizaje porRealización de una encuesta. Su finalización tarda aproximadamente 10minutos.
Las traducciones son generadas a través de traducción automática. En caso de conflicto entre latraducción y la version original de inglés, prevalecerá la version en inglés.
vii
AWS SDK for .NET Developer GuideAcerca de esta versión
¿Qué es AWS SDK for .NET?LaAWS SDK for .NETEl facilita la creación de aplicaciones de .NET que aprovechen la rentabilidad,escalabilidad y confiabilidad de aplicaciones de .NETAWSServicios de Amazon Simple StorageService (Amazon S3) y Amazon Elastic Compute Cloud (Amazon EC2). El SDK simplifica el usodeAWSproporcionando un conjunto de bibliotecas que son coherentes y familiares para los desarrolladoresde.NET.
(De acuerdo, ya lo tengoEstoy listo para unaTutorial de (p. 5)o para iniciarConfiguración (p. 15).)
Acerca de esta versiónNote
Esta documentación es para la versión 3.5 y posterior delAWS SDK for .NET. Está principalmentecentrado en .NET Core y ASP.NET Core. Además de Windows y Visual Studio, da igualconsideración al desarrollo multiplataforma.Documentación para la versión 3.0 del SDK, que se centra principalmente en .NET Frameworky ASP.NET 4.x, Windows y Visual Studio, se pueden encontrar enhttps://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/Para obtener más información sobre la migración, consulteMigración del proyecto (p. 50).
Mantenimiento y soporte para las versionesprincipales del SDK
Para obtener información sobre el mantenimiento y la compatibilidad con las versiones principales delSDK y sus dependencias subyacentes, consulte lo siguiente en elAWSGuía de referencia de los SDK y lasherramientas:
• AWS Política de mantenimiento de SDK y herramientas de• AWS Matriz de compatibilidad con versiones de SDK y herramientas
Casos de uso comúnLaAWS SDK for .NETEl ayuda a realizar varios casos de uso convincentes, entre los que se incluyen lossiguientes:
• Gestione usuarios y roles conAWS Identity and Access Management(IAM).
1
AWS SDK for .NET Developer GuideTemas adicionales de esta sección
• Acceso aAmazon Simple Storage Service (Amazon S3)Para crear buckets y almacenar objetos.• AdministraciónAmazon Simple Notification Service (Amazon SNS)Suscripciones HTTP a temas.• UsarUtilidad de transferencia de S3para transferir archivos a Amazon S3 desde sus aplicaciones
Xamarin.• UsarAmazon Simple Queue Service (Amazon SQS)para procesar mensajes y flujos de trabajo entre
componentes de un sistema.• Realice transferencias eficientes de Amazon S3 enviando sentencias SQL aAmazon S3 Select.• Crear y lanzarAmazon EC2y configurar y solicitar Amazon EC2Instancias de spot.
Temas adicionales de esta sección• AWSHerramientas relacionadas conAWS SDK for .NET (p. 2)• Recursos adicionales (p. 3)
AWSHerramientas relacionadas conAWS SDKfor .NET
Herramientas para Windows PowerShell y Tools forPowerShell CoreAWS Tools for Windows PowerShell y AWS Tools for PowerShell Core son módulos de PowerShellbasados en la funcionalidad expuesta por el AWS SDK for .NET. LaAWSLas herramientas de PowerShellle permiten realizar operaciones mediante scripts en suAWSdesde el símbolo del sistema de PowerShell.Aunque los cmdlets se implementan mediante los clientes del servicio y los métodos del SDK, los cmdletsproporcionan una experiencia de PowerShell idiomático para especificar parámetros y administrar losresultados.
Para empezar, consulte AWS Tools for Windows PowerShell.
Toolkit for VS CodeEl AWS Toolkit for Visual Studio Code es un complemento para el editor de código de Visual Studio (VSCode). El conjunto de herramientas facilita el desarrollo, la depuración y la implementación de aplicacionesque utilizan AWS.
Con el conjunto de herramientas, puede hacer cosas como las siguientes:
• Crear aplicaciones sin servidor que contengan funciones AWS Lambda e implementar las aplicacionesen una pila de AWS CloudFormation.
• Trabajo con esquemas de Amazon EventBridge.• Utilice IntelliSense cuando trabaje con archivos de definición de tareas de Amazon ECS.• Visualización de una aplicación de AWS Cloud Development Kit (CDK)
Toolkit for Visual StudioEl AWS Toolkit for Visual Studio es un complemento para el IDE de Visual Studio que facilita el desarrollo,la depuración y la implementación de aplicaciones .NET que utilizan Amazon Web Services. El Toolkit for
2
AWS SDK for .NET Developer GuideKit de herramientas para operaciones de desarrollo de Azure
Visual Studio proporciona plantillas de Visual Studio para servicios tales como Lambda y asistentes deimplementación para aplicaciones web y aplicaciones sin servidor. Puede utilizar elAWSExplorador paraadministrar instancias de Amazon EC2, trabajar con tablas de Amazon DynamoDB, publicar mensajes encolas de Amazon Simple Notification Service (Amazon SNS), etc., todo ello dentro de Visual Studio.
Para empezar, consulteConfiguración delAWS Toolkit for Visual Studio.
Kit de herramientas para operaciones de desarrollo deAzureAWS Toolkit for Microsoft Azure DevOps añade tareas para habilitar fácilmente la creación y publicaciónde canalizaciones en Azure DevOps y Azure DevOps Server para trabajar con los servicios de AWS.Puede trabajar con Amazon S3,AWS Elastic Beanstalk,AWS CodeDeploy, Lambda,AWS CloudFormation,Amazon Simple Queue Service (Amazon SQS) y Amazon SNS. También puede ejecutar comandos con elmódulo Windows PowerShell y la AWS Command Line Interface (AWS CLI).
Para empezar a trabajar conAWS Toolkit for Azure DevOps, consulte laAWS Toolkit for Microsoft AzureDevOpsGuía del usuario.
Recursos adicionalesServicios admitidos e historial de revisiones
El AWS SDK for .NET admite la mayoría de los productos de infraestructura de AWS y más servicios seañaden con frecuencia. Para obtener una lista de los servicios de AWS compatibles con el SDK, consulteel archivo README del SDK.
Para ver lo que ha cambiado en una versión determinada, consulte el registro de cambios del SDK.
Home page (Página de inicio) AWS SDK for .NET
Para obtener más información acerca delAWS SDK for .NETConsulte la página de inicio del SDK enhttps://aws.amazon.com/sdk-for-net/.
Documentación de referencia del SDK
La documentación de referencia del SDK le ofrece la capacidad de explorar y buscar entre todo elcódigo incluido en el SDK. Proporciona documentación exhaustiva y ejemplos de uso. Para obtener másinformación, consulte la Referencia de la API de AWS SDK for .NET.
AWS foros
Visite laAWSPara realizar preguntas o realizar comentarios acerca deAWS. Cada página dedocumentación tiene unIr a los forosEn la parte superior de la página que le dirigirá al foroasociado.AWSLos ingenieros de los foros monitorean los foros y responden a las preguntas, loscomentarios y los problemas. También puede suscribirse a las fuentes RSS de cualquiera de los foros.
AWS Toolkit for Visual Studio
Si utiliza el IDE de Microsoft Visual Studio, debería comprobar elAWS Toolkit for Visual StudioGuía delusuario.
Bibliotecas, extensiones y herramientas útiles
Visite laaws/dotnetyaws/aws-sdk-netEn el sitio web de GitHub encontrará enlaces a bibliotecas,herramientas y recursos que puede utilizar como ayuda para la creación de aplicaciones y servicios .NETenAWS.
3
AWS SDK for .NET Developer GuideRecursos adicionales
Estas son algunas de las características principales desde el repositorio:
• AWS .NET Configuration Extension para Systems Manager• AWS .NET Core Setup• AWS .NET• Biblioteca de extensiones de autenticación de Amazon Cognito• AWS X-Ray SDK para .NET
4
AWS SDK for .NET Developer GuideAplicación multiplataforma sencilla
Comience a utilizar rápidamentelaAWS SDK for .NET
Esta sección incluye pasos básicos de configuración y tutoriales para desarrolladores que son nuevos enelAWS SDK for .NET.
Para obtener información más avanzada, consulteConfiguración del entorno (p. 15)yUso deAWSEnelAWS SDK for .NET (p. 55)En lugar de esto
Temas• Aplicación multiplataforma sencilla que utiliza la herramienta AWS SDK for .NET (p. 5)• Aplicación sencilla basada en Windows que utiliza la herramienta AWS SDK for .NET (p. 9)• Pasos siguientes (p. 14)
Aplicación multiplataforma sencilla que utiliza laherramienta AWS SDK for .NET
En este tutorial se utilizaAWS SDK for .NETy .NET Core para el desarrollo multiplataforma. En el tutorial semuestra cómo utilizar el SDK para enumerar laBuckets de Amazon S3que posee y, opcionalmente, cree undepósito.
Steps• Configuración para este tutorial (p. 5)• Creación del proyecto (p. 6)• Crear el código (p. 7)• Ejecución de la aplicación (p. 9)• Eliminar recursos (p. 9)
Configuración para este tutorialEsta sección proporciona la configuración mínima necesaria para completar este tutorial. No deberíatomarse esto como una configuración completa. Para una configuración completa, vaya a ConfigurarsuAWS SDK for .NETenvironment (p. 15).
Note
Si ya ha completado alguno de los siguientes pasos a través de otros tutoriales o unaconfiguración ya existente, omita esos pasos.
Crear una cuenta de AWSPara crear unAWS, consulte¿Cómo creo y activo una nueva cuenta de Amazon Web Services?
Crear credenciales de AWS y un perfilPara realizar estos tutoriales, debe crear unAWS Identity and Access Management(IAM) y obtenercredenciales para ese usuario. Una vez que tenga esas credenciales, las pone a disposición del SDK ensu entorno de desarrollo. A continuación se indica el procedimiento.
5
AWS SDK for .NET Developer GuideCreación del proyecto
Para crear y utilizar credenciales
1. Inicie sesión en la AWS Management Console y abra la consola de IAM en https://console.aws.amazon.com/iam/.
2. Seleccione Users y, luego, Add user.3. Proporcione un nombre de usuario. Para este tutorial, utilizaremos Dotnet-Tutorial-User.4. UNDERSelectAWSTipo de accesoSeleccione, seleccioneAcceso programáticoy, a continuación,
seleccioneSiguiente: Permisos.5. Elija Attach existing policies directly.6. EnBúsqueda, introduzcas3y, a continuación, seleccioneAmazonS3FullAccess.7. Seleccione Next (Siguiente): Etiquetas,Siguiente: Review (Revisar), yCreación de usuario.8. Registre las credenciales de Dotnet-Tutorial-User. Puede hacerlo descargando el archivo .csv o
copiando y pegando el ID de clave de acceso y la clave de acceso secreta.
Warning
Utilice las medidas de seguridad adecuadas para mantener estas credenciales seguras yrotadas.
9. Cree o abra el archivo de credenciales compartidas de AWS. Este archivo es~/.aws/credentialsen sistemas Linux y macOS, y%USERPROFILE%\.aws\credentialsen Windows.
10. Agregue el texto siguiente al archivo de credenciales compartidas de AWS, pero reemplace el ID deejemplo y la clave de ejemplo por los que obtuvo anteriormente. Recuerde guardar el archivo.
[dotnet-tutorials]aws_access_key_id = AKIAIOSFODNN7EXAMPLEaws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
El procedimiento anterior es la más simple de entre varias posibilidades de autenticación y autorización.Para obtener información completa, consulteConfiguraciónAWScredenciales (p. 20).
Instalación de otras herramientas
Llevará a cabo este tutorial utilizando herramientas multiplataforma como la interfaz de la líneade comandos (CLI) .NET. Para obtener otras formas de configurar el entorno de desarrollo,consulteInstalación y configuración de la cadena de herramientas (p. 16).
Necesario para el desarrollo multiplataforma de .NET en Windows, Linux o macOS:
• Microsoft .NET Core SDK, versión 2.1, 3.1 o posterior, que incluye la interfaz de línea de comandos (CLI)de .NET (dotnet) y el tiempo de ejecución de .NET Core.
• Un editor de código o entorno de desarrollo integrado (IDE) adecuado para el sistema operativo y losrequisitos. Esto normalmente es uno que proporciona cierto soporte para .NET Core.
Entre los ejemplos se incluyen Microsoft Visual Studio Code (VS Code), JetBrains Rider y MicrosoftVisual Studio.
Creación del proyecto1. Abra el símbolo del sistema o la terminal. Busque o cree una carpeta del sistema operativo en la que
pueda crear un proyecto .NET.
6
AWS SDK for .NET Developer GuideCrear el código
2. En esa carpeta, ejecute el siguiente comando para crear el proyecto .NET.
dotnet new console --name S3CreateAndList
3. Vaya a la carpeta S3CreateAndList recién creada y ejecute el siguiente comando.
dotnet add package AWSSDK.S3
El comando anterior instala el paquete AWSSDK.S3 NuGet desde el administrador de paquetesNuGet. Dado que sabemos exactamente qué paquetes NuGet necesitamos para este tutorial,podemos realizar este paso ahora. También es común que los paquetes requeridos se conozcandurante el desarrollo. Cuando esto sucede, se puede ejecutar un comando similar en ese momento.
4. Agregue las siguientes variables de entorno temporales al entorno.
Linux o macOS
AWS_PROFILE='dotnet-tutorials'AWS_REGION='us-west-2'
Windows
set AWS_PROFILE=dotnet-tutorialsset AWS_REGION=us-west-2
Crear el código1. En la carpeta S3CreateAndList, busque y abra Program.cs en su editor de código.2. Reemplace el contenido con el siguiente código y guarde el archivo.
using System;using System.Threading.Tasks;
// To interact with Amazon S3.using Amazon.S3;using Amazon.S3.Model;
namespace S3CreateAndList{ class Program { // Main method static async Task Main(string[] args) { // Before running this app: // - Credentials must be specified in an AWS profile. If you use a profile other than // the [default] profile, also set the AWS_PROFILE environment variable. // - An AWS Region must be specified either in the [default] profile // or by setting the AWS_REGION environment variable.
// Create an S3 client object. var s3Client = new AmazonS3Client();
// Parse the command line arguments for the bucket name. if(GetBucketName(args, out String bucketName)) { // If a bucket name was supplied, create the bucket.
7
AWS SDK for .NET Developer GuideCrear el código
// Call the API method directly try { Console.WriteLine($"\nCreating bucket {bucketName}..."); var createResponse = await s3Client.PutBucketAsync(bucketName); Console.WriteLine($"Result: {createResponse.HttpStatusCode.ToString()}"); } catch (Exception e) { Console.WriteLine("Caught exception when creating a bucket:"); Console.WriteLine(e.Message); } }
// List the buckets owned by the user. // Call a class method that calls the API method. Console.WriteLine("\nGetting a list of your buckets..."); var listResponse = await MyListBucketsAsync(s3Client); Console.WriteLine($"Number of buckets: {listResponse.Buckets.Count}"); foreach(S3Bucket b in listResponse.Buckets) { Console.WriteLine(b.BucketName); } }
// // Method to parse the command line. private static Boolean GetBucketName(string[] args, out String bucketName) { Boolean retval = false; bucketName = String.Empty; if (args.Length == 0) { Console.WriteLine("\nNo arguments specified. Will simply list your Amazon S3 buckets." + "\nIf 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("\nToo many arguments specified." + "\n\ndotnet_tutorials - A utility to list your Amazon S3 buckets and optionally create a new one." + "\n\nUsage: S3CreateAndList [bucket_name]" + "\n - bucket_name: A valid, globally unique bucket name." + "\n - If bucket_name isn't supplied, this utility simply lists your buckets."); Environment.Exit(1); } return retval; }
// // Async method to get a list of Amazon S3 buckets. private static async Task<ListBucketsResponse> MyListBucketsAsync(IAmazonS3 s3Client) {
8
AWS SDK for .NET Developer GuideEjecución de la aplicación
return await s3Client.ListBucketsAsync(); }
}}
Ejecución de la aplicación1. Ejecute el comando siguiente.
dotnet run
2. Examine la salida para ver el número de buckets de Amazon S3 de que posee, si los hay, y susnombres.
3. Elija un nombre para un bucket nuevo de Amazon S3. Use «dotnet-quickstart-s3-1-cross-» como basey agregue algo único, como un GUID o su nombre. Asegúrese de seguir las reglas para nombres debucket, como se describe enReglas de nomenclatura de bucketsen laAmazon Simple Storage ServiceDeveloper Guide.
4. Ejecute el siguiente comando, reemplazando BUCKET-NAME por el nombre del bucket elegido.
dotnet run BUCKET-NAME
5. Examine la salida para ver el nuevo bucket que se creó.
Eliminar recursosDurante la realización de este tutorial, ha creado algunos recursos que puede elegir limpiar en estemomento.
• Si no desea conservar el depósito creado por la aplicación en un paso anterior, elimínelo mediante laconsola de Amazon S3 enhttps://console.aws.amazon.com/s3/.
• Si no desea mantener al usuario que creó durante la configuración del tutorial anteriormente en estetema, elimínelo mediante la consola de IAM enhttps://console.aws.amazon.com/iam/home#/users.
Si elige eliminar el usuario, también debe eliminar eldotnet-tutorialsque ha creado enelAWSarchivo de credenciales. En este tema creó este perfil durante la configuración del tutorialanteriormente.
• Si no desea conservar el proyecto .NET, quite elS3CreateAndListdesde el entorno de desarrollo.
Pasos siguientesVuelva al menú de inicio rápido (p. 5) o vaya directamente al final de este inicio rápido (p. 14).
Aplicación sencilla basada en Windows que utilizala herramienta AWS SDK for .NET
En este tutorial se utilizaAWS SDK for .NETen Windows con Visual Studio y .NET Core. En el tutorial semuestra cómo utilizar el SDK para enumerar laBuckets de Amazon S3que posee y, opcionalmente, cree undepósito.
9
AWS SDK for .NET Developer GuideSteps
Steps• Configuración para este tutorial (p. 10)• Creación del proyecto (p. 11)• Crear el código (p. 12)• Ejecución de la aplicación (p. 13)• Eliminar recursos (p. 14)
Configuración para este tutorialEsta sección proporciona la configuración mínima necesaria para completar este tutorial. No deberíatomarse esto como una configuración completa. Para una configuración completa, vaya a ConfigurarsuAWS SDK for .NETenvironment (p. 15).
Note
Si ya ha completado alguno de los siguientes pasos a través de otros tutoriales o unaconfiguración ya existente, omita esos pasos.
Crear una cuenta de AWS
Para crear unAWS, consulte¿Cómo puedo crear y activar una cuenta nueva de Amazon Web Services?
Crear credenciales de AWS y un perfil
Para realizar estos tutoriales, debe crear unAWS Identity and Access Management(IAM) y obtenercredenciales para ese usuario. Una vez que tenga esas credenciales, las pone a disposición del SDK ensu entorno de desarrollo. A continuación se indica el procedimiento.
Para crear y utilizar credenciales
1. Inicie sesión en la AWS Management Console y abra la consola de IAM en https://console.aws.amazon.com/iam/.
2. Seleccione Users y, luego, Add user.3. Proporcione un nombre de usuario. Para este tutorial, utilizaremos Dotnet-Tutorial-User.4. UNDERSelectAWSTipo de accesoSeleccione, seleccioneAcceso programáticoy, a continuación,
seleccioneSiguiente: Permisos.5. Elija Attach existing policies directly.6. EnBúsqueda, introduzcas3y, a continuación, seleccioneAmazonS3FullAccess.7. Seleccione Next (Siguiente): Etiquetas,Siguiente: Review (Revisar), yCreación de usuario.8. Registre las credenciales de Dotnet-Tutorial-User. Puede hacerlo descargando el archivo .csv o
copiando y pegando el ID de clave de acceso y la clave de acceso secreta.
Warning
Utilice las medidas de seguridad adecuadas para mantener estas credenciales seguras yrotadas.
9. Cree o abra el archivo de credenciales compartidas de AWS. Este archivo es~/.aws/credentialsen sistemas Linux y macOS, y%USERPROFILE%\.aws\credentialsen Windows.
10. Agregue el texto siguiente al archivo de credenciales compartidas de AWS, pero reemplace el ID deejemplo y la clave de ejemplo por los que obtuvo anteriormente. Recuerde guardar el archivo.
10
AWS SDK for .NET Developer GuideCreación del proyecto
[dotnet-tutorials]aws_access_key_id = AKIAIOSFODNN7EXAMPLEaws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
El procedimiento anterior es la más simple de entre varias posibilidades de autenticación y autorización.Para obtener información completa, consulteConfiguraciónAWScredenciales (p. 20).
Instalación de otras herramientas
Llevará a cabo este tutorial en Windows mediante Visual Studio y .NET Core. Para obtener otrasformas de configurar el entorno de desarrollo, consulteInstalación y configuración de la cadena deherramientas (p. 16).
Necesario para el desarrollo en Windows con Visual Studio y .NET Core:
• Microsoft Visual Studio
• Microsoft .NET Core 2.1, 3.1 o posterior
Esto normalmente se incluye de forma predeterminada al instalar una versión reciente de Visual Studio.
Creación del proyecto1. Abra Visual Studio y cree un nuevo proyecto que use la versión C# delAplicación de Consola; es decir,
con descripción: «... para crear una aplicación de línea de comandos que se pueda ejecutar en.NETCore...». Asigne un nombre al proyecto S3CreateAndList.
Note
No elija la versión de.NET Framework de la plantilla de aplicación de consola o, si lo hace,asegúrese de usar .NET Framework 4.5 o posterior.
2. Con el proyecto recién creado cargado, elijaHerramientas de,Administrador de paquetesNuGet,Administrar paquetes NuGet para la solución.
3. Busque el paquete AWSSDK.S3 NuGet e instálelo en el proyecto.
Este proceso instala el paquete AWSSDK.S3 NuGet desde el administrador de paquetes NuGet. Dadoque sabemos exactamente qué paquetes NuGet necesitamos para este tutorial, podemos realizareste paso ahora. También es común que los paquetes requeridos se conozcan durante el desarrollo.Cuando esto suceda, siga un proceso similar para instalarlos en ese momento.
4. Si tiene la intención de ejecutar la aplicación desde el símbolo del sistema, abra un símbolo delsistema ahora y vaya a la carpeta que contendrá la salida de compilación. Esto suele ser algo asícomo S3CreateAndList\S3CreateAndList\bin\Debug\netcoreapp3.1, pero dependerá denuestro entorno.
5. Agregue las siguientes variables de entorno temporales al entorno.
En el símbolo del sistema, utilice lo siguiente.
set AWS_PROFILE=dotnet-tutorialsset AWS_REGION=us-west-2
O bien, si tiene la intención de ejecutar la aplicación en el IDE, seleccioneProyecto de,Propiedades deS3CreateAndList,Debugy ponerlos allí.
11
AWS SDK for .NET Developer GuideCrear el código
Crear el código1. En el proyecto S3CreateAndList, busque y abra Program.cs en el IDE.2. Reemplace el contenido con el siguiente código y guarde el archivo.
using System;using System.Threading.Tasks;
// To interact with Amazon S3.using Amazon.S3;using Amazon.S3.Model;
namespace S3CreateAndList{ class Program { // Main method static async Task Main(string[] args) { // Before running this app: // - Credentials must be specified in an AWS profile. If you use a profile other than // the [default] profile, also set the AWS_PROFILE environment variable. // - An AWS Region must be specified either in the [default] profile // or by setting the AWS_REGION environment variable.
// Create an S3 client object. var s3Client = new AmazonS3Client();
// Parse the command line arguments for the bucket name. if(GetBucketName(args, out String bucketName)) { // If a bucket name was supplied, create the bucket. // Call the API method directly try { Console.WriteLine($"\nCreating bucket {bucketName}..."); var createResponse = await s3Client.PutBucketAsync(bucketName); Console.WriteLine($"Result: {createResponse.HttpStatusCode.ToString()}"); } catch (Exception e) { Console.WriteLine("Caught exception when creating a bucket:"); Console.WriteLine(e.Message); } }
// List the buckets owned by the user. // Call a class method that calls the API method. Console.WriteLine("\nGetting a list of your buckets..."); var listResponse = await MyListBucketsAsync(s3Client); Console.WriteLine($"Number of buckets: {listResponse.Buckets.Count}"); foreach(S3Bucket b in listResponse.Buckets) { Console.WriteLine(b.BucketName); } }
// // Method to parse the command line. private static Boolean GetBucketName(string[] args, out String bucketName) {
12
AWS SDK for .NET Developer GuideEjecución de la aplicación
Boolean retval = false; bucketName = String.Empty; if (args.Length == 0) { Console.WriteLine("\nNo arguments specified. Will simply list your Amazon S3 buckets." + "\nIf 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("\nToo many arguments specified." + "\n\ndotnet_tutorials - A utility to list your Amazon S3 buckets and optionally create a new one." + "\n\nUsage: S3CreateAndList [bucket_name]" + "\n - bucket_name: A valid, globally unique bucket name." + "\n - If bucket_name isn't supplied, this utility simply lists your buckets."); Environment.Exit(1); } return retval; }
// // Async method to get a list of Amazon S3 buckets. private static async Task<ListBucketsResponse> MyListBucketsAsync(IAmazonS3 s3Client) { return await s3Client.ListBucketsAsync(); }
}}
3. Compilación de la aplicación.
Note
Si está utilizando una versión anterior de Visual Studio, puede aparecer un error decompilación similar al siguiente:«La característica 'async main' no está disponible en C # 7.0. Utilice la versión de idioma 7.1o superior.»Si aparece este error, configure el proyecto para que utilice una versión posterior del idioma.Esto se realiza normalmente en las propiedades del proyecto,Build,Advanced (Avanzado).
Ejecución de la aplicación1. Ejecute la aplicación sin argumentos de línea de comandos. Haga esto en el símbolo del sistema (si
abrió una anteriormente) o desde el IDE.2. Examine la salida para ver el número de buckets de Amazon S3 de que posee, si los hay, y sus
nombres.3. Elija un nombre para un bucket nuevo de Amazon S3. Use «dotnet-quickstart-s3-1-winvs-» como base
y agregue algo único, como un GUID o su nombre. Asegúrese de seguir las reglas para nombres de
13
AWS SDK for .NET Developer GuideEliminar recursos
bucket, como se describe enReglas para la nomenclatura de bucketsen laAmazon Simple StorageService Developer Guide.
4. Vuelva a ejecutar la aplicación, esta vez proporcionando el nombre del bucket.
En la línea de comandos, reemplaceNOMBRE-BUCKETEn el siguiente comando con el nombre delbucket elegido.
S3CreateAndList BUCKET-NAME
O bien, si está ejecutando la aplicación en el IDE, seleccioneProyecto de,Propiedades deS3CreateAndList,Debuge ingrese el nombre del depósito allí.
5. Examine la salida para ver el nuevo bucket que se creó.
Eliminar recursosDurante la realización de este tutorial, ha creado algunos recursos que puede elegir limpiar en estemomento.
• Si no desea conservar el depósito creado por la aplicación en un paso anterior, elimínelo mediante laconsola de Amazon S3 enhttps://console.aws.amazon.com/s3/.
• Si no desea mantener al usuario que creó durante la configuración del tutorial anteriormente en estetema, elimínelo mediante la consola de IAM enhttps://console.aws.amazon.com/iam/home#/users.
Si elige eliminar el usuario, también debe eliminar eldotnet-tutorialsque ha creado enelAWSarchivo de credenciales. En este tema creó este perfil durante la configuración del tutorialanteriormente.
• Si no desea conservar el proyecto .NET, quite elS3CreateAndListdesde el entorno de desarrollo.
Pasos siguientesVuelva al menú de inicio rápido (p. 5) o vaya directamente al final de este inicio rápido (p. 14).
Pasos siguientesAsegúrese de limpiar los recursos sobrantes que haya creado mientras realiza estos tutoriales. Puedentratarse deAWSLos recursos de o recursos en su entorno de desarrollo, como archivos y carpetas.
Ahora que ha hecho un recorrido por AWS SDK for .NET, es posible que desee ver una configuración másavanzada (p. 15).
14
AWS SDK for .NET Developer GuideCrear una cuenta de AWS
Configurar suAWS SDKfor .NETenvironment
En esta sección se muestra cómo configurar las características globales y la configuración para laAWSSDK for .NET.
Si es la vez que utiliza el desarrollo.NET enAWSo al menos nuevo en elAWS SDK for .NET, echa unvistazo a laInicio rápido (p. 5)el tema primero. Proporciona una introducción al SDK.
Cuando ya no utilice estos temas, puede pasar aConfiguración del proyecto (p. 17).
Temas• Crear una cuenta de AWS (p. 15)• Instalación y configuración de la cadena de herramientas (p. 16)
Crear una cuenta de AWSPara utilizar elAWS SDK for .NETPara obtener acceso aAWSPara obtener servicios deAWSCuenta deyAWSCredenciales de .
1. Cree una cuenta de .
Para crear unAWS, consulte¿Cómo creo y activo una nueva cuenta de Amazon Web Services?2. Creación de un usuario administrativo.
Evite usar su cuenta de usuario raíz (la cuenta inicial que cree) para obtener acceso a la consola deadministración y los servicios. En su lugar, cree una cuenta de usuario administrativo, como se explicaenCreación del primer grupo y usuario administrador de IAM.
Después de crear la cuenta de usuario administrativo y registrar los detalles de inicio de sesión,cerrarsesión en tu cuenta de usuario raízy vuelve a iniciar sesión con la cuenta administrativa.
Si necesita cerrar suAWS, consulteCierre de una cuenta.
Paso siguienteInstalación y configuración de la cadena de herramientas (p. 16)
Información adicionalPara obtener información adicional acerca de cómo administrar certificados y seguridad, consultePrácticasrecomendadas y casos de uso de IAMen laIAM User Guide.
Para obtener información sobre cómo agregarAWSa sus aplicaciones,consulteConfiguraciónAWScredenciales (p. 20).
15
AWS SDK for .NET Developer GuideInstalación y configuración de la cadena de herramientas
Instalación y configuración de la cadena deherramientas
Para utilizarAWS SDK for .NETDebe tener instaladas ciertas herramientas de desarrollo.
Note
Si ha realizado el inicio rápido para el SDK (p. 5), es posible que ya tenga algunas de estasherramientas instaladas. Si no hizo el inicio rápido y es nuevo en el desarrollo .NET enAWS,considere hacer eso primero para una introducción alAWS SDK for .NET.
Para el desarrollo multiplataformaNecesario para el desarrollo multiplataforma de .NET en Windows, Linux o macOS:
• Microsoft .NET Core SDK, versión 2.1, 3.1 o posterior, que incluye la interfaz de línea de comandos (CLI)de .NET (dotnet) y el tiempo de ejecución de .NET Core.
• Un editor de código o entorno de desarrollo integrado (IDE) adecuado para el sistema operativo y losrequisitos. Esto normalmente uno que proporciona cierto soporte para .NET Core.
Entre los ejemplos se incluyen Microsoft Visual Studio Code (VS Code), JetBrains Rider y MicrosoftVisual Studio.
• (Opcional) UnAWSsi hay uno disponible para el editor que eligió y su sistema operativo.
Entre los ejemplos se incluyenAWS Toolkit for Visual Studio Code,AWS Toolkit for JetBrains, yAWSToolkit for Visual Studio.
Windows con Visual Studio y .NET CoreNecesario para el desarrollo en Windows con Visual Studio y .NET Core:
• Microsoft Visual Studio
• Microsoft .NET Core 2.1, 3.1 o posterior
Esto normalmente se incluye de forma predeterminada al instalar una versión reciente de Visual Studio.
• (Opcional) ElAWS Toolkit for Visual StudioUn complemento que proporciona una interfaz de usuario paraadministrarAWSLos perfiles locales y recursos de Visual Studio. Para instalar el kit de herramientas,consulteConfiguración delAWS Toolkit for Visual Studio.
Para obtener más información, consulte la Guía del usuario de AWS Toolkit for Visual Studio.
16
AWS SDK for .NET Developer GuideInicio de un nuevo proyecto
Configuración deAWS SDKfor .NETProyecto de
Además deConfiguración del entorno (p. 15), debe configurar cada proyecto que cree.Note
La configuración que se muestra aquí se centra en .NET Core y ASP.NET Core (aunque puedehaber cierta superposición con la configuración de.NET Framework).Si busca la configuración de.NET Framework, consulteVersión 3de la guía en su lugar.
Hay algunas cosas esenciales que su aplicación necesita para accederAWSA través deAWS SDKfor .NET:
• Una cuenta de usuario o un rol adecuado• Credenciales para esa cuenta de usuario o para asumir ese rol• Especificación deAWSRegión• Paquetes o ensamblajes AWSSDK
Algunos de los temas de esta sección proporcionan información acerca de cómo configurar estas cosasesenciales.
Otros temas de esta sección y otras secciones proporcionan información sobre formas más avanzadas deconfigurar el proyecto.
Temas• Inicio de un nuevo proyecto (p. 17)• Crear usuarios y roles (p. 18)• ConfiguraciónAWScredenciales (p. 20)• Configuración delAWSRegión (p. 27)• Instalar paquetes AWSSDK con NuGet (p. 29)• Instalar ensamblados AWSSDK sin NuGet (p. 31)• Configuración avanzada para suAWS SDK for .NETProyecto de (p. 32)
Inicio de un nuevo proyectoHay varias técnicas que puede utilizar para iniciar un nuevo proyecto para acceder aAWSServicios de .Estas son algunas de esas técnicas:
• Si es la vez que utiliza el desarrollo .NET enAWSo al menos nuevo en elAWS SDK for .NET, puede verejemplos completos enInicio rápido (p. 5). Le da una introducción al SDK.
• Puede iniciar un proyecto básico utilizando la CLI de .NET. Para ver un ejemplo de esto, abra un símbolodel sistema o terminal, cree una carpeta o directorio, acceda al mismo y, a continuación, escriba losiguiente.
dotnet new console --name [SOME-NAME]
17
AWS SDK for .NET Developer GuideCrear usuarios y roles
Se crea un proyecto vacío al que puede agregar código y paquetes NuGet. Para obtener másinformación, consulte la Guía de .NET Core.
Para ver una lista de plantillas de proyecto, utilice lo siguiente:dotnet new --list
• AWS Toolkit for Visual Studio incluye plantillas de proyecto de C# para una serie de servicios de AWS.Después de tiInstalar el conjunto de herramientasEn Visual Studio, puede tener acceso a las plantillasmientras crea un nuevo proyecto.
Para ver esto, vaya aUso deAWSservicesen laAWS Toolkit for Visual StudioGuía del usuario. Varios delos ejemplos de esa sección crean nuevos proyectos.
• Si desarrolla con Visual Studio en Windows pero sin elAWS Toolkit for Visual Studio, use sus técnicastípicas para crear un nuevo proyecto.
Para ver un ejemplo, abra Visual Studio y elijaArchivo,New,Proyecto de. Busque «.net core» y elija laversión C # delAplicación de consola (.NET Core)orAplicación WPF (.NET Core)Plantilla de Se crea unproyecto vacío al que puede agregar código y paquetes NuGet.
Después de crear el proyecto de, realice las tareas adicionales apropiadas paraConfiguración delproyecto (p. 17).
Encontrará algunos ejemplos de cómo trabajar conAWSenUso deAWSServicios de (p. 55).
Crear usuarios y rolesComo resultado deCreación de unAWSaccount (p. 15), tiene (al menos) dos cuentas de usuario:
• Su cuenta de usuario raíz, que fue creada para usted y tiene acceso completo a todo.• Una cuenta de usuario administrativo, que creó y dio acceso completo acasitodo.
Ninguna de estas cuentas de usuario es apropiada para realizar el desarrollo.NET enAWSPara ejecutaraplicaciones .NET enAWS. Como tal, debe crear cuentas de usuario y roles de servicio que seanadecuados para estas tareas.
Las cuentas de usuario y los roles de servicio específicos que cree, así como la forma en que los utilice,dependerán de los requisitos de las aplicaciones. Los siguientes son algunos de los tipos más simples decuentas de usuario y funciones de servicio, así como información sobre por qué se pueden utilizar y cómocrearlos.
Cuentas de usuarioPuede usar una cuenta de usuario con credenciales a largo plazo para acceder aAWSa través de suaplicación. Este tipo de acceso es apropiado si un solo usuario va a utilizar su aplicación (usted, porejemplo). El escenario más común para usar este tipo de acceso es durante el desarrollo, pero otrosescenarios son posibles.
El proceso para crear un usuario varía dependiendo de la situación, pero es esencialmente el siguiente.
1. Inicie sesión en la AWS Management Console y abra la consola de IAM en https://console.aws.amazon.com/iam/.
2. Seleccione Users y, luego, Add user.3. Proporcione un nombre de usuario.
18
AWS SDK for .NET Developer GuideRoles de servicio
4. UNDERSelectAWSTipo de accesoseleccione, seleccioneAcceso programáticoHaga clic en y luegoenSiguiente: Permisos.
5. SeleccionarAsociar políticas existentes directamenteSeleccione y, a continuación, seleccionelaPolíticas adecuadaspara laAWSque usará su aplicación.
Warning
DONOelija elAdministratorAccessporque dicha directiva habilita permisos de lectura yescritura para casi todo lo que hay en su cuenta.
6. Seleccione Next (Siguiente): Tags (Etiquetas):e introduzca las etiquetas que desee.
Puede encontrar información acerca de las etiquetas enControl del acceso medianteAWSetiquetas derecursosen laGuía del usuario de IAM.
7. Seleccione Next (Siguiente): Review (Revisar)Haga clic en y luego enCreación de usuario.8. Registre las credenciales del nuevo usuario. Para ello, descargue el texto claro.csvo copiando y
pegando el archivoID de clave de accesoyclave de acceso secreta.
Estas son las credenciales que necesitará para su aplicación.Warning
Usarmedidas de seguridad apropiadasPara mantener estas credenciales seguras y rotadas.
Puede encontrar información de alto nivel acerca de los usuarios de IAM enIdentidades (usuarios, gruposy roles)en laGuía del usuario de IAM. Encuentre información detallada sobre los usuarios en laUsuarios deIAMTema.
Roles de servicioPuede configurar unAWSFunción de servicio para accederAWSservicios en nombre de los usuarios. Estetipo de acceso es adecuado si varias personas van a ejecutar la aplicación de forma remota; por ejemplo,en una instancia de Amazon EC2 que haya creado para este fin.
El proceso para crear un rol de servicio varía según la situación, pero es esencialmente el siguiente.
1. Inicie sesión en la AWS Management Console y abra la consola de IAM en https://console.aws.amazon.com/iam/.
2. Elija Roles y después Create Role (Crear rol).3. SeleccionarAWSServicio, busque y seleccioneEC2Haga clic en y luego en laEC2caso de uso (por
ejemplo).4. Seleccione Next (Siguiente): Permisosy seleccione la casillaPolíticas adecuadaspara laAWSque usará
su aplicación.Warning
DONOelija elAdministratorAccessporque dicha directiva habilita permisos de lectura yescritura para casi todo lo que hay en su cuenta.
5. Seleccione Next (Siguiente): Tags (Etiquetas):e introduzca las etiquetas que desee.
Puede encontrar información acerca de las etiquetas enControl del acceso medianteAWSetiquetas derecursosen laGuía del usuario de IAM.
6. Seleccione Next (Siguiente): Review (Revisar)Proporcionar unNombre de rolyDescripción del rol. Acontinuación, elija Create role.
Puede encontrar información de alto nivel acerca de las funciones de IAM enIdentidades (usuarios, gruposy roles)en laGuía del usuario de IAM. Encuentre información detallada sobre los roles en laIAM rolesTema.
19
AWS SDK for .NET Developer GuideConfiguraciónAWScredenciales
ConfiguraciónAWScredencialesDespués de tiCree unAWSaccount (p. 15)yCrear las cuentas de usuario requeridas (p. 18), puedeadministrar las credenciales de esas cuentas de usuario. Necesita estas credenciales para realizar muchasde las tareas y ejemplos de esta guía.
A continuación se proporciona un proceso de alto nivel para la administración y uso de credenciales.
1. Cree las credenciales que necesita:
• Puede crear credenciales cuando cree una cuenta de usuario. Consulte Cuentas deusuario (p. 18) para ver un ejemplo.
• También puede crear credenciales para una cuenta de usuario existente. ConsulteAdministración delas claves de acceso de los usuarios de IAM.
2. Almacene las credenciales (por ejemplo, en elCompartidoAWSarchivo de credenciales (p. 21)oelTienda de SDK (p. 23)).
3. Configure su proyecto para que su aplicación puedaEncuentre las credenciales (p. 25).
Los temas siguientes proporcionan información que puede utilizar para determinar cómo administrar y usarcredenciales en su entorno.
Temas• Advertencias importantes y orientación para las credenciales (p. 20)• Uso delAWSarchivo de credenciales (p. 21)• Uso de SDK Store (solo Windows) (p. 23)• Credenciales y resolución de perfiles (p. 25)
Advertencias importantes y orientación para lascredencialesAvisos de credenciales
• NO HACERUtilice las credenciales raíz de su cuenta para acceder aAWSde AWS. Estas credencialesproporcionan acceso ilimitado a la cuenta y son difíciles de revocar.
• NO HACERPonga claves de acceso literales en sus archivos de aplicación. Si lo hace, puede crear unriesgo de exposición accidental de sus credenciales si, por ejemplo, carga el proyecto en un repositoriopúblico.
• NO HACERincluir archivos que contengan credenciales en el área del proyecto.• Credenciales en uno de los mecanismos de almacenamiento de credenciales, elAWSarchivo de
credenciales, se almacenan en texto sin cifrar.
Orientación adicional para administrar credenciales de forma segura
Para consultar un debate general sobre cómo administrar de forma seguraAWScredenciales,consultePrácticas recomendadas para administrarAWSclaves de accesoen laAWSReferencia general de.Además de ese debate, tenga en cuenta lo siguiente:
• Cree usuarios de IAM y utilice sus credenciales en lugar de suAWSUsuario raíz. Las credenciales deusuario de IAM se pueden revocar si es necesario. Además, puede aplicar una política a cada usuario deIAM para obtener acceso a determinados recursos y acciones.
20
AWS SDK for .NET Developer GuideUso delAWSarchivo de credenciales
• UsarRoles de IAM para las tareasPara las tareas de Amazon Elastic Container Service (Amazon ECS).
• UsarIAM rolesPara aplicaciones que se ejecutan en instancias de Amazon EC2.
• UsarCredenciales temporales (p. 26)Para las variables de entorno para las aplicaciones disponiblespara los usuarios que se encuentran fuera de su organización.
Uso delAWSarchivo de credenciales(Asegúrese de revisar laadvertencias importantes y orientación para las credenciales (p. 20).)
Una forma de proporcionar credenciales para sus aplicaciones es crear perfiles enelCompartidoAWSarchivo de credencialesy, a continuación, almacenar credenciales en esos perfiles. Estearchivo puede ser utilizado por los otrosAWSSDK. También puede ser utilizado por laAWS CLI, elAWSTools for Windows PowerShell, y elAWSConjunto de herramientas de paraVisual Studio,JetBrains, yCódigode VS.
Información generalDe forma predeterminada, elAWSEl archivo de credenciales se encuentra en el archivo.awsDirectoriode su directorio principal y se llamacredentials; es decir,~/.aws/credentials(Linux o macOS)o%USERPROFILE%\.aws\credentials(Windows). Para obtener más información acerca de ubicacionesalternativas, consulteUbicación de los archivos compartidosen laAWSGuía de referencia de SDK yherramientas. Consulte también Acceso a credenciales y perfiles en una aplicación (p. 172).
El compartidoAWSarchivo de credenciales es un archivo de texto no cifrado y sigue un formatodeterminado. Para obtener más información sobre el formato deAWSarchivos de credenciales,consulteFormato del archivo de credencialesen laAWSGuía de referencia de SDK y herramientas.
Puede administrar los perfiles en laAWSarchivo de credenciales de varias maneras.
• Utilice cualquier editor de texto para crear y actualizar laAWSarchivo de credenciales.• UsarAmazon.runtime.CredentialManagementEl espacio de nombresAWS SDK for .NETAPI, como se
muestra más adelante en este tema.• Utilice comandos y procedimientos para elAWS Tools for PowerShelly laAWSConjunto de herramientas
de paraVisual Studio,JetBrains, yCódigo VS.• UsarAWS CLIcomandos; por ejemplo,aws configure set aws_access_key_idyaws configureset aws_secret_access_key.
Ejemplos de gestión de perfilesEn las secciones siguientes se muestran ejemplos de perfiles en laAWSarchivo de credenciales. Algunosde los ejemplos muestran el resultado, que se puede obtener a través de cualquiera de los métodos deadministración de credenciales descritos anteriormente. En otros ejemplos, se muestra cómo se utiliza unmétodo determinado.
El perfil predeterminado
El compartidoAWScasi siempre tendrá un perfil llamadopredeterminada. Aquí es donde elAWS SDKfor .NETbusca credenciales si no se han definido otros perfiles.
La[default]El perfil de suele tener un aspecto parecido al siguiente.
21
AWS SDK for .NET Developer GuideUso delAWSarchivo de credenciales
[default]aws_access_key_id = AKIAIOSFODNN7EXAMPLEaws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Crear un perfil de
En este ejemplo se muestra cómo crear un perfil de y guardarlo en laAWSarchivo de credencialesmediante programación. utiliza las siguientes clases de laAmazon.runtime.CredentialManagementespaciode nombres: CredentialProfileOptions,CredentialProfile, ySharedCredentialsFile.
using Amazon.Runtime.CredentialManagement;...
// For illustrative purposes only--do not include credentials in your code.WriteProfile("my_new_profile", "AKIAIOSFODNN7EXAMPLE", "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY");...
void WriteProfile(string profileName, string keyId, string secret){ Console.WriteLine($"Create the [{profileName}] profile..."); var options = new CredentialProfileOptions { AccessKey = keyId, SecretKey = secret }; var profile = new CredentialProfile(profileName, options); var sharedFile = new SharedCredentialsFile(); sharedFile.RegisterProfile(profile);}
Warning
Código como este generalmente no debería estar en su aplicación. Si lo incluye en su aplicación,tome las precauciones apropiadas para asegurarse de que las claves de texto sin formato no sepuedan ver en el código, a través de la red o incluso en la memoria de la computadora.
El siguiente es el perfil creado por este ejemplo.
[my_new_profile]aws_access_key_id=AKIAIOSFODNN7EXAMPLEaws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Actualización de un perfil existente mediante programación
En este ejemplo se muestra cómo actualizar mediante programación el perfil creado anteriormente.utiliza las siguientes clases de laAmazon.runtime.CredentialManagementespacio de nombres:CredentialProfileySharedCredentialsFile. También utiliza elRegionEndpointLa claseAmazonespacio denombres.
using Amazon.Runtime.CredentialManagement;...
AddRegion("my_new_profile", RegionEndpoint.USWest2);...
void AddRegion(string profileName, RegionEndpoint region){ var sharedFile = new SharedCredentialsFile();
22
AWS SDK for .NET Developer GuideUso de SDK Store (solo Windows)
CredentialProfile profile; if (sharedFile.TryGetProfile(profileName, out profile)) { profile.Region = region; sharedFile.RegisterProfile(profile); }}
El siguiente es el perfil actualizado.
[my_new_profile]aws_access_key_id=AKIAIOSFODNN7EXAMPLEaws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEYregion=us-west-2
Note
También puede configurar elAWSRegión en otras ubicaciones y mediante el uso de otrosmétodos. Para obtener más información, consulte Configuración delAWSRegión (p. 27).
Uso de SDK Store (solo Windows)(Asegúrese de revisar laadvertencias y directrices importantes (p. 20).)
En Windows, elTienda de SDKes otro lugar para crear perfiles y almacenar credenciales cifradas parasuAWS SDK for .NETrevisiones de. Se encuentra en%USERPROFILE%\AppData\Local\AWSToolkit\RegisteredAccounts.json. Puede usar el SDK Store durante el desarrollo como una alternativaalCompartidoAWSarchivo de credenciales (p. 21).
Información generalSDK Store proporciona los siguientes beneficios:
• Las credenciales del SDK Store se cifran y el SDK Store reside en el directorio de inicio del usuario. Estolimita el riesgo de exposición accidental de sus credenciales.
• El almacén de SDK también proporciona credenciales a laAWS Tools for Windows PowerShelly laAWSToolkit for Visual Studio.
Los perfiles de almacén de SDK son específicos de un usuario determinado de un host concreto. No puedecopiarlos en otros hosts ni en otros usuarios. Esto significa que no puede volver a usar los perfiles detienda de SDK que se encuentran en su equipo de desarrollo para otros hosts o equipos de desarrollador.También significa que no puede usar perfiles de SDK Store en aplicaciones de producción.
Puede administrar los perfiles en la tienda de SDK de las siguientes formas:
• Utilice la interfaz de usuario gráfica (GUI) en laAWS Toolkit for Visual Studio.• UsarAmazon.runtime.CredentialManagementEl espacio de nombresAWS SDK for .NETAPI, como se
muestra más adelante en este tema.• Utilice los comandos de laAWS Tools for Windows PowerShell; por ejemplo,Set-AWSCredentialyRemove-AWSCredentialProfile.
Ejemplos de gestión de perfilesEn los siguientes ejemplos se muestra cómo crear y actualizar un perfil en el almacén de SDK.
23
AWS SDK for .NET Developer GuideUso de SDK Store (solo Windows)
Crear un perfil deEste ejemplo muestra cómo crear un perfil y almacenarlo en el SDK Store mediante programación.utiliza las siguientes clases de laAmazon.runtime.CredentialManagementespacio de nombres:CredentialProfileOptions,CredentialProfile, yNetSDKCredentialsFile.
using Amazon.Runtime.CredentialManagement;...
// For illustrative purposes only--do not include credentials in your code.WriteProfile("my_new_profile", "AKIAIOSFODNN7EXAMPLE", "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY");...
void WriteProfile(string profileName, string keyId, string secret){ Console.WriteLine($"Create the [{profileName}] profile..."); var options = new CredentialProfileOptions { AccessKey = keyId, SecretKey = secret }; var profile = new CredentialProfile(profileName, options); var netSdkStore = new NetSDKCredentialsFile(); netSdkStore.RegisterProfile(profile);}
Warning
Código como este generalmente no debería estar en su aplicación. Si está incluido en laaplicación, tome las precauciones apropiadas para asegurarse de que las claves de textosin formato no se puedan ver en el código, a través de la red o incluso en la memoria de lacomputadora.
El siguiente es el perfil creado por este ejemplo.
"[generated GUID]" : { "AWSAccessKey" : "01000000D08...[etc., encrypted access key ID]", "AWSSecretKey" : "01000000D08...[etc., encrypted secret access key]", "ProfileType" : "AWS", "DisplayName" : "my_new_profile",}
Actualización de un perfil existente mediante programaciónEn este ejemplo se muestra cómo actualizar mediante programación el perfil creado anteriormente.utiliza las siguientes clases de laAmazon.runtime.CredentialManagementespacio de nombres:CredentialProfileyNetSDKCredentialsFile. También utiliza elRegionEndpointLa claseAmazonespacio denombres.
using Amazon.Runtime.CredentialManagement;...
AddRegion("my_new_profile", RegionEndpoint.USWest2);...
void AddRegion(string profileName, RegionEndpoint region){ var netSdkStore = new NetSDKCredentialsFile(); CredentialProfile profile; if (netSdkStore.TryGetProfile(profileName, out profile))
24
AWS SDK for .NET Developer GuideCredenciales y resolución de perfiles
{ profile.Region = region; netSdkStore.RegisterProfile(profile); }}
El siguiente es el perfil actualizado.
"[generated GUID]" : { "AWSAccessKey" : "01000000D08...[etc., encrypted access key ID]", "AWSSecretKey" : "01000000D08...[etc., encrypted secret access key]", "ProfileType" : "AWS", "DisplayName" : "my_new_profile", "Region" : "us-west-2"}
Note
También puede configurar elAWSRegión en otras ubicaciones y mediante el uso de otrosmétodos. Para obtener más información, consulte Configuración delAWSRegión (p. 27).
Credenciales y resolución de perfilesLaAWS SDK for .NETBusca credenciales en un determinado orden y usa el primer conjunto disponiblepara la aplicación actual.
Note
La información de este tema sobre el perfil y la precedencia de credenciales se centra en .NETCore y ASP.NET Core, y es diferente de la información similar para .NET Framework.Además, la información sobre la especificación de perfiles mediante mecanismos de.NETFramework, comoApp.configyWeb.configno se aplica a .NET Core y, por lo tanto, no estápresente.Si está buscando información de.NET Framework, consulteversión 3de la guía en su lugar.
Orden de búsqueda de credenciales
1. Credenciales que se establecen explícitamente en laAWScliente de servicio, como se describeenAcceso a credenciales y perfiles en una aplicación (p. 172).
Note
Ese tema se encuentra en elConsideraciones especiales (p. 171)porque no es el métodopreferido para especificar credenciales.
2. Un perfil de credenciales con el nombre especificado por un valor enawsConfigs.awsProfileName.3. Un perfil de credenciales con el nombre especificado por laAWS_PROFILEvariable de entorno.4. El perfil de credenciales [default].5. SessionawScredentialsque se crean a partir de laAWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEY,
yAWS_SESSION_TOKEN, si no están todas vacías.6. BasicAWSCredentialsque se crean a partir de laAWS_ACCESS_KEY_IDyAWS_SECRET_ACCESS_KEY, si
no están ambas vacías.7. Roles de IAM para las tareaspara las tareas de Amazon ECS.8. Metadatos de la instancia de Amazon EC2.
Si su aplicación se ejecuta en una instancia de Amazon EC2, como un entorno de producción, use un rolde IAM como se describe enConceder acceso mediante un rol de IAM (p. 115). De lo contrario, almacene
25
AWS SDK for .NET Developer GuideCredenciales y resolución de perfiles
sus credenciales en un archivo que use elAWSFormato de archivo de credenciales al que su aplicaciónweb tenga acceso en el servidor.
Resolución del perfilCon dos mecanismos de almacenamiento diferentes para las credenciales, es importante entender cómoconfigurar elAWS SDK for .NETPara utilizarlas. LaawsConfigs.awsProfilesLocationcontrola cómo lapropiedadAWS SDK for .NETbusca perfiles de credenciales.
AWSProfilesLocation Comportamiento de la resolución
null (no establecido) o vacío Busque en el SDK Store si la plataformalo admite y, a continuación, busque enelAWSarchivo de credenciales en elubicaciónpredeterminada (p. 21). Si no está en ningunade esas ubicaciones, busque en~/.aws/config(Linux o macOS) o%USERPROFILE%\.aws\config(Windows).
La ruta a un archivo en elAWSFormato de archivode credenciales
Busque solo en el archivo especificado el perfil conel nombre indicado.
Uso de credenciales de cuenta de usuario federadoLas aplicaciones que utilizan elAWS SDK for .NET(AWSSDK.CoreLas versiones 3.1.6.0 y posterior)pueden usar cuentas de usuario federado a través de Servicios de federación de Active Directory (AD FS)para obtener acceso aAWSUso de lenguaje de marcado de aserción de seguridad (SAML).
La compatibilidad del acceso federado significa que los usuarios pueden autenticarse mediante su ActiveDirectory. Las credenciales temporales se conceden al usuario automáticamente. Estas credencialestemporales, que son válidas durante una hora, se usan cuando su aplicación invocaAWSServicios de .El SDK gestiona la administración de las credenciales temporales. Para las cuentas de usuario unidas aun dominio, si su aplicación realiza una llamada, pero las credenciales han caducado, el usuario vuelve aautenticarse automáticamente y se conceden credenciales actualizadas (para las cuentas que no unidas aun dominio, se le pide al usuario que escriba las credenciales antes de la segunda autenticación).
Para usar este soporte en su aplicación de .NET, primero debe configurar el perfil de rol medianteun cmdlet de PowerShell. Para obtener más información, consulte laAWS Tools for WindowsPowerShellDocumentación de.
Después de configurar el perfil de rol, haga referencia al perfil en la aplicación. Hay una serie de formas dehacerlo, una de las cuales es usando elawsConfigs.awsProfileNameDe la misma manera que lo haría conotros perfiles de credenciales.
LaAWS Security Token ServiceAssemblyawssdk.SecurityToken) proporciona el soporte de SAML paraobtenerAWSCredenciales de . Para usar credenciales de cuenta de usuario federado, asegúrese de queeste ensamblado está disponible para su aplicación.
Especificación de roles o credenciales temporalesPara las aplicaciones que se ejecutan en instancias de Amazon EC2, el modo más seguro deadministrar credenciales es usar roles de IAM, como se describe enConceder acceso mediante un rol deIAM (p. 115).
Para los escenarios de aplicación en los que el software ejecutable está disponible para los usuariosexternos a su organización, recomendamos que diseñe el software para usarcredenciales de seguridadtemporales. Además de proporcionar acceso restringido aAWSEstas credenciales tienen el beneficio de
26
AWS SDK for .NET Developer GuideConfiguración delAWSRegión
caducar después de un período de tiempo especificado. Para obtener más información sobre cómo usarcredenciales de seguridad temporales, consulte lo siguiente:
• Credenciales de seguridad temporales• Grupos de identidad de Amazon Cognito
Uso de credenciales de proxySi su software se comunica conAWSA través de un proxy, puede especificar las credenciales para elproxy mediante laProxyCredentialsLa propiedadConfigde un servicio. LaConfigde un serviciosuele formar parte del espacio de nombres principal del servicio. Algunos ejemplos son los siguientes:AmazonCloudDirectoryConfigen laAmazon.cloudDirectoryespacio de nombres yAmazonGameLiftConfigenlaAmazon.GameLiftespacio de nombres.
ParaAmazon S3Por ejemplo, podría usar código similar al siguiente, donde {my-username}y {my-password} son el nombre de usuario y la contraseña del proxy especificados enunNetworkCredentialObjeto.
AmazonS3Config config = new AmazonS3Config();config.ProxyCredentials = new NetworkCredential("my-username", "my-password");
Note
Las versiones anteriores del SDK usaban ProxyUsername y ProxyPassword, pero estaspropiedades están obsoletas.
Configuración delAWSRegiónAWSLas regiones le permiten acceder aAWSLos servicios que se ubican físicamente en una regióngeográfica determinada. Esto puede ser útil para evitar redundancias y para que sus datos y aplicacionesse ejecuten cerca del lugar desde donde accederá a ellos usted y sus usuarios.
Para ver la lista actual de todas las regiones y puntos de enlace compatibles para cadaAWS,consulteCuotas y puntos de enlace de servicioen laAWSReferencia general de. Para ver una lista de losextremos regionales existentes, consulteAWSPuntos de enlace de los servicios de. Para ver informacióndetallada acerca de las regiones, consulteAdministraciónAWSRegiones de.
Puede crear unaAWScliente de servicio que va a unRegión en particular (p. 27). También puedeconfigurar su aplicación con una Región que se utilizará paraTodoAWSClientes de servicio (p. 28).Estos dos casos se explican a continuación.
Crear un cliente de servicio con una regióndeterminadaPuede especificar la región para cualquiera de losAWSen su aplicación. La configuración de la región deesta manera prevalece sobre cualquier configuración global para ese cliente de servicio en particular.
Región existenteEn este ejemplo puede ver cómo crear una instancia deCliente de Amazon EC2en una región existente.Utiliza definidoRegionEndpoint.
using (AmazonEC2Client ec2Client = new AmazonEC2Client(RegionEndpoint.USWest2))
27
AWS SDK for .NET Developer GuideEspecificar una región para todos los clientes de servicio
{ // Make a request to EC2 in the us-west-2 Region using ec2Client}
Nueva región usando la clase RegionEndPointEn este ejemplo puede ver cómo construir un nuevo punto de enlace de regiónmedianteRegionEndPoint.GetBySystemName.
var newRegion = RegionEndpoint.GetBySystemName("us-west-new");using (var ec2Client = new AmazonEC2Client(newRegion)){ // Make a request to EC2 in the new Region using ec2Client}
Nueva región mediante la clase de configuración del cliente deservicioEn este ejemplo puede ver cómo utilizar laServiceURLLa propiedad de la clase de configuración delcliente de servicio para especificar la región; en este caso, mediante laConfig de Amazonec2La clase.
Esta técnica funciona incluso si el punto de enlace de la región no sigue el patrón de punto de enlace de laregión habitual.
var ec2ClientConfig = new AmazonEC2Config{ // Specify the endpoint explicitly ServiceURL = "https://ec2.us-west-new.amazonaws.com"};
using (var ec2Client = new AmazonEC2Client(ec2ClientConfig)){ // Make a request to EC2 in the new Region using ec2Client}
Especificar una región para todos los clientes deservicioPuede especificar una región para todos losAWSque crea su aplicación. Esta región se utiliza para clientesde servicio que no se crean con una región determinada.
LaAWS SDK for .NETbuscará un valor de región en el orden que se indica a continuación.
ProfilesEstablezca un perfil que su aplicación o el SDK haya cargado. Para obtener más información, consulteCredenciales y resolución de perfiles (p. 25).
Variables de entornoEstablezca en elAWS_REGIONLa variable de entorno.
En Linux o macOS:
AWS_REGION='us-west-2'
28
AWS SDK for .NET Developer GuideNueva información acerca de la región de China (Pekín)
En Windows:
set AWS_REGION=us-west-2
Note
Si establece esta variable de entorno para todo el sistema (usandoexportorsetx), afecta a todoslos SDK y kits de herramientas, no solo alAWS SDK for .NET.
Clase AWSConfigsEstablecer comoawsConfigs.awsRegionpropiedad.
AWSConfigs.AWSRegion = "us-west-2";using (var ec2Client = new AmazonEC2Client()){ // Make request to Amazon EC2 in us-west-2 Region using ec2Client}
Nueva información acerca de la región de China(Pekín)Para utilizar servicios en la región de China (Pekín), debe disponer de una cuenta y de credencialesespecíficas de la región de China (Pekín). Cuentas y credenciales de otrosAWSLas regiones nofuncionarán en la región de China (Pekín). De igual modo, las cuentas y las credenciales de la región deChina (Pekín) no funcionarán en otrosAWSRegiones. Para obtener más información acerca de los puntosde enlace y los protocolos disponibles en la región de China (Pekín), consulte la sección sobre la regiónChina (Pekín).
Nueva información acerca deAWSServicios deNewAWSLos servicios se pueden lanzar inicialmente en algunas regiones y ser compatibles más adelanteen otras regiones. En estos casos, no es necesario instalar el último SDK para acceder a las nuevasregiones para ese servicio. Puede especificar las regiones que se han agregado recientemente para cadacliente o de forma global, como se muestra anteriormente.
Instalar paquetes AWSSDK con NuGetNuGet es un sistema de administración de paquetes de la plataforma .NET. Con NuGet, puede instalarelPaquetes AWSSDK, así como varias otras extensiones, a su proyecto. Para obtener informaciónadicional, consulte elaws/dotnetEn el sitio web de GitHub.
NuGet dispone siempre de las versiones más recientes de los paquetes AWSSDK, así como versionesanteriores. NuGet tiene en cuenta las dependencias entre los paquetes e instala todos los paquetesnecesarios de forma automática.
Warning
La lista de paquetes NuGet puede incluir uno llamado simplemente «AWSSDK» (sin identificadoradjunto). NO instale este paquete NuGet; es heredado y no debe usarse para nuevos proyectos.
Los paquetes instalados con NuGet se almacenan en su proyecto en lugar de en una ubicación central. Deeste modo podrá instalar versiones de ensamblados específicos de una aplicación determinada sin que
29
AWS SDK for .NET Developer GuideUso de NuGet desde el símbolo del sistema o terminal
se generen problemas de compatibilidad con otras aplicaciones. Para obtener más información acerca deNuGet, consulte la documentación de NuGet.
Uso de NuGet desde el símbolo del sistema o terminal1. Acceda alPaquetes AWSSDK en NuGety determine qué paquetes necesita en su proyecto; por
ejemplo,AWSSDK.S3.2. Copie el comando de la CLI de .NET desde la página web de ese paquete, tal y como se muestra en
el siguiente ejemplo.
dotnet add package AWSSDK.S3 --version 3.3.110.19
3. En el directorio de su proyecto, ejecute ese comando de la CLI de .NET. NuGet también instalacualquier dependencia, como por ejemplo AWSSDK.Core.
Note
Si sólo desea la versión más reciente de un paquete NuGet, puede excluir la información deversión del comando, como se muestra en el siguiente ejemplo.dotnet add package AWSSDK.S3
Uso de NuGet desde el Explorador de solucionesVisual Studio1. En el Explorador de soluciones, haga clic con el botón derecho en el proyecto y, a continuación, elija
Manage NuGet Packages ((Administrar paquetes NuGet) en el menú contextual.2. En el panel izquierdo del NuGet Package Manager (Administrador de paquetes NuGet), elija Browse
(Examinar). A continuación, puede utilizar el cuadro de búsqueda para buscar el paquete que deseainstalar.
La figura siguiente muestra la instalación deAWSSDK.S3Creación de paquetes. NuGet también instalacualquier dependencia, como por ejemplo AWSSDK.Core.
30
AWS SDK for .NET Developer GuideUso de NuGet desde la Consoladel administrador de paquetes
Uso de NuGet desde la Consola del administrador depaquetesEn Visual Studio, elijaHerramientas,Administrador de paquetes NuGet,Consola del administrador depaquetes.
Puede instalar los paquetes AWSSDK que desee desde la Consola del administrador de paquetesutilizando elInstall-PackageComando de la Por ejemplo, para instalar AWSSDK.S3, utilice el siguientecomando.
PM> Install-Package AWSSDK.S3
NuGet también instala cualquier dependencia, como por ejemplo AWSSDK.Core.
Si necesita instalar una versión previa de un paquete, utilice el-Versiony especifique la versión delpaquete que desea, tal y como se muestra en el siguiente ejemplo.
PM> Install-Package AWSSDK.S3 -Version 3.3.106.6
Para obtener más información acerca de los comandos de la consola del Administrador de paquetes,consulte laReferencia de PowerShellEn elDocumentación de NuGet.
Instalar ensamblados AWSSDK sin NuGetEn este tema se describe cómo puede utilizar los ensamblados AWSSDK que obtuvo yalmacenó localmente (o en las instalaciones) como se describe enObtención de ensamblados deAWSSDK (p. 171). Esto esnoel método recomendado para manejar referencias de SDK, pero esnecesario en algunos entornos.
Note
El método recomendado para manejar referencias de SDK es descargar e instalar solo lospaquetes NuGet que cada proyecto necesita. Ese método se describe enInstalar paquetesAWSSDK con NuGet (p. 29).
Para instalar ensamblados AWSSDK
1. Cree una carpeta en el área de proyecto para los ensamblajes AWSSDK requeridos. Como ejemplo,podría llamar a esta carpetaAwsAssemblies.
2. Si aún no lo ha hecho,obtener los ensamblajes AWSSDK (p. 171), que coloca los ensambladosen alguna carpeta local de descarga o instalación. Copie los archivos DLL para los ensambladosrequeridos de esa carpeta de descarga en su proyecto (en elAwsAssemblies, en nuestro ejemplo).
Asegúrese de copiar también las dependencias. Puede encontrar información sobre las dependenciasen laGitHubSitio web.
3. Haga referencia a los conjuntos requeridos de la siguiente manera.
Cross-platform development
1. Abra el.csprojy agregue un archivo<ItemGroup>Elemento.2. En la<ItemGroup>elemento, agregue un<Reference>Elemento con unIncludeatributo
para cada ensamblado requerido.
Para Amazon S3, por ejemplo, debería agregar las siguientes líneas a la.csprojfile.
31
AWS SDK for .NET Developer GuideConfiguración avanzada
En Linux y macOS:
<ItemGroup> <Reference Include="./AwsAssemblies/AWSSDK.Core.dll" /> <Reference Include="./AwsAssemblies/AWSSDK.S3.dll" /></ItemGroup>
En Windows:
<ItemGroup> <Reference Include="AwsAssemblies\AWSSDK.Core.dll" /> <Reference Include="AwsAssemblies\AWSSDK.S3.dll" /></ItemGroup>
3. Guarde el proyecto.csprojfile.
Windows with Visual Studio and .NET Core
1. En Visual Studio, cargue el proyecto y abraPrevisión,Agregar referencia.2. Elija el iconoBrowseEn la parte inferior del cuadro de diálogo. Desplácese hasta la carpeta
del proyecto y la subcarpeta en la que copió los archivos DLL requeridos (AwsAssemblies,por ejemplo).
3. Seleccione todos los archivos DLL, elijaAdd, y elijaACEPTAR.4. Guarde el proyecto.
Configuración avanzada para suAWS SDKfor .NETProyecto de
Los temas de esta sección contienen información acerca de las tareas y métodos de configuraciónadicionales que pueden ser de su interés.
Temas• Uso de AWSSDK.Extensions.NETCore.Setup y la interfaz de Iconfiguration (p. 32)
Uso de AWSSDK.Extensions.NETCore.Setup y lainterfaz de Iconfiguration(Este tema se titulaba anteriormente, «Configurar elAWS SDK for .NETcon .NET Core»)
Uno de los mayores cambios en .NET Core es la eliminación deConfigurationManagery elestándarapp.configyweb.configarchivos usados con aplicaciones de .NET Framework y ASP.NET.
La configuración en .NET Core se basa en pares clave-valor establecidos por los proveedores deconfiguración. Los proveedores de configuración leen los datos de configuración en pares clave-valordesde diversos orígenes de configuración, incluidos argumentos de línea de comandos, archivos dedirectorio, variables de entorno y archivos de configuración.
Note
Para obtener más información, consulte Configuración en ASP.NET Core.
32
AWS SDK for .NET Developer GuideAWSSDK.Extensions.NETCore.Setup e Iconfiguration
Para facilitar el uso delAWS SDK for .NETCon .NET Core, puede usarelAWSSDK.Extensions.NETCore.SetupPaquete de NuGet. Como muchas bibliotecas de .NET Core, añademétodos de extensión alIConfigurationpara hacer que se obtenga elAWSconfiguración perfecta.
Uso de AWSSDK.Extensions.NETCore.SetupSupongamos que crea una aplicación ASP.NET Core Model-View-Controller (MVC), que sepuede lograr con laAplicación Web ASP.NET Coreplantilla en Visual Studio o ejecutandodotnetnew mvc ...En la CLI de .NET Core. Cuando crea una aplicación de este tipo, el constructordeStartup.csmaneja la configuración leyendo en varias fuentes de entrada de proveedores deconfiguración comoappsettings.json.
public Startup(IConfiguration configuration){ Configuration = configuration;}
Para utilizarConfigurationpara obtener el objetoAWS, primero agregueelAWSSDK.Extensions.NETCore.SetupPaquete de NuGet. A continuación, añada sus opciones alarchivo de configuración como se describe a continuación.
Los siguientes ajustes de configuración muestran ejemplos de los valores que puede añadir enel cuadro de diálogoappsettings.Development.jsonPara proporcionar un archivo en elproyectoAWSConfiguración del .
{ "AWS": { "Profile": "local-test-profile", "Region": "us-west-2" }, "SupportEmail": "[email protected]"}
Para acceder a una configuración en unCSHTML, utilice el archivoConfigurationDirectiva.
@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 obtener acceso a laAWSse establecen en el archivo a partir del código, llame almétodoGetAWSOptionsmétodo de extensión agregado aIConfiguration.
Para crear un cliente de servicio a partir de estas opciones, llame a CreateServiceClient. En elejemplo siguiente se muestra cómo crear un cliente de servicio Amazon S3. (Asegúrese de añadirelAWSSDK.S3Paquete de NuGet para su proyecto.)
var options = Configuration.GetAWSOptions();IAmazonS3 client = options.CreateServiceClient<IAmazonS3>();
También puede crear varios clientes de servicio con configuraciones incompatibles utilizando variasentradas en elappsettings.Development.jsonComo se muestra en los siguientes ejemplos en los
33
AWS SDK for .NET Developer GuideAWSSDK.Extensions.NETCore.Setup e Iconfiguration
que la configuración deservice1incluye elus-west-2Región y la configuración deservice2incluye elendpoint especialURL.
{ "service1": { "Profile": "default", "Region": "us-west-2" }, "service2": { "Profile": "default", "ServiceURL": "URL" }}
A continuación, puede obtener las opciones para un servicio específico mediante la entrada del archivoJSON. Por ejemplo, para obtener la configuración deservice1Utilice lo siguiente.
var options = Configuration.GetAWSOptions("service1");
Valores permitidos en el archivo appsettings
Los siguientes valores de configuración de la aplicación se pueden establecer en el archivoappsettings.Development.json. Los nombres de campos deben usar la forma en que se muestra.Para obtener más información sobre esta configuración, consulte laAWS.Runtime.ClientConfigClase.
• Región• Perfil• ProfilesLocation• SignatureVersion• RegionEndpoint• UseHttp• ServiceURL• AuthenticationRegion• AuthenticationServiceName• MaxErrorRetry• LogResponse• BufferSize• ProgressUpdateInterval• ResignRetries• AllowAutoRedirect• LogMetrics• DisableLogging• UseDualstackEndpoint
Inserción de dependencias de ASP.NET CoreEl paquete NuGet AWSSDK.Extensions.NETCore.Setup también se integra con un nuevo sistema deinserción de dependencias en ASP.NET Core. LaConfigureServicesen el métodoStartupLa clase esdonde se añaden los servicios MVC. Si la aplicación usa Entity Framework, también es donde se inicializa.
public void ConfigureServices(IServiceCollection services){
34
AWS SDK for .NET Developer GuideAWSSDK.Extensions.NETCore.Setup e Iconfiguration
// Add framework services. services.AddMvc();}
Note
Información general acerca de la inserción de dependencias en .NET Core está disponible enelSitio de documentación de .NET Core.
LaAWSSDK.Extensions.NETCore.SetupEl paquete NuGet agrega nuevos métodosde extensión aIServiceCollectionque puede usar para agregarAWSa la inyección dedependencia. En el código siguiente se muestra cómo agregar losAWSopciones que se leendeIConfigurationpara agregar Amazon S3 y DynamoDB a la lista de servicios. (Asegúrese de añadirelAWSSDK.S3yAWSSDK.DynamoDBv2NuGet paquetes para su proyecto.)
public void ConfigureServices(IServiceCollection services){ // Add framework services. services.AddMvc();
services.AddDefaultAWSOptions(Configuration.GetAWSOptions()); services.AddAWSService<IAmazonS3>(); services.AddAWSService<IAmazonDynamoDB>();}
Ahora, si sus controladores MVC usan IAmazonS3 o IAmazonDynamoDB como parámetros en susconstructores, el sistema de inserción de dependencias pasa esos servicios.
public class HomeController : Controller{ IAmazonS3 S3Client { get; set; }
public HomeController(IAmazonS3 s3Client) { this.S3Client = s3Client; }
...
}
35
AWS SDK for .NET Developer GuideAPI asincrónicas
Características de la AWS SDKfor .NET
En esta sección se proporciona información acerca de las características deAWS SDK for .NETque esposible que deba tener en cuenta al crear sus aplicaciones.
Asegúrese de que tienePara configurar el proyecto (p. 17)first.
Para obtener información acerca del desarrollo de software paraAWSservicios, consulteUso deAWSEnelAWS SDK for .NET (p. 55).
Temas• API asincrónicas de AWS para .NET (p. 36)• Reintentos y tiempos de espera (p. 37)• Paginators (p. 40)• Habilitación de SDK Metrics (p. 44)• Herramientas adicionales (p. 49)
API asincrónicas de AWS para .NETLaAWS SDK for .NETUsa laPatrón asíncrono basado en tareas (TAP)para su implementación asíncrona.Para obtener más información sobre TAP, consultePatrón asíncrono basado en tareas (TAP)endocs.microsoft.com.
En este tema se proporciona información general sobre cómo utilizar TAP en sus llamadas aAWSclientesde servicio.
Note
La información de este tema se centra en .NET Core y ASP.NET Core. Si mantiene el códigode.NET Framework 4.5, la información de este tema también se aplica a la implementación delSDK de.NET Framework 4.5, que también utiliza TAP.Si busca información heredada sobre cómo laAWS SDK for .NET.NET Framework 3.5,consulteversión 3de la guía en su lugar.
Los métodos asíncronos en elAWS SDK for .NETAPI son operaciones basadas enTaskLaclaseTask<TResult>Clase. Consulte docs.microsoft.com para obtener información acerca de estasclases: Clase Tarea,<TResult>Clase de tarea.
Cuando se llama a estos métodos API en su código, deben llamarse dentro de una función que se declaracon el métodoasync, tal y como se muestra en el ejemplo siguiente.
static async Task Main(string[] args){ ... // Call the function that contains the asynchronous API method. // Could also call the asynchronous API method directly from Main
36
AWS SDK for .NET Developer GuideReintentos y tiempos de espera
// because Main is declared async var response = await ListBucketsAsync(); Console.WriteLine($"Number of buckets: {response.Buckets.Count}"); ...}
// Async method to get a list of Amazon S3 buckets.private static async Task<ListBucketsResponse> ListBucketsAsync(){ ... var response = await s3Client.ListBucketsAsync(); return response;}
Como se muestra en el fragmento de código anterior, el ámbito preferido para elasyncDeclaración es ladeclaraciónMainfunción. Configuración de estaasyncgarantiza que todas las llamadas aAWSse requiereque los clientes de servicio sean asincrónicos. Si no puede declararMainpara que sea asincrónico poralguna razón, puede usar el métodoasyncpalabra clave en funciones distintas deMainA continuación sellama a los métodos API desde allí, tal y como se muestra en el siguiente ejemplo.
static void Main(string[] args){ ... Task<ListBucketsResponse> response = ListBucketsAsync(); Console.WriteLine($"Number of buckets: {response.Result.Buckets.Count}"); ...}
// Async method to get a list of Amazon S3 buckets.private static async Task<ListBucketsResponse> ListBucketsAsync(){ ... var response = await s3Client.ListBucketsAsync(); return response;}
Tenga en cuenta la especialTask<>que se necesita enMaincuando se utiliza este patrón. Además, deberáutilizar laResultmiembro de la respuesta para obtener los datos.
Puede ver ejemplos completos de llamadas asincrónicas aAWSclientes de servicio en elIniciorápido (p. 5)sección (Aplicación multiplataforma sencilla (p. 5)yAplicación sencilla basada enWindows (p. 9)) y enUso deAWSServicios de (p. 55).
Reintentos y tiempos de esperaLaAWS SDK for .NETEl le permite configurar el número de reintentos y los valores de tiempo de esperade las solicitudes HTTP aAWSServicios de . Si los valores predeterminados de los reintentos y los tiemposde espera no son adecuados para su aplicación, puede ajustarlos para sus requisitos específicos, pero esimportante comprender cómo afectará hacer esto al comportamiento de su aplicación.
Para determinar qué valores usar para los reintentos y los tiempos de espera, tenga en cuenta lo siguiente:
• ¿Cómo debería elAWS SDK for .NETy su aplicación responderá cuando la conectividad de red sedegrade o se degradeAWSservicio es inalcanzable? ¿Desea que la llamada fracase rápidamente o esadecuado que la llamada se siga reintentando en su nombre?
• ¿Es su aplicación una aplicación o sitio web que se orienta a los usuarios y que debe tener capacidad derespuesta, o se trata de una tarea de procesamiento en segundo plano con una mayor tolerancia de laslatencias más elevadas?
37
AWS SDK for .NET Developer GuideRetries
• ¿Se implementa la aplicación en una red fiable con baja latencia o se implementa en una ubicaciónremota con una conectividad poco fiable?
RetriesOverviewLaAWS SDK for .NETPuede reintentar solicitudes con errores causados por la limitación controlada dellado del servidor o por conexiones perdidas. Hay dos propiedades de las clases de configuración deservicio que puede utilizar para especificar el comportamiento de reintento de un cliente de servicio. Lasclases de configuración de servicio heredan estas propiedades del resumenAmazon.runtime.clientconfigdela claseAWS SDK for .NETReferencia de la API:
• RetryModeespecifica uno de los tres modos de reintento, que se definen en el cuadro dediálogoAmazon.runtime.requestretryModeenumeración.
El valor predeterminado de la aplicación se puede controlar mediante el comandoAWS_RETRY_MODEo lavariable de entornoretry_modeconfiguración en el archivo compartidoAWSarchivo de configuración.
• MaxErrorRetryEspecifica el número de reintentos permitidos en el nivel de cliente del servicio; el SDKreintenta la operación la cantidad especificada de veces antes de que se produzca el error y de que selance una excepción.
El valor predeterminado de la aplicación se puede controlar mediante el comandoAWS_MAX_ATTEMPTSola variable de entornomax_attemptsconfiguración en el archivo compartidoAWSarchivo de configuración.
Las descripciones detalladas de estas propiedades se pueden encontrar en elresumenAmazon.runtime.clientconfigde la claseAWS SDK for .NETReferencia de la API. Cada valordeRetryModecorresponde por defecto a un valor particular deMaxErrorRetry, como se muestra en lasiguiente tabla.
RetryMode Corresponding MaxErrorRetry(Amazon DynamoDB)
Corresponding MaxErrorRetry (allothers)
Legacy 10 4
Standard 10 2
Adaptive (experimental) 10 2
BehaviorCuando se inicia la aplicación
Cuando se inicia la aplicación, los valores predeterminados paraRetryModeyMaxErrorRetryestánconfigurados por el SDK. Estos valores predeterminados se utilizan al crear un cliente de servicio a menosque especifique otros valores.
• Si las propiedades no están establecidas en su entorno, el valor predeterminado deRetryModeestáconfigurado comoHeredadoy el valor predeterminado paraMaxErrorRetryse configura con el valorcorrespondiente de la tabla anterior.
• Si el modo de reintento se ha establecido en su entorno, ese valor se utiliza como valor predeterminadoparaRetryMode. El valor predeterminado deMaxErrorRetryse configura con el valor correspondiente
38
AWS SDK for .NET Developer GuideTimeouts
de la tabla anterior, a menos que el valor de los errores máximos también se haya establecido en suentorno (descrito a continuación).
• Si el valor de los errores máximos se ha establecido en su entorno, ese valor se utiliza como valorpredeterminado paraMaxErrorRetry. Amazon DynamoDB es la excepción a esta regla; el valorpredeterminado de DynamoDB paraMaxErrorRetryes siempre el valor de la tabla anterior.
A medida que se ejecuta la aplicación
Al crear un cliente de servicio, puede utilizar los valores predeterminadosparaRetryModeyMaxErrorRetry, como se describió anteriormente, o puede especificar otrosvalores. Para especificar otros valores, cree e incluya un objeto de configuración de serviciocomoAmazonDynamoDBConfigorAmazonSQSConfigal crear el cliente de servicio.
Estos valores no se pueden cambiar para un cliente de servicio una vez creado.
Consideraciones
Cuando se produce un reintento, la latencia de su solicitud aumenta. Debe configurar sus reintentos segúnlos límites de su aplicación para la latencia de solicitudes total y las tasas de error.
TimeoutsLaAWS SDK for .NETEl le permite configurar los valores de tiempo de espera de la solicitudo de tiempo de espera de lectura/escritura del socket en el nivel de cliente del servicio. Estosvalores se especifican en el cuadro de diálogoTimeouty laReadWriteTimeoutpropiedadesdel resumenAmazon.runtime.clientconfigClase. Estos valores se transfierencomoTimeoutyReadWriteTimeoutpropiedades de la propiedadHttpWebRequestcreados por elobjetoAWSobjeto cliente de servicio. De forma predeterminada, el valor Timeout es de 100 segundos y elvalor ReadWriteTimeout es de 300 segundos.
Cuando su red tiene una elevada latencia o existen condiciones que hacen que se reintente una operación,el uso de valores de tiempo de espera largo y un elevado número de reintentos pueden hacer que algunasoperaciones del SDK parezcan no tener capacidad de respuesta.
Note
La versión del AWS SDK for .NET que tiene como destino la biblioteca de clases portable (PCL)usa la clase HttpClient en lugar de la clase HttpWebRequest y admite únicamente la propiedadTimeout.
A continuación, se indican las excepciones sobre los valores de tiempo de espera predeterminados. Estosvalores se invalidan al establecer de forma explícita los valores de tiempo de espera.
• TimeoutyReadWriteTimeoutse establecen en los valores máximos si el método al que se llamacarga una secuencia, comoAmazons3Client.putObjectAsync (),Amazons3Client.uploadPartAsync(),amazongLacierClient.uploadArchiveAsync (), y así sucesivamente.
• Las versiones de la versiónAWS SDK for .NETque se establece .NETFrameworkTimeoutyReadWriteTimeouta los valores máximos para todoslosAmazons3ClientyAmazonGlacierClientObjetos.
• Las versiones de la versiónAWS SDK for .NETque se dirigen a la biblioteca de clasesportátil (PCL) y al conjunto de núcleos de.NETTimeoutal valor máximo para todoslosAmazons3ClientyAmazonGlacierClientObjetos.
39
AWS SDK for .NET Developer GuideExample
ExampleEn el siguiente ejemplo se muestra cómo especificarestándarEl modo de reintento, un máximo de3 reintentos, un tiempo de espera de 10 segundos y un tiempo de espera de lectura/escritura de 10segundos (si corresponde). LaAmazons3Clientse le da unAmazons3configun objeto.
var s3Client = new AmazonS3Client( new AmazonS3Config { Timeout = TimeSpan.FromSeconds(10), // NOTE: The following property is obsolete for // versions of the AWS SDK for .NET that target .NET Core. ReadWriteTimeout = TimeSpan.FromSeconds(10), RetryMode = RequestRetryMode.Standard, MaxErrorRetry = 3 });
PaginatorsAlgunoAWSrecopilan y almacenan una gran cantidad de datos, que puede recuperar utilizando lasllamadas API de laAWS SDK for .NET. Si la cantidad de datos que desea recuperar es demasiado grandepara una sola llamada a la API, puede dividir los resultados en partes más manejables mediante el usodepaginación.
Para permitirle realizar la paginación, los objetos de solicitud y respuesta para muchos clientes de servicioen el SDK proporcionan untoken de continuación(normalmente llamadoNextToken). Algunos de estosclientes de servicio también proporcionanpaginadores.
Los paginadores le permiten evitar la sobrecarga del token de continuación, que podría implicar bucles,variables de estado, múltiples llamadas API, etc. Cuando utiliza un paginador, puede recuperar datos deunAWSa través de una sola línea de código, unforeachdeclaración del bucle. Si se necesitan variasllamadas API para recuperar los datos, el paginador lo gestiona por usted.
¿Dónde encontrar paginadores?No todos los servicios proporcionan paginadores. Una forma de determinar si un servicio proporciona unpaginador para una API concreta es mirar la definición de una clase de cliente de servicio en elAWS SDKfor .NETReferencia de la API.
Por ejemplo, si examina la definición deAmazonCloudWatchLogsClient, verá unaclasePaginatorspropiedad. Esta es la propiedad que proporciona un paginador para AmazonCloudWatch Logs.
¿Qué me dan los paginadores?Los paginadores contienen propiedades que le permiten ver respuestas completas. También suelencontener una o más propiedades que le permiten acceder a las partes más interesantes de las respuestas,a las que llamaremosresultados clave.
Por ejemplo, en elAmazonCloudWatchLogsClientmencionado anteriormente, elPaginatorcontieneun objetoResponsescon la propiedad completaDescribeLogGroupsResponsede la llamada a la API.EsteResponsescontiene, entre otras cosas, una colección de los grupos de registro.
El objeto Paginator también contiene un resultado clave llamadoLogGroups. Esta propiedad contiene sólola parte de grupos de registro de la respuesta. Tener este resultado clave le permite reducir y simplificar sucódigo en muchas circunstancias.
40
AWS SDK for .NET Developer GuidePaginación síncrona frente a asincrónica
Paginación síncrona frente a asincrónicaLos paginadores proporcionan mecanismos sincrónicos y asincrónicos para la paginación. La paginaciónsíncrona está disponible en proyectos .NET Framework 4.5 (o posterior). La paginación asíncrona estádisponible en los proyectos de.NET Core.
Dado que se recomiendan operaciones asíncronas y .NET Core, el ejemplo siguiente muestra lapaginación asíncrona. La información acerca de cómo realizar las mismas tareas mediante la paginaciónsincrónica y .NET Framework 4.5 (o posterior) se muestra después del ejemplo enConsideracionesadicionales para los paginadores (p. 43).
ExampleEl siguiente ejemplo muestra cómo utilizar elAWS SDK for .NETPara mostrar una lista de grupos deregistro. Por el contrario, el ejemplo muestra cómo hacerlo con y sin paginadores. Antes de mirar el códigocompleto, que se muestra más adelante, considere los siguientes fragmentos.
Obtener grupos de registro de CloudWatch sin paginadores
// Loop as many times as needed to get all the log groups var request = new DescribeLogGroupsRequest{Limit = LogGroupLimit}; do { Console.WriteLine($"Getting up to {LogGroupLimit} log groups..."); var response = await cwClient.DescribeLogGroupsAsync(request); foreach(var logGroup in response.LogGroups) { Console.WriteLine($"{logGroup.LogGroupName}"); } request.NextToken = response.NextToken; } while(!string.IsNullOrEmpty(request.NextToken));
Obtención de grupos de registro de CloudWatch mediante paginadores
// No need to loop to get all the log groups--the SDK does it for us behind the scenes var paginatorForLogGroups = cwClient.Paginators.DescribeLogGroups(new DescribeLogGroupsRequest()); await foreach(var logGroup in paginatorForLogGroups.LogGroups) { Console.WriteLine(logGroup.LogGroupName); }
Los resultados de estos dos fragmentos son exactamente los mismos, por lo que la ventaja en el uso depaginadores se puede ver claramente.
Note
Antes de intentar compilar y ejecutar el código completo, asegúrese de tenerConfiguración delentorno (p. 15). Revise también la información deConfiguración del proyecto (p. 17).Es posible que también necesite elMicrosoft.BCL.AsyncInterfacesNuGet porque los paginadoresasíncronos usan elIAsyncEnumerable.
Completa el códigoEn esta sección se muestran las referencias relevantes y el código completo de este ejemplo.
Referencia del SDK de
Paquetes NuGet:
41
AWS SDK for .NET Developer GuideExample
• awssdk.CloudWatch
Elementos de programación:
• NamespaceAmazon.cloudWatch
ClaseAmazonCloudWatchLogsClient• NamespaceAmazon.cloudwatchlogs.model
ClaseDescribeLogGroupsRequest
ClaseDescribeLogGroupsResponse
ClaseLogGroup
Código completo
using System;using System.Threading.Tasks;using Amazon.CloudWatchLogs;using Amazon.CloudWatchLogs.Model;
namespace CWGetLogGroups{ class Program { // A small limit for demonstration purposes private const int LogGroupLimit = 3;
// // Main method static async Task Main(string[] args) { var cwClient = new AmazonCloudWatchLogsClient(); await DisplayLogGroupsWithoutPaginators(cwClient); await DisplayLogGroupsWithPaginators(cwClient); }
// // Method to get CloudWatch log groups without paginators private static async Task DisplayLogGroupsWithoutPaginators(IAmazonCloudWatchLogs cwClient) { Console.WriteLine("\nGetting list of CloudWatch log groups without using paginators..."); Console.WriteLine("------------------------------------------------------------------");
// Loop as many times as needed to get all the log groups var request = new DescribeLogGroupsRequest{Limit = LogGroupLimit}; do { Console.WriteLine($"Getting up to {LogGroupLimit} log groups..."); DescribeLogGroupsResponse response = await cwClient.DescribeLogGroupsAsync(request); foreach(LogGroup logGroup in response.LogGroups) { Console.WriteLine($"{logGroup.LogGroupName}"); } request.NextToken = response.NextToken; } while(!string.IsNullOrEmpty(request.NextToken));
42
AWS SDK for .NET Developer GuideConsideraciones adicionales para los paginadores
}
// // Method to get CloudWatch log groups by using paginators private static async Task DisplayLogGroupsWithPaginators(IAmazonCloudWatchLogs cwClient) { Console.WriteLine("\nGetting list of CloudWatch log groups by using paginators..."); Console.WriteLine("-------------------------------------------------------------");
// Access the key results; i.e., the log groups // No need to loop to get all the log groups--the SDK does it for us behind the scenes Console.WriteLine("\nFrom the key results..."); Console.WriteLine("------------------------"); IDescribeLogGroupsPaginator paginatorForLogGroups = cwClient.Paginators.DescribeLogGroups(new DescribeLogGroupsRequest()); await foreach(LogGroup logGroup in paginatorForLogGroups.LogGroups) { Console.WriteLine(logGroup.LogGroupName); }
// Access the full response // Create a new paginator, do NOT reuse the one from above Console.WriteLine("\nFrom the full response..."); Console.WriteLine("--------------------------"); IDescribeLogGroupsPaginator paginatorForResponses = cwClient.Paginators.DescribeLogGroups(new DescribeLogGroupsRequest()); await foreach(DescribeLogGroupsResponse response in paginatorForResponses.Responses) { Console.WriteLine($"Content length: {response.ContentLength}"); Console.WriteLine($"HTTP result: {response.HttpStatusCode}"); Console.WriteLine($"Metadata: {response.ResponseMetadata}"); Console.WriteLine("Log groups:"); foreach(LogGroup logGroup in response.LogGroups) { Console.WriteLine($"\t{logGroup.LogGroupName}"); } } } }}
Consideraciones adicionales para los paginadores• Los paginadores no se pueden usar más de una vez
Si necesita los resultados de unAWSpaginador en varias ubicaciones de su código, nodebe usar un objeto paginador más de una vez. En su lugar, cree un paginador nuevocada vez que lo necesite. Este concepto se muestra en el ejemplo anterior de código enlaDisplayLogGroupsWithPaginatorsMétodo de.
• Paginación síncrona
La paginación síncrona está disponible para proyectos .NET Framework 4.5 (o posterior).
Para ver esto, cree un proyecto de.NET Framework 4.5 (o posterior) y copie el código anterior en él. Acontinuación, simplemente elimine elawaitPalabra clave de los dosforeachLas llamadas paginadoras,tal y como se muestra en el ejemplo siguiente.
43
AWS SDK for .NET Developer GuideHabilitación de SDK Metrics
/*await*/ foreach(var logGroup in paginatorForLogGroups.LogGroups){ Console.WriteLine(logGroup.LogGroupName);}
Cree y ejecute el proyecto para ver los mismos resultados que vio con la paginación asíncrona.
Habilitación de SDK MetricsAWS SDK Metrics for Enterprise Support(SDK Metrics) permite a los clientes de Enterprise recopilarmétricas deAWSSDK en sus hosts y clientes compartidos conAWSpara Enterprise Support SDK Metricsproporciona información que ayuda a acelerar la detección y el diagnóstico de los problemas que seproducen en las conexiones conAWSparaAWSpara Enterprise Support
A medida que la telemetría se recopila en cada host, se transmite a través de UDP a 127.0.0.1 (tambiénconocido como localhost), donde el agente de Amazon CloudWatch agrega los datos y los envía al serviciode SDK Metrics. Por lo tanto, para recibir métricas, es necesario que el agente de CloudWatch se añada asu instancia.
Los siguientes pasos para configurar las métricas del SDK corresponden a una instancia de Amazon EC2que ejecuta Amazon Linux para una aplicación cliente que utilizaAWS SDK for .NET. SDK Metrics tambiénestá disponible para sus entornos de producción si lo habilita mientras configuraAWS SDK for .NET.
Para utilizar SDK Metrics, ejecute la última versión del agente de CloudWatch. Obtenga informaciónsobre cómoConfigurar el agente de CloudWatch para métricas del SDKen la guía del usuario de AmazonCloudWatch.
Para configurar las métricas de SDK con elAWS SDK for .NET, siga estas instrucciones:
1. Cree una aplicación con un cliente de AWS SDK for .NET para utilizar un servicio de AWS.2. Aloje el proyecto en una instancia de Amazon EC2 o en su entorno local.3. Instale y utilice la versión más reciente del AWS SDK for .NET.4. Instale y configure un agente de CloudWatch en una instancia EC2 o en su entorno local.5. Autorice a SDK Metrics a que recopile y envíe métricas.6. Habilite las métricas del SDK paraAWS SDK for .NET (p. 44).
Para obtener más información, consulte los siguientes temas:
• Actualizar un agente de CloudWatch (p. 45)• Deshabilitación de SDK Metrics (p. 46)
Habilite las métricas del SDK paraAWS SDK for .NETDe forma predeterminada, SDK Metrics está desactivado y el puerto está configurado en 31000. Lossiguientes son los parámetros predeterminados.
//default values [ 'enabled' => false, 'port' => 31000,
44
AWS SDK for .NET Developer GuideActualizar un agente de CloudWatch
]
La habilitación de SDK Metrics es independiente de la configuración de sus credenciales parautilizarAWSServicio
Puede habilitar las métricas del SDK estableciendo variables de entorno o usandoAWSarchivo deconfiguración compartida.
Opción 1: Configuración de las variables de entornoSiAWS_CSM_ENABLEDEn primer lugar, el SDK verifica el perfil especificado en la variable de entornoenAWS_PROFILEpara determinar si las métricas de SDK están habilitadas. De forma predeterminada, seestablece en false.
Para activar las métricas del SDK, añada lo siguiente a las variables de entorno.
export AWS_CSM_ENABLED=true
Hay otras opciones de configuración (p. 45) disponibles.
Note
La habilitación de SDK Metrics no configura sus credenciales para utilizarAWSServicio
Opción 2:AWSarchivo de configuración compartidaSi no se encuentra ninguna configuración de SDK Metrics en las variables de entorno, el SDKbuscaAWSCampo de perfil. Si AWS_DEFAULT_PROFILE se configura de forma distinta a lapredeterminada, actualice ese perfil. Para habilitar SDK Metrics, añada csm_enabled al archivo deconfiguración compartida que se encuentra en ~/.aws/config.
[default]csm_enabled = true
[profile aws_csm]csm_enabled = true
Hay otras opciones de configuración (p. 45) disponibles.
Note
La habilitación de SDK Metrics es independiente de la configuración de sus credenciales parautilizarAWSServicio Puede utilizar un perfil diferente para la autenticación.
Actualizar un agente de CloudWatchPara realizar cambios en el puerto, debe establecer los valores y, a continuación, reiniciarAWSLos trabajosque están activos actualmente.
Opción 1: Configuración de las variables de entornoLa mayoría de los servicios utilizan el puerto predeterminado. Pero si el servicio requiere un ID de puertoúnico, añada AWS_CSM_PORT=[número_de_puerto], a las variables de entorno del host.
export AWS_CSM_ENABLED=true
45
AWS SDK for .NET Developer GuideDeshabilitación de SDK Metrics
export AWS_CSM_PORT=1234
Opción 2:AWSarchivo de configuración compartidaLa mayoría de los servicios utilizan el puerto predeterminado. Pero si su servicio requiere un ID de puertoúnico, añada csm_port =[número_de_puerto] a ~/.aws/config.
[default]csm_enabled = falsecsm_port = 1234
[profile aws_csm]csm_enabled = falsecsm_port = 1234
Reinicie las métricas del SDKPara reiniciar un trabajo, ejecute los siguientes comandos.
amazon-cloudwatch-agent-ctl –a stop;amazon-cloudwatch-agent-ctl –a start;
Deshabilitación de SDK MetricsPara desactivar las métricas de SDK, establezcaHabilite csm_enabledDe afalseen sus variables deentorno, o en suAWSarchivo de configuración compartida ubicado en~/.aws/config. A continuación,reinicie su agente de CloudWatch para que los cambios puedan surtir efecto.
Variables de entorno
export AWS_CSM_ENABLED=false
AWS archivo de configuración compartida
RemoveHabilite csm_enabledde los perfiles de suAWSarchivo de configuración compartida ubicadoen~/.aws/config.
Note
Las variables de entorno invalidanAWSarchivo de configuración compartida. Si SDK Metrics estáhabilitado en las variables de entorno, las métricas del SDK permanecen habilitadas.
[default]csm_enabled = false
[profile aws_csm]csm_enabled = false
Para deshabilitar las métricas del SDK, utilice el comando siguiente para detener el agente de CloudWatch.
sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a stop &&echo "Done"
Si utiliza otras características de CloudWatch, reinicie CloudWatch con el comando siguiente.
46
AWS SDK for .NET Developer GuideDefiniciones para métricas del SDK
amazon-cloudwatch-agent-ctl –a start;
Reinicie las métricas del SDKPara reiniciar un trabajo, ejecute los siguientes comandos.
amazon-cloudwatch-agent-ctl –a stop;amazon-cloudwatch-agent-ctl –a start;
Definiciones para métricas del SDKPuede utilizar las siguientes descripciones de SDK Metrics para interpretar los resultados. En general,estas métricas están disponibles para que las revise con el director de cuentas técnicas durante lasrevisiones de negocio periódicas.AWS Los recursos de AWS Support y el director técnico de cuentasdeben tener acceso a los datos de SDK Metrics para ayudarle a resolver los casos, pero si encuentra datosque son confusos o inesperados, aunque no parezca que afectan negativamente al rendimiento de susaplicaciones, es mejor examinarlos durante Opiniones.
Métrica CallCount
Definición Número total de llamadas a la API realizadascorrectamente o con errores desde el códigoaAWSservices
Modo de uso Utilícela como línea de referencia paracorrelacionarla con otras métricas como errores olimitación controlada.
Métrica ClientErrorCount
Definición Número de llamadas a la API que se realizaronincorrectamente con errores del cliente (códigosde respuesta HTTP 4xx). Ejemplos: El límite, elacceso denegado, el bucket de S3 no existe y elvalor de parámetro no válido.
Modo de uso Excepto en ciertos casos relacionados conla limitación controlada (por ejemplo, cuandose produce debido a un límite que se debeincrementar) esta métrica puede indicar algo en suaplicación que se debe solucionar.
Métrica ConnectionErrorCount
Definición Número de llamadas a la API que no se realizancorrectamente debido a errores de conexióncon el servicio. Estos errores pueden deberse aproblemas de red entre la aplicación del clienteyAWSServicios de, incluidos los balanceadores decarga, errores de DNS y proveedores de tránsito.En algunos casos,AWSEstos problemas puedendar lugar a este error.
47
AWS SDK for .NET Developer GuideDefiniciones para métricas del SDK
Métrica ConnectionErrorCount
Modo de uso Utilice esta métrica para determinar si losproblemas son específicos de la aplicación olos causa la infraestructura o la red. Un valor deConnectionErrorCount elevado también podríaindicar valores de tiempo de espera cortos para lasllamadas a la API.
Métrica ThrottleCount
Definición Número de llamadas a la API que producen erroresdebido a la limitación controlada impuesta por losservicios de AWS.
Modo de uso Utilice esta métrica para evaluar si la aplicación haalcanzado los límites, así como para determinarla causa de los reintentos y la latencia de laaplicación. Considere la posibilidad de distribuirlas llamadas a través de una ventana en lugar deagruparlas por lotes.
Métrica ServerErrorCount
Definición Número de llamadas a la API que serealizan incorrectamente debido a errores deservidor (códigos de respuesta HTTP 5xx)desdeAWSServicios de. Suelen ser causados porlos servicios de AWS.
Modo de uso Determine la causa de los reintentos o latenciadel SDK. Esta métrica no siempre indicaráqueAWSservicios son culpables, ya quealgunosAWSclasifican la latencia como unarespuesta HTTP 503.
Métrica EndToEndLatency
Definición Tiempo total del que dispone la aplicaciónpara realizar una llamada usandoAWSSDK,incluidos los reintentos. En otras palabras,independientemente de si se realiza correctamentedespués de varios intentos, o tan pronto comono se produce una llamada debido a un errorirreparable.
Modo de uso Determinar cómoAWSLas llamadas a la APIcontribuyen a la latencia general de la aplicación.Una latencia superior a la esperada puededeberse a problemas con la red, el firewall u otrosparámetros de configuración o a la latencia que seproduce como resultado de los reintentos del SDK.
48
AWS SDK for .NET Developer GuideHerramientas adicionales
Herramientas adicionalesLas siguientes son algunas herramientas adicionales que puede utilizar para facilitar el trabajo dedesarrollo, implementación y mantenimiento de las aplicaciones.NET.
AWSHerramienta de implementación de.NET
Esta es una documentación preliminar para una característica en versión de vista previa. Está sujeta acambios.
Después de desarrollar la aplicación de.NET Core nativa de la nube en una máquina de desarrollo, puedeusar la herramientaAWS.NET para que la CLI de.NET pueda implementar más fácilmente su aplicaciónenAWS.
Para obtener más información, consulteHerramienta de implementación (p. 150)inHerramientasadicionales para usar con elAWS SDK for .NET (p. 150).
49
AWS SDK for .NET Developer GuideNovedades
Migrando su proyecto para elAWSSDK for .NET
En esta sección se proporciona información acerca de las tareas de migración que pueden aplicarse austed e instrucciones acerca de cómo realizar esas tareas.
Temas• Novedades de laAWS SDK for .NET (p. 50)• Plataformas admitidas por elAWS SDK for .NET (p. 50)• Migración a la versión 3.5 deAWS SDK for .NET (p. 51)• Migración a la versión 3.7 deAWS SDK for .NET (p. 53)• Migración desde .NET Standard 1.3 (p. 54)
Novedades de laAWS SDK for .NETConsulte la página del producto enhttps://aws.amazon.com/sdk-for-net/Para obtener información de altonivel acerca de las novedades deAWS SDK for .NET.
A continuación, se muestra las novedades de laAWS SDK for .NET.
2021-03-17: Vista previa para desarrolladores de laAWSHerramienta de implementación de.NET
Esta es una documentación preliminar para un servicio en versión de vista previa. Está sujeta a cambios.
LaAWSLa herramienta de implementación de.NET, que es una herramienta de implementaciónobstinada para la CLI de.NET, está disponible para Developer Preview. Puede utilizar la herramienta deimplementación para implementar aplicaciones de.NET nativas de la nube desde la CLI de.NET en unospocos pasos.
24/08/2020: Lanzamiento de la versión 3.5 del SDK
• Estandariza la experiencia con .NET mediante la transición del soporte para todas las variacionesdel SDK que no sean de Framework a .NET Standard 2.0. Para obtener más información, consulteMigración a la versión 3.5 (p. 51).
• Se agregaron paginadores a muchos clientes de servicio, lo que hace que la paginación de losresultados de API sea más conveniente. Para obtener más información, consulte Paginators (p. 40).
Plataformas admitidas por elAWS SDK for .NETEl AWS SDK for .NET proporciona diferentes grupos de ensamblados para desarrolladores a fin deinteractuar con diversas plataformas. Sin embargo, no toda la funcionalidad del SDK es la misma encada una de estas plataformas. En este tema se describen las diferencias en cuanto a soporte de cadaplataforma.
.NET CoreLaAWS SDK for .NETEl admite aplicaciones escritas para .NET Core.AWSLos clientes de servicios deMicrosoft solo admiten patrones de llamada asíncronos en .NET Core. Esto también afecta a muchas de
50
AWS SDK for .NET Developer Guide.NET Standard 2.0
las abstracciones de alto nivel basadas en clientes de servicios como TransferUtility de Amazon S3,que solo admitirá llamadas asíncronas en el entorno de .NET Core.
.NET Standard 2.0Variaciones que no son marco de laAWS SDK for .NETCumplir con.NET Standard 2.0.
.NET Framework 4.5Para obtener más información sobre la compatibilidad con .NET Framework 4.5, consulteVersión 3delaAWS SDK for .NETGuía para desarrolladores de.)
Esta versión delAWS SDK for .NETse compila con .NET Framework 4.5 y se ejecuta en el tiempo deejecución de 4.0 de .NET.AWSLos clientes de servicios de llamada admiten patrones de llamada síncronosy asíncronos y usan elasíncrono y esperePalabras clave introducidas enC # 5.0.
.NET Framework 3.5Esta versión delAWS SDK for .NETse compila con .NET Framework 3.5 y se ejecuta en el tiempo deejecución de 2.0 o 4.0 de .NET.AWSLos clientes de servicios de Amazon admiten los patrones de llamadasíncronos y asíncronos y usan el patrón de inicio y finalización anterior.
Note
El AWS SDK for .NET no cumple con el Estándar de procesamiento de la información federal(FIPS, Federal Information Processing Standard) cuando lo usan aplicaciones generadascon la versión 2.0 del CLR. Para obtener detalles acerca de cómo puede sustituir unaimplementación compatible con FIPS en ese entorno, consulte CryptoConfig en el blog deMicrosoft y la clase HMACSHA256 del equipo de seguridad de CLR (HMACSHA256Cng) enSecurity.Cryptography.dll.
Biblioteca de clases portableEl AWS SDK for .NET también contiene la implementación de una biblioteca de clases portable. Laimplementación de la biblioteca de clases portable puede dirigirse a varias plataformas, incluidasla plataforma universal de Windows (UWP) y Xamarin en iOS y Android. Consulte elSDK de Mobilepara .NET y Xamarinpara obtener más información.AWSLos clientes de servicios de Amazon solo admitenpatrones de llamada asíncronos.
Soporte de UnityPara obtener más información sobre el soporte de Unity, consulteConsideraciones especiales para elsoporte de Unity (p. 174).
Más informaciónMigración a la versión 3.5 deAWS SDK for .NET (p. 51)
Migración a la versión 3.5 deAWS SDK for .NETLa versión 3.5 de AWS SDK for .NET estandariza aún más la experiencia con .NET mediante la transicióndel soporte para todas las variaciones del SDK que no sean de Framework a .NET Standard 2.0. En
51
AWS SDK for .NET Developer Guide¿Qué ha cambiado para la versión 3.5
función del entorno y la base de código, para aprovechar las características de la versión 3.5, es posibleque necesite realizar determinados trabajos de migración.
En este tema se describen los cambios en la versión 3.5 y el posible trabajo que debe realizar para migrarel entorno o el código desde la versión 3.
¿Qué ha cambiado para la versión 3.5A continuación se describe lo que ha cambiado o no en la versión 3.5 de AWS SDK for .NET.
.NET Framework y .NET CoreLa compatibilidad para .NET Framework y .NET Core no ha cambiado.
XamarinLos proyectos de Xamarin (nuevos y existentes) deben dirigirse a .NET Standard 2.0. ConsulteCompatibilidad de .NET Standard 2.0 en Xamarin.Forms y Compatibilidad con implementaciones de .NET.
UnityLas aplicaciones de Unity deben dirigirse a perfiles de .NET Standard 2.0 o .NET 4.x con Unity 2018.1o una versión posterior. Para obtener más información, consulte Compatibilidad con perfiles de .NET.Además, si está utilizandoIL2CPPPara crear, debe deshabilitar el desmontaje de código agregandounlink.xmlarchivo, tal y como se describe enReferencia a laAWS SDK for .NETEstándar 2.0 de Unity,Xamarin o UWP. Después de portar el código a una de las bases de código recomendadas, la aplicaciónUnity puede acceder a todos los servicios ofrecidos por el SDK.
Dado que Unity es compatible con .NET Standard 2.0, el paquete AWSSDK.Core del SDK versión 3.5 yano tiene código específico de Unity, incluidas algunas funcionalidades de nivel superior. Para proporcionaruna mejor transición, todos losheredadoEl código de Unity está disponible como referencia en elaws/aws-sdk-unity-netRepositorio de GitHub. Si encuentra que falta alguna funcionalidad que afecte al usodeAWSCon Unity, puede presentar una solicitud de función enhttps://github.com/aws/dotnet/issues.
Consulte también Consideraciones especiales para el soporte de Unity (p. 174).
Plataforma universal de WindowsDirija su aplicación UWP a la versión 16299 o posterior (actualización de Fall Creators, versión 1709,publicada en octubre de 2017).
Windows Phone y SilverlightLa versión 3.5 de AWS SDK for .NET no admite estas plataformas porque Microsoft ya no las estádesarrollando activamente. Para obtener más información, consulte los siguientes temas:
• Fin del soporte para Windows 10 Mobile• Fin del soporte de Silverlight
Bibliotecas de clases portátiles heredadas (PCLs basadas enperfiles)Considere redirigir su biblioteca a .NET Standard. Para obtener más información, consulte Comparacióncon bibliotecas de clases portátiles de Microsoft.
52
AWS SDK for .NET Developer GuideMigración de código síncrono
Amazon Cognito Sync Manager y Amazon Mobile AnalyticsManagerLas abstracciones de alto nivel que facilitan el uso de Amazon Cognito Sync y Amazon Mobile Analytics seeliminan de la versión 3.5 de laAWS SDK for .NET.AWS AppSynces el reemplazo preferido para AmazonCognito Sync. Amazon Pinpoint es el reemplazo preferido para Amazon Mobile Analytics.
Si su código se ve afectado por la falta de código de biblioteca de nivel superior paraAWS AppSyncPuederegistrar su interés en alguno o en ambos de los siguientes problemas de GitHub:https://github.com/aws/dotnet/issues/20yhttps://github.com/aws/dotnet/issues/19. También puede obtener las bibliotecas deAmazon Cognito Sync Manager y Amazon Mobile Analytics Manager en los siguientes repositorios deGitHub:aws/amazon-cognito-sync-manager-netyaws/aws-mobile-analytics-manager-net.
Migración de código síncronoLa versión 3.5 de AWS SDK for .NET solo admite llamadas asíncronas a servicios de AWS. Debe cambiarel código síncrono que desea ejecutar con la versión 3.5 para que se ejecute de forma asíncrona.
Los siguientes fragmentos de código muestran cómo puede cambiar el código síncrono a códigoasíncrono. El código de estos fragmentos se utiliza para mostrar el número de buckets de Amazon S3.
El código original llama a ListBuckets.
private static ListBucketsResponse MyListBuckets(){ var s3Client = new AmazonS3Client(); var response = s3Client.ListBuckets(); return response;}
// From the calling functionListBucketsResponse response = MyListBuckets();Console.WriteLine($"Number of buckets: {response.Buckets.Count}");
Para usar la versión 3.5 del SDK, llame a ListBucketsAsync en su lugar.
private static async Task<ListBucketsResponse> MyListBuckets(){ var s3Client = new AmazonS3Client(); var response = await s3Client.ListBucketsAsync(); return response;}
// From an **asynchronous** calling functionListBucketsResponse response = await MyListBuckets();Console.WriteLine($"Number of buckets: {response.Buckets.Count}");
// OR From a **synchronous** calling functionTask<ListBucketsResponse> response = MyListBuckets();Console.WriteLine($"Number of buckets: {response.Result.Buckets.Count}");
Migración a la versión 3.7 deAWS SDK for .NEThasta la versión 3.7, elAWS SDK for .NETya no es compatible con .NET Standard 1.3.
53
AWS SDK for .NET Developer GuideMigración desde .NET Standard 1.3
Para obtener información sobre la migración desde .NET Standard 1.3, consulteMigración desde .NETStandard 1.3 (p. 54).
Migración desde .NET Standard 1.3El 27 de junio de 2019 Microsoft terminó el soporte para las versiones de .NET Core 1.0 y .NET Core 1.1.Tras este anuncio,AWSEl está orientado a .NET Standard 1.3 enAWS SDK for .NETEl 31 de diciembre de2020.
AWScontinuó proporcionando actualizaciones de servicios y correcciones de seguridad en elAWS SDKfor .NETEl está orientado a .NET Standard 1.3 hasta el 1 de octubre de 2020. Después de esa fecha, eldestino .NET Standard 1.3 entró en modo de mantenimiento, lo que significa que no se lanzaron nuevasactualizaciones;AWSaplicó correcciones de errores críticos y parches de seguridad solamente.
El 31 de diciembre de 2020, el soporte para .NET Standard 1.3 enAWS SDK for .NETllegó a su fin de vida.Después de esa fecha no se aplicaron correcciones de errores o parches de seguridad. Los artefactosconstruidos con ese destino siguen estando disponibles para su descarga en NuGet.
Qué necesita
• Si está ejecutando aplicaciones que utilizan .NET Framework, no se verá afectado.
• Si está ejecutando aplicaciones que utilizan .NET Core 2.0 o superior, no se verá afectado.
• Si ejecuta aplicaciones con .NET Core 1.0 o .NET Core 1.1, migre las aplicaciones a una versión másreciente de .NET Core siguiendo las instrucciones de migración de Microsoft. Recomendamos comomínimo la versión .NET Core 3.1.
• Si está ejecutando aplicaciones críticas para la empresa que no se pueden actualizar en este momento,puede continuar utilizando la versión actual de AWS SDK for .NET.
Si tiene preguntas o dudas, póngase en contacto con AWS Support.
54
AWS SDK for .NET Developer GuideAWS CloudFormation
Uso deAWSEn elAWS SDK for .NETEn las secciones siguientes se muestran ejemplos de cómo puede utilizar elAWS SDK for .NETParatrabajar conAWSServicios de .
Si es la primera vez que utiliza elAWS SDK for .NET, es posible que desee consultar elInicio rápido (p. 5)eltema primero. Es una introducción a SDK.
Note
Los ejemplos de esta sección sonAsíncronoy trabajar con .NET Core y ASP.NET Core, ytambién .NET Framework 4.5 o posterior (aunque se prefiere .NET Core).Si buscasynchronous.NET Framework, consulteVersión 3de la guía en su lugar.
Puede encontrar más ejemplos de código en elAWSEjemplos de códigoy laRepositorio de awslabsenGitHub.
Antes de comenzar, asegúrese de que tieneConfiguración del entorno (p. 15). Revise también lainformación deConfiguración del proyecto (p. 17)yCaracterísticas del SDK (p. 36).
Temas• Acceso aAWS CloudFormationconAWS SDK for .NET (p. 55)• Trabajar con Amazon EC2 (p. 57)• Acceso aAWS Identity and Access Management(IAM) con elAWS SDK for .NET (p. 98)• Uso del almacenamiento en Internet de Amazon Simple Storage Service (p. 120)• Mensajes mediante Amazon SQS (p. 126)• ProgramaciónAWS OpsWorksPara Trabajar con pilas y aplicaciones (p. 148)• OtrosAWSServicios y configuración (p. 149)
Acceso aAWS CloudFormationconAWS SDKfor .NET
LaAWS SDK for .NETes compatible con AWS CloudFormation , que crea yprovisionaAWSImplementaciones de infraestructura de forma predecible y constante.
APIsLaAWS SDK for .NETproporciona API paraAWS CloudFormationclientes. Las API le permiten trabajarconAWS CloudFormationcomo plantillas y pilas. Esta sección contiene un pequeño número de ejemplosque muestran los patrones que puede seguir al trabajar con estas API. Para ver el conjunto completo deAPI, consulte laAWS SDK for .NETReferencia de la API(y desplácese hasta «Amazon.cloudFormation»).
La AWS CloudFormation las API son proporcionadas por elawssdk.CloudFormationPaquete.
PrerequisitesAntes de comenzar, asegúrese de tenerConfiguración del entorno (p. 15). Revise también la informacióndeConfiguración del proyecto (p. 17)yCaracterísticas del SDK (p. 36).
55
AWS SDK for .NET Developer GuideTopics
TopicsTemas
• ListaAWSUso de recursos deAWS CloudFormation (p. 56)
ListaAWSUso de recursos deAWS CloudFormationEn este ejemplo puede ver cómo utilizar el comandoAWS SDK for .NETpara enumerar los recursosenAWS CloudFormationpilas. En el ejemplo, se utiliza la API de bajo nivel de. La aplicación no aceptaargumentos, sino que simplemente recopila información para todas las pilas a las que se puede accederlas credenciales del usuario y, a continuación, muestra información sobre esas pilas.
Referencia del SDK de referenciasPaquetes NuGet:
• awssdk.CloudFormation
Elementos de programación:
• NamespaceAmazon.cloudFormation
ClaseAmazonCloudFormationClient• NamespaceAmazon.cloudformation.model
ClaseDescribestackResourcesRequest
ClaseDescribestackResourcesResponse
ClaseDescribestacksResponse
ClasePila
ClaseStackResource
ClaseEtiquetar
using System;using System.Threading.Tasks;using Amazon.CloudFormation;using Amazon.CloudFormation.Model;
namespace CFNListResources{ class Program { static async Task Main(string[] args) { // Create the CloudFormation client var cfnClient = new AmazonCloudFormationClient();
// List the resources for each stack await ListResources(cfnClient, await cfnClient.DescribeStacksAsync()); }
// // Method to list stack resources and other information
56
AWS SDK for .NET Developer GuideAmazon EC2
private static async Task ListResources( IAmazonCloudFormation cfnClient, DescribeStacksResponse responseDescribeStacks) { Console.WriteLine("Getting CloudFormation stack information...");
foreach (Stack stack in responseDescribeStacks.Stacks) { // Basic information for each stack Console.WriteLine("\n------------------------------------------------"); Console.WriteLine($"\nStack: {stack.StackName}"); Console.WriteLine($" Status: {stack.StackStatus.Value}"); Console.WriteLine($" Created: {stack.CreationTime}");
// The tags of each stack (etc.) if(stack.Tags.Count > 0) { Console.WriteLine(" Tags:"); foreach (Tag tag in stack.Tags) Console.WriteLine($" {tag.Key}, {tag.Value}"); }
// The resources of each stack DescribeStackResourcesResponse responseDescribeResources = await cfnClient.DescribeStackResourcesAsync(new DescribeStackResourcesRequest{ StackName = stack.StackName}); if(responseDescribeResources.StackResources.Count > 0) { Console.WriteLine(" Resources:"); foreach(StackResource resource in responseDescribeResources.StackResources) Console.WriteLine($" {resource.LogicalResourceId}: {resource.ResourceStatus}"); } } Console.WriteLine("\n------------------------------------------------"); } }}
Trabajar con Amazon EC2LaAWS SDK for .NETes compatible conAmazon EC2, que es un servicio web que proporciona capacidadinformática de tamaño ajustable. Usted utiliza esta capacidad informática para construir y alojar sussistemas de software.
APIsLaAWS SDK for .NETProporciona API para clientes Amazon EC2. Las API le permiten trabajar concaracterísticas de EC2, como grupos de seguridad y pares de claves. Las API también le permitencontrolar las instancias de Amazon EC2. Esta sección contiene un pequeño número de ejemplos quemuestran los patrones que puede seguir al trabajar con estas API. Para ver el conjunto completo de API,consulte laAWS SDK for .NETReferencia de la API(y desplácese hasta «Amazon.ec2").
Las API de Amazon EC2 son proporcionadas por elAWSSDK.EC2Paquete de NuGet.
PrerequisitesAntes de comenzar, asegúrese de tenerConfigurar el entorno (p. 15). También revise la informaciónenConfiguración del proyecto (p. 17)yCaracterísticas del SDK (p. 36).
57
AWS SDK for .NET Developer GuideAcerca de los ejemplos
Acerca de los ejemplosLos ejemplos de esta sección muestran cómo trabajar con clientes de Amazon EC2 y gestionar instanciasde Amazon EC2.
LaGuía del ejemplo de spot de EC2 (p. 90)Le muestra cómo solicitar instancias de spot de AmazonEC2. Las instancias de spot le permiten acceder a la capacidad EC2 sin utilizar por un precio inferior alprecio bajo demanda.
Temas• Uso de grupos de seguridad en Amazon EC2 (p. 58)• Uso de pares de claves de Amazon EC2 (p. 70)• Ver las regiones y las zonas de disponibilidad de Amazon EC2 (p. 77)• Uso de instancias Amazon EC2 (p. 78)• Guía del ejemplo de spot de Amazon EC2 (p. 90)
Uso de grupos de seguridad en Amazon EC2En Amazon EC2, ungrupo de seguridadActúa como un firewall virtual que controla el tráfico de red de unao varias instancias EC2. De forma predeterminada, EC2 asocia sus instancias con un grupo de seguridadque no permite el tráfico entrante. Puede crear un grupo de seguridad que permita a sus instancias EC2aceptar un tráfico determinado. Por ejemplo, si necesita conectarse a una instancia EC2 Windows, debeconfigurar el grupo de seguridad para permitir el tráfico RDP.
Obtenga más información sobre los grupos de seguridad en elGuía del usuario de EC2 para Linuxy laGuíadel usuario de EC2 para Windows.
Cuando se utiliza elAWS SDK for .NET, puede crear un grupo de seguridad para utilizarlo en EC2 en unaVPC o EC2-Classic. Para obtener más información acerca de EC2 en una VPC y EC2-Classic, consultelaGuía del usuario de EC2 para Linuxo elGuía del usuario de EC2 para Windows.
Para obtener más información acerca de los API y los requisitos previos, consulte la sección principal(Trabajar con Amazon EC2 (p. 57)).
Temas• Enumeración de grupos de seguridad (p. 58)• Creación de grupos de seguridad (p. 61)• Actualización de grupos de seguridad (p. 66)
Enumeración de grupos de seguridadEn este ejemplo puede ver cómo utilizar laAWS SDK for .NETpara enumerar los grupos de seguridad. Sisuministra unAmazon Virtual Private CloudID, la aplicación enumera los grupos de seguridad de esa VPCen particular. De lo contrario, la aplicación simplemente muestra una lista de todos los grupos de seguridaddisponibles.
En las siguientes secciones, se incluyen fragmentos de este ejemplo. Lacódigo completo para elejemplo (p. 59)se muestra después de eso, y se puede construir y ejecutar tal como está.
Temas• Enumerar grupos de seguridad (p. 59)• Completa código (p. 59)
58
AWS SDK for .NET Developer GuideGrupos de seguridad
Enumerar grupos de seguridad
En el siguiente fragmento se enumeran los grupos de seguridad. Enumera todos los grupos o los gruposde una VPC en particular si se da uno.
El ejemploAl final de este tema (p. 59)muestra este fragmento en uso.
// // Method to enumerate the security groups private static async Task EnumerateGroups(IAmazonEC2 ec2Client, string vpcID) { // A request object, in case we need it. var request = new DescribeSecurityGroupsRequest();
// Put together the properties, if needed if(!string.IsNullOrEmpty(vpcID)) { // We have a VPC ID. Find the security groups for just that VPC. Console.WriteLine($"\nGetting security groups for VPC {vpcID}...\n"); request.Filters.Add(new Filter { Name = "vpc-id", Values = new List<string>() { vpcID } }); }
// Get the list of security groups DescribeSecurityGroupsResponse response = await ec2Client.DescribeSecurityGroupsAsync(request);
// Display the list of security groups. foreach (SecurityGroup item in response.SecurityGroups) { Console.WriteLine("Security group: " + item.GroupId); Console.WriteLine("\tGroupId: " + item.GroupId); Console.WriteLine("\tGroupName: " + item.GroupName); Console.WriteLine("\tVpcId: " + item.VpcId); Console.WriteLine(); } }
Completa código
En esta sección se muestran las referencias relevantes y el código completo de este ejemplo.
Referencia del SDK
Paquetes NuGet:
• AWSSDK.EC2
Elementos de programación:
• NamespaceAmazon.ec2
ClaseAmazonec2Client• NamespaceAmazon.ec2.model
ClaseDescribeSecurityGroupsRequest
ClaseDescribeSecurityGroupsResponse
59
AWS SDK for .NET Developer GuideGrupos de seguridad
ClaseFiltro
ClaseSecurityGroup
El Código
using System;using System.Threading.Tasks;using System.Collections.Generic;using Amazon.EC2;using Amazon.EC2.Model;
namespace EC2EnumerateSecGroups{ class Program { static async Task Main(string[] args) { // Parse the command line string vpcID = string.Empty; if(args.Length == 0) { Console.WriteLine("\nEC2EnumerateSecGroups [vpc_id]"); Console.WriteLine(" vpc_id - The ID of the VPC for which you want to see security groups."); Console.WriteLine("\nSince you specified no arguments, showing all available security groups."); } else { vpcID = args[0]; }
if(vpcID.StartsWith("vpc-") || string.IsNullOrEmpty(vpcID)) { // Create an EC2 client object var ec2Client = new AmazonEC2Client();
// Enumerate the security groups await EnumerateGroups(ec2Client, vpcID); } else { Console.WriteLine("Could not find a valid VPC ID in the command-line arguments:"); Console.WriteLine($"{args[0]}"); } }
// // Method to enumerate the security groups private static async Task EnumerateGroups(IAmazonEC2 ec2Client, string vpcID) { // A request object, in case we need it. var request = new DescribeSecurityGroupsRequest();
// Put together the properties, if needed if(!string.IsNullOrEmpty(vpcID)) { // We have a VPC ID. Find the security groups for just that VPC. Console.WriteLine($"\nGetting security groups for VPC {vpcID}...\n"); request.Filters.Add(new Filter {
60
AWS SDK for .NET Developer GuideGrupos de seguridad
Name = "vpc-id", Values = new List<string>() { vpcID } }); }
// Get the list of security groups DescribeSecurityGroupsResponse response = await ec2Client.DescribeSecurityGroupsAsync(request);
// Display the list of security groups. foreach (SecurityGroup item in response.SecurityGroups) { Console.WriteLine("Security group: " + item.GroupId); Console.WriteLine("\tGroupId: " + item.GroupId); Console.WriteLine("\tGroupName: " + item.GroupName); Console.WriteLine("\tVpcId: " + item.VpcId); Console.WriteLine(); } } }}
Consideraciones adicionales
• Aviso para el caso de VPC que el filtro se construye con elNameparte del par nombre-valor establecido en «vpc-id». Este nombre proviene de la descripción deFiltersde lapropiedadDescribeSecurityGroupsRequestClase de.
• Para obtener la lista completa de los grupos de seguridad, también puedeusarDescribeSecurityGroupsAsync sin parámetros.
• Puede verificar los resultados comprobando la lista de grupos de seguridad en el cuadro dediálogoConsola de Amazon EC2.
Creación de grupos de seguridadEn este ejemplo puede ver cómo utilizar laAWS SDK for .NETPara crear un grupo de seguridad. Puedeproporcionar el ID de una VPC existente para crear un grupo de seguridad para EC2 en una VPC. Sino proporciona un ID de este tipo, el nuevo grupo de seguridad será para EC2-Classic si suAWScuentasoporta esto.
Si no se suministra un ID de VPC yAWSNo admite EC2-Classic, el nuevo grupo de seguridad perteneceráa la VPC predeterminada de su cuenta. Para obtener más información, consulte las referencias paraEC2 en una VPC frente a EC2-Classic la sección principal (Uso de grupos de seguridad en AmazonEC2 (p. 58)).
En las siguientes secciones, se incluyen fragmentos de este ejemplo. Lacódigo completo para elejemplo (p. 63)se muestra después de eso, y se puede construir y ejecutar tal como está.
Temas• Buscar grupos de seguridad existentes (p. 61)• Crear un grupo de seguridad (p. 62)• Completa código (p. 63)
Buscar grupos de seguridad existentesEl siguiente fragmento busca grupos de seguridad existentes con el nombre dado en la VPC dada.
61
AWS SDK for .NET Developer GuideGrupos de seguridad
El ejemploAl final de este tema (p. 63)muestra este fragmento en uso.
// // Method to determine if a security group with the specified name // already exists in the VPC private static async Task<List<SecurityGroup>> FindSecurityGroups( IAmazonEC2 ec2Client, string groupName, string vpcID) { var request = new DescribeSecurityGroupsRequest(); request.Filters.Add(new Filter{ Name = "group-name", Values = new List<string>() { groupName } }); if(!string.IsNullOrEmpty(vpcID)) request.Filters.Add(new Filter{ Name = "vpc-id", Values = new List<string>() { vpcID } });
var response = await ec2Client.DescribeSecurityGroupsAsync(request); return response.SecurityGroups; }
Crear un grupo de seguridadEl siguiente fragmento crea un nuevo grupo de seguridad si un grupo con ese nombre no existe en la VPCdada. Si no se da ninguna VPC y existen uno o más grupos con ese nombre, el fragmento simplementedevuelve la lista de grupos.
El ejemploAl final de este tema (p. 63)muestra este fragmento en uso.
// // Method to create a new security group (either EC2-Classic or EC2-VPC) // If vpcID is empty, the security group will be for EC2-Classic private static async Task<List<SecurityGroup>> CreateSecurityGroup( IAmazonEC2 ec2Client, string groupName, string vpcID) { // See if one or more security groups with that name // already exist in the given VPC. If so, return the list of them. var securityGroups = await FindSecurityGroups(ec2Client, groupName, vpcID); if (securityGroups.Count > 0) { Console.WriteLine( $"\nOne or more security groups with name {groupName} already exist.\n"); return securityGroups; }
// If the security group doesn't already exists, create it. var createRequest = new CreateSecurityGroupRequest{ GroupName = groupName }; if(string.IsNullOrEmpty(vpcID)) { createRequest.Description = "My .NET example security group for EC2-Classic"; } else { createRequest.VpcId = vpcID; createRequest.Description = "My .NET example security group for EC2-VPC"; } CreateSecurityGroupResponse createResponse = await ec2Client.CreateSecurityGroupAsync(createRequest);
// Return the new security group
62
AWS SDK for .NET Developer GuideGrupos de seguridad
DescribeSecurityGroupsResponse describeResponse = await ec2Client.DescribeSecurityGroupsAsync(new DescribeSecurityGroupsRequest{ GroupIds = new List<string>() { createResponse.GroupId } }); return describeResponse.SecurityGroups; }
Completa códigoEn esta sección se muestran las referencias relevantes y el código completo de este ejemplo.
Referencia del SDK
Paquetes NuGet:
• AWSSDK.EC2
Elementos de programación:
• NamespaceAmazon.ec2
ClaseAmazonec2Client• NamespaceAmazon.ec2.model
ClaseCreateSecurityGroupRequest
ClaseCreateSecurityGroupResponse
ClaseDescribeSecurityGroupsRequest
ClaseDescribeSecurityGroupsResponse
ClaseFiltro
ClaseSecurityGroup
El código
using System;using System.Threading.Tasks;using System.Collections.Generic;using Amazon.EC2;using Amazon.EC2.Model;
namespace EC2CreateSecGroup{ // = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = // Class to create a security group class Program { private const int MaxArgs = 2;
static async Task Main(string[] args) { // Parse the command line and show help if necessary var parsedArgs = CommandLine.Parse(args); if(parsedArgs.Count == 0) { PrintHelp(); return;
63
AWS SDK for .NET Developer GuideGrupos de seguridad
} if(parsedArgs.Count > MaxArgs) CommandLine.ErrorExit("\nThe number of command-line arguments is incorrect." + "\nRun the command with no arguments to see help.");
// Get the application parameters from the parsed arguments var groupName = CommandLine.GetParameter(parsedArgs, null, "-g", "--group-name"); var vpcID = CommandLine.GetParameter(parsedArgs, null, "-v", "--vpc-id"); if(string.IsNullOrEmpty(groupName)) CommandLine.ErrorExit("\nYou must supply a name for the new group." + "\nRun the command with no arguments to see help."); if(!string.IsNullOrEmpty(vpcID) && !vpcID.StartsWith("vpc-")) CommandLine.ErrorExit($"\nNot a valid VPC ID: {vpcID}");
// groupName has a value and vpcID either has a value or is null (which is fine) // Create the new security group and display information about it var securityGroups = await CreateSecurityGroup(new AmazonEC2Client(), groupName, vpcID); Console.WriteLine("Information about the security group(s):"); foreach(var group in securityGroups) { Console.WriteLine($"\nGroupName: {group.GroupName}"); Console.WriteLine($"GroupId: {group.GroupId}"); Console.WriteLine($"Description: {group.Description}"); Console.WriteLine($"VpcId (if any): {group.VpcId}"); } }
// // Method to create a new security group (either EC2-Classic or EC2-VPC) // If vpcID is empty, the security group will be for EC2-Classic private static async Task<List<SecurityGroup>> CreateSecurityGroup( IAmazonEC2 ec2Client, string groupName, string vpcID) { // See if one or more security groups with that name // already exist in the given VPC. If so, return the list of them. var securityGroups = await FindSecurityGroups(ec2Client, groupName, vpcID); if (securityGroups.Count > 0) { Console.WriteLine( $"\nOne or more security groups with name {groupName} already exist.\n"); return securityGroups; }
// If the security group doesn't already exists, create it. var createRequest = new CreateSecurityGroupRequest{ GroupName = groupName }; if(string.IsNullOrEmpty(vpcID)) { createRequest.Description = "My .NET example security group for EC2-Classic"; } else { createRequest.VpcId = vpcID; createRequest.Description = "My .NET example security group for EC2-VPC"; } CreateSecurityGroupResponse createResponse = await ec2Client.CreateSecurityGroupAsync(createRequest);
// Return the new security group DescribeSecurityGroupsResponse describeResponse = await ec2Client.DescribeSecurityGroupsAsync(new DescribeSecurityGroupsRequest{ GroupIds = new List<string>() { createResponse.GroupId } });
64
AWS SDK for .NET Developer GuideGrupos de seguridad
return describeResponse.SecurityGroups; }
// // Method to determine if a security group with the specified name // already exists in the VPC private static async Task<List<SecurityGroup>> FindSecurityGroups( IAmazonEC2 ec2Client, string groupName, string vpcID) { var request = new DescribeSecurityGroupsRequest(); request.Filters.Add(new Filter{ Name = "group-name", Values = new List<string>() { groupName } }); if(!string.IsNullOrEmpty(vpcID)) request.Filters.Add(new Filter{ Name = "vpc-id", Values = new List<string>() { vpcID } });
var response = await ec2Client.DescribeSecurityGroupsAsync(request); return response.SecurityGroups; }
// // Command-line help private static void PrintHelp() { Console.WriteLine( "\nUsage: EC2CreateSecGroup -g <group-name> [-v <vpc-id>]" + "\n -g, --group-name: The name you would like the new security group to have." + "\n -v, --vpc-id: The ID of a VPC to which the new security group will belong." + "\n If vpc-id isn't present, the security group will be for EC2-Classic" + "\n instead of EC2-VPC (if your AWS account supports this)."); } }
// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = // Class that represents a command line on the console or terminal. // (This is the same for all examples. When you have seen it once, you can ignore it.) static class CommandLine { // Method to parse a command line of the form: "--param value" or "-p value". // If "param" is found without a matching "value", Dictionary.Value is an empty string. // If "value" is found without a matching "param", Dictionary.Key is "--NoKeyN" // where "N" represents sequential numbers. public static Dictionary<string,string> Parse(string[] args) { var parsedArgs = new Dictionary<string,string>(); int i = 0, n = 0; while(i < args.Length) { // If the first argument in this iteration starts with a dash it's an option. if(args[i].StartsWith("-")) { var key = args[i++]; var value = string.Empty;
// Is there a value that goes with this option? if((i < args.Length) && (!args[i].StartsWith("-"))) value = args[i++]; parsedArgs.Add(key, value); }
65
AWS SDK for .NET Developer GuideGrupos de seguridad
// If the first argument in this iteration doesn't start with a dash, it's a value else { parsedArgs.Add("--NoKey" + n.ToString(), args[i++]); n++; } }
return parsedArgs; }
// // Method to get a parameter from the parsed command-line arguments public static string GetParameter( Dictionary<string,string> parsedArgs, string def, params string[] keys) { string retval = null; foreach(var key in keys) if(parsedArgs.TryGetValue(key, out retval)) break; return retval ?? def; }
// // Exit with an error. public static void ErrorExit(string msg, int code=1) { Console.WriteLine("\nError"); Console.WriteLine(msg); Environment.Exit(code); } }
}
Actualización de grupos de seguridadEn este ejemplo puede ver cómo utilizar laAWS SDK for .NETPara añadir una regla a un grupo deseguridad. En particular, el ejemplo agrega una regla para permitir el tráfico entrante en un puerto TCPdeterminado, que se puede utilizar, por ejemplo, para conexiones remotas a una instancia EC2. Laaplicación toma el ID de un grupo de seguridad existente, una dirección IP (o intervalo de direcciones) enformato CIDR y, opcionalmente, un número de puerto TCP. A continuación, agrega una regla de entrada algrupo de seguridad dado.
Note
Para utilizar este ejemplo, necesita una dirección IP (o intervalo de direcciones) en formato CIDR.ConsulteConsideraciones adicionalesEn este extremo de este tema, encontrará métodos paraobtener la dirección IP de su equipo local.
En las siguientes secciones, se incluyen fragmentos de este ejemplo. Lacódigo completo para elejemplo (p. 67)se muestra después de eso, y se puede construir y ejecutar tal como está.
Temas• Agregar una regla de entrada (p. 66)• Completa código (p. 67)
Agregar una regla de entradaEl siguiente fragmento agrega una regla de entrada a un grupo de seguridad para una dirección IP (ointervalo) y un puerto TCP concretos.
66
AWS SDK for .NET Developer GuideGrupos de seguridad
El ejemploAl final de este tema (p. 67)muestra este fragmento en uso.
// // Method that adds a TCP ingress rule to a security group private static async Task AddIngressRule( IAmazonEC2 eC2Client, string groupID, string ipAddress, int port) { // Create an object to hold the request information for the rule. // It uses an IpPermission object to hold the IP information for the rule. var ingressRequest = new AuthorizeSecurityGroupIngressRequest{ GroupId = groupID}; ingressRequest.IpPermissions.Add(new IpPermission{ IpProtocol = "tcp", FromPort = port, ToPort = port, Ipv4Ranges = new List<IpRange>() { new IpRange { CidrIp = ipAddress } } });
// Create the inbound rule for the security group AuthorizeSecurityGroupIngressResponse responseIngress = await eC2Client.AuthorizeSecurityGroupIngressAsync(ingressRequest); Console.WriteLine($"\nNew RDP rule was written in {groupID} for {ipAddress}."); Console.WriteLine($"Result: {responseIngress.HttpStatusCode}"); }
Completa códigoEn esta sección se muestran las referencias relevantes y el código completo de este ejemplo.
Referencia del SDK
Paquetes NuGet:
• AWSSDK.EC2
Elementos de programación:
• NamespaceAmazon.ec2
ClaseAmazonec2Client• NamespaceAmazon.ec2.model
ClaseAuthorizeSecurityGroupIngressRequest
ClaseAuthorizeSecurityGroupIngressResponse
ClaseIpPermission
ClaseIpRange
El código
using System;using System.Threading.Tasks;using System.Collections.Generic;using Amazon.EC2;using Amazon.EC2.Model;
namespace EC2AddRuleForRDP{
67
AWS SDK for .NET Developer GuideGrupos de seguridad
// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = // Class to add a rule that allows inbound traffic on TCP a port class Program { private const int DefaultPort = 3389;
static async Task Main(string[] args) { // Parse the command line and show help if necessary var parsedArgs = CommandLine.Parse(args); if(parsedArgs.Count == 0) { PrintHelp(); return; }
// Get the application parameters from the parsed arguments var groupID = CommandLine.GetParameter(parsedArgs, null, "-g", "--group-id"); var ipAddress = CommandLine.GetParameter(parsedArgs, null, "-i", "--ip-address"); var portStr = CommandLine.GetParameter(parsedArgs, DefaultPort.ToString(), "-p", "--port"); if(string.IsNullOrEmpty(ipAddress)) CommandLine.ErrorExit("\nYou must supply an IP address in CIDR format."); if(string.IsNullOrEmpty(groupID) || !groupID.StartsWith("sg-")) CommandLine.ErrorExit("\nThe ID for a security group is missing or incorrect."); if(int.Parse(portStr) == 0) CommandLine.ErrorExit($"\nThe given TCP port number, {portStr}, isn't allowed.");
// Add a rule to the given security group that allows // inbound traffic on a TCP port await AddIngressRule( new AmazonEC2Client(), groupID, ipAddress, int.Parse(portStr)); }
// // Method that adds a TCP ingress rule to a security group private static async Task AddIngressRule( IAmazonEC2 eC2Client, string groupID, string ipAddress, int port) { // Create an object to hold the request information for the rule. // It uses an IpPermission object to hold the IP information for the rule. var ingressRequest = new AuthorizeSecurityGroupIngressRequest{ GroupId = groupID}; ingressRequest.IpPermissions.Add(new IpPermission{ IpProtocol = "tcp", FromPort = port, ToPort = port, Ipv4Ranges = new List<IpRange>() { new IpRange { CidrIp = ipAddress } } });
// Create the inbound rule for the security group AuthorizeSecurityGroupIngressResponse responseIngress = await eC2Client.AuthorizeSecurityGroupIngressAsync(ingressRequest); Console.WriteLine($"\nNew RDP rule was written in {groupID} for {ipAddress}."); Console.WriteLine($"Result: {responseIngress.HttpStatusCode}"); }
// // Command-line help private static void PrintHelp() { Console.WriteLine( "\nUsage: EC2AddRuleForRDP -g <group-id> -i <ip-address> [-p <port>]" +
68
AWS SDK for .NET Developer GuideGrupos de seguridad
"\n -g, --group-id: The ID of the security group to which you want to add the inbound rule." + "\n -i, --ip-address: An IP address or address range in CIDR format." + "\n -p, --port: The TCP port number. Defaults to 3389."); } }
// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = // Class that represents a command line on the console or terminal. // (This is the same for all examples. When you have seen it once, you can ignore it.) static class CommandLine { // Method to parse a command line of the form: "--param value" or "-p value". // If "param" is found without a matching "value", Dictionary.Value is an empty string. // If "value" is found without a matching "param", Dictionary.Key is "--NoKeyN" // where "N" represents sequential numbers. public static Dictionary<string,string> Parse(string[] args) { var parsedArgs = new Dictionary<string,string>(); int i = 0, n = 0; while(i < args.Length) { // If the first argument in this iteration starts with a dash it's an option. if(args[i].StartsWith("-")) { var key = args[i++]; var value = string.Empty;
// Is there a value that goes with this option? if((i < args.Length) && (!args[i].StartsWith("-"))) value = args[i++]; parsedArgs.Add(key, value); }
// If the first argument in this iteration doesn't start with a dash, it's a value else { parsedArgs.Add("--NoKey" + n.ToString(), args[i++]); n++; } }
return parsedArgs; }
// // Method to get a parameter from the parsed command-line arguments public static string GetParameter( Dictionary<string,string> parsedArgs, string def, params string[] keys) { string retval = null; foreach(var key in keys) if(parsedArgs.TryGetValue(key, out retval)) break; return retval ?? def; }
// // Exit with an error. public static void ErrorExit(string msg, int code=1) { Console.WriteLine("\nError"); Console.WriteLine(msg); Environment.Exit(code); } }
69
AWS SDK for .NET Developer GuidePares de claves
}
Consideraciones adicionales
• Si no proporciona un número de puerto, la aplicación tiene el valor predeterminado del puerto 3389. Estees el puerto para Windows RDP, que le permite conectarse a una instancia EC2 que ejecuta Windows.En cambio, si lanza una instancia EC2 que ejecuta Linux, puede utilizar el puerto TCP 22 (SSH).
• Observe que el ejemplo estableceIpProtocola «tcp». Los valores deIpProtocolSe puedenencontrar en la descripción de laIpProtocolde la propiedadIpPermissionClase de.
• Puede que desee la dirección IP de su equipo local cuando utilice este ejemplo. A continuaciónpresentamos algunas de las formas en las que puede obtener la dirección.• Si su equipo local (desde el que se conectará a la instancia de EC2) tiene una dirección IP pública
estática, puede usar un servicio para obtener esa dirección. Uno de esos servicios eshttp://checkip.amazonaws.com/. Obtenga más información sobre cómo autorizar el tráfico entrante enelGuía del usuario de EC2 para Linuxo elGuía del usuario de EC2 para Windows.
• Otra forma de obtener la dirección IP de su equipo local es usar elConsola de Amazon EC2.
Seleccione uno de sus grupos de seguridad, seleccione la casillaReglas de entraday elijaEdición dereglas entrantes. En una regla de entrada, abra el menú desplegable en laFuentey elijaMi direcciónIPPara ver la dirección IP de su equipo local en formato CIDR. Asegúrese deCancella operación.
• Puede comprobar los resultados de este ejemplo examinando la lista de grupos de seguridad en elcuadro de diálogoConsola de Amazon EC2.
Uso de pares de claves de Amazon EC2Amazon EC2 utiliza la criptografía de clave pública para cifrar y descifrar la información de inicio desesión. En la criptografía de clave pública se utiliza una clave pública para cifrar datos y, a continuación, eldestinatario utiliza la clave privada para descifrar los datos. El conjunto de clave pública y clave privada sedenomina par de claves. Si desea conectarse a una instancia EC2, debe especificar un key pair al lanzarloy, a continuación, proporcionar la clave privada del par cuando se conecte a él.
Al lanzar una instancia EC2, puede crear un key pair para ella o usar uno que ya haya utilizado al lanzarotras instancias. Para obtener más información acerca de los pares de claves de Amazon EC2 en laGuíadel usuario de EC2 para Linuxo elGuía del usuario de EC2 para Windows.
Para obtener más información acerca de los API y los requisitos previos, consulte la sección principal(Trabajar con Amazon EC2 (p. 57)).
Temas• Creación y visualización de pares de claves (p. 70)• Eliminación de pares de claves (p. 74)
Creación y visualización de pares de clavesEn este ejemplo puede ver cómo utilizar laAWS SDK for .NETPara crear un key pair. La aplicación tomael nombre del nuevo key pair y el nombre de un archivo PEM (con una extensión «.pem»). Crea el par declaves, escribe la clave privada en el archivo PEM y, a continuación, muestra todos los pares de clavesdisponibles. Si no proporciona argumentos de línea de comandos, la aplicación simplemente muestratodos los pares de claves disponibles.
70
AWS SDK for .NET Developer GuidePares de claves
En las siguientes secciones, se incluyen fragmentos de este ejemplo. Lacódigo completo para elejemplo (p. 71)se muestra después de eso, y se puede construir y ejecutar tal como está.
Temas• Creación del key pair (p. 71)• Mostrar pares de claves disponibles (p. 71)• Completa código (p. 71)
Creación del key pair
El siguiente fragmento crea un key pair y, a continuación, almacena la clave privada en el archivo PEMdado.
El ejemploAl final de este tema (p. 71)muestra este fragmento en uso.
// // Method to create a key pair and save the key material in a PEM file private static async Task CreateKeyPair( IAmazonEC2 ec2Client, string keyPairName, string pemFileName) { // Create the key pair CreateKeyPairResponse response = await ec2Client.CreateKeyPairAsync(new CreateKeyPairRequest{ KeyName = keyPairName }); Console.WriteLine($"\nCreated new key pair: {response.KeyPair.KeyName}");
// Save the private key in a PEM file using (var s = new FileStream(pemFileName, FileMode.Create)) using (var writer = new StreamWriter(s)) { writer.WriteLine(response.KeyPair.KeyMaterial); } }
Mostrar pares de claves disponibles
El siguiente fragmento muestra una lista de los pares de claves disponibles.
El ejemploAl final de este tema (p. 71)muestra este fragmento en uso.
// // Method to show the key pairs that are available private static async Task EnumerateKeyPairs(IAmazonEC2 ec2Client) { DescribeKeyPairsResponse response = await ec2Client.DescribeKeyPairsAsync(); Console.WriteLine("Available key pairs:"); foreach (KeyPairInfo item in response.KeyPairs) Console.WriteLine($" {item.KeyName}"); }
Completa código
En esta sección se muestran las referencias relevantes y el código completo de este ejemplo.
Referencia del SDK
Paquetes NuGet:
71
AWS SDK for .NET Developer GuidePares de claves
• AWSSDK.EC2
Elementos de programación:
• NamespaceAmazon.ec2
ClaseAmazonec2Client• NamespaceAmazon.ec2.model
ClaseCreateKeyPairRequest
ClaseCreateKeyPairResponse
ClaseDescribeKeyPairsResponse
ClaseKeyPairInfo
El código
using System;using System.Threading.Tasks;using System.IO;using Amazon.EC2;using Amazon.EC2.Model;using System.Collections.Generic;
namespace EC2CreateKeyPair{ // = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = // Class to create and store a key pair class Program { static async Task Main(string[] args) { // Create the EC2 client var ec2Client = new AmazonEC2Client();
// Parse the command line and show help if necessary var parsedArgs = CommandLine.Parse(args); if(parsedArgs.Count == 0) { // In the case of no command-line arguments, // just show help and the existing key pairs PrintHelp(); Console.WriteLine("\nNo arguments specified."); Console.Write( "Do you want to see a list of the existing key pairs? ((y) or n): "); string response = Console.ReadLine(); if((string.IsNullOrEmpty(response)) || (response.ToLower() == "y")) await EnumerateKeyPairs(ec2Client); return; }
// Get the application parameters from the parsed arguments string keyPairName = CommandLine.GetParameter(parsedArgs, null, "-k", "--keypair-name"); string pemFileName = CommandLine.GetParameter(parsedArgs, null, "-p", "--pem-filename"); if(string.IsNullOrEmpty(keyPairName)) CommandLine.ErrorExit("\nNo key pair name specified." + "\nRun the command with no arguments to see help.");
72
AWS SDK for .NET Developer GuidePares de claves
if(string.IsNullOrEmpty(pemFileName) || !pemFileName.EndsWith(".pem")) CommandLine.ErrorExit("\nThe PEM filename is missing or incorrect." + "\nRun the command with no arguments to see help.");
// Create the key pair await CreateKeyPair(ec2Client, keyPairName, pemFileName); await EnumerateKeyPairs(ec2Client); }
// // Method to create a key pair and save the key material in a PEM file private static async Task CreateKeyPair( IAmazonEC2 ec2Client, string keyPairName, string pemFileName) { // Create the key pair CreateKeyPairResponse response = await ec2Client.CreateKeyPairAsync(new CreateKeyPairRequest{ KeyName = keyPairName }); Console.WriteLine($"\nCreated new key pair: {response.KeyPair.KeyName}");
// Save the private key in a PEM file using (var s = new FileStream(pemFileName, FileMode.Create)) using (var writer = new StreamWriter(s)) { writer.WriteLine(response.KeyPair.KeyMaterial); } }
// // Method to show the key pairs that are available private static async Task EnumerateKeyPairs(IAmazonEC2 ec2Client) { DescribeKeyPairsResponse response = await ec2Client.DescribeKeyPairsAsync(); Console.WriteLine("Available key pairs:"); foreach (KeyPairInfo item in response.KeyPairs) Console.WriteLine($" {item.KeyName}"); }
// // Command-line help private static void PrintHelp() { Console.WriteLine( "\nUsage: EC2CreateKeyPair -k <keypair-name> -p <pem-filename>" + "\n -k, --keypair-name: The name you want to assign to the key pair." + "\n -p, --pem-filename: The name of the PEM file to create, with a \".pem\" extension."); } }
// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = // Class that represents a command line on the console or terminal. // (This is the same for all examples. When you have seen it once, you can ignore it.) static class CommandLine { // Method to parse a command line of the form: "--param value" or "-p value". // If "param" is found without a matching "value", Dictionary.Value is an empty string. // If "value" is found without a matching "param", Dictionary.Key is "--NoKeyN" // where "N" represents sequential numbers. public static Dictionary<string,string> Parse(string[] args)
73
AWS SDK for .NET Developer GuidePares de claves
{ var parsedArgs = new Dictionary<string,string>(); int i = 0, n = 0; while(i < args.Length) { // If the first argument in this iteration starts with a dash it's an option. if(args[i].StartsWith("-")) { var key = args[i++]; var value = string.Empty;
// Is there a value that goes with this option? if((i < args.Length) && (!args[i].StartsWith("-"))) value = args[i++]; parsedArgs.Add(key, value); }
// If the first argument in this iteration doesn't start with a dash, it's a value else { parsedArgs.Add("--NoKey" + n.ToString(), args[i++]); n++; } }
return parsedArgs; }
// // Method to get a parameter from the parsed command-line arguments public static string GetParameter( Dictionary<string,string> parsedArgs, string def, params string[] keys) { string retval = null; foreach(var key in keys) if(parsedArgs.TryGetValue(key, out retval)) break; return retval ?? def; }
// // Exit with an error. public static void ErrorExit(string msg, int code=1) { Console.WriteLine("\nError"); Console.WriteLine(msg); Environment.Exit(code); } }
}
Consideraciones adicionales
• Después de ejecutar el ejemplo, puede ver el nuevo key pair en laConsola de Amazon EC2.
• Al crear un key pair, debe guardar la clave privada que se devuelve porque no puede recuperarla másadelante.
Eliminación de pares de clavesEn este ejemplo puede ver cómo utilizar laAWS SDK for .NETPara eliminar un key pair. La aplicacióntoma el nombre de un key pair. Elimina el key pair y, a continuación, muestra todos los pares de claves
74
AWS SDK for .NET Developer GuidePares de claves
disponibles. Si no proporciona argumentos de línea de comandos, la aplicación simplemente muestratodos los pares de claves disponibles.
En las siguientes secciones, se incluyen fragmentos de este ejemplo. Lacódigo completo para elejemplo (p. 75)se muestra después de eso, y se puede construir y ejecutar tal como está.
Temas• Eliminar el key pair (p. 75)• Mostrar pares de claves disponibles (p. 75)• Completa código (p. 75)
Eliminar el key pairEl siguiente fragmento de código elimina un key pair.
El ejemploAl final de este tema (p. 75)muestra este fragmento en uso.
// // Method to delete a key pair private static async Task DeleteKeyPair(IAmazonEC2 ec2Client, string keyName) { await ec2Client.DeleteKeyPairAsync(new DeleteKeyPairRequest{ KeyName = keyName}); Console.WriteLine($"\nKey pair {keyName} has been deleted (if it existed)."); }
Mostrar pares de claves disponiblesEl siguiente fragmento muestra una lista de los pares de claves disponibles.
El ejemploAl final de este tema (p. 75)muestra este fragmento en uso.
// // Method to show the key pairs that are available private static async Task EnumerateKeyPairs(IAmazonEC2 ec2Client) { DescribeKeyPairsResponse response = await ec2Client.DescribeKeyPairsAsync(); Console.WriteLine("Available key pairs:"); foreach (KeyPairInfo item in response.KeyPairs) Console.WriteLine($" {item.KeyName}"); }
Completa códigoEn esta sección se muestran las referencias relevantes y el código completo de este ejemplo.
Referencia del SDK
Paquetes NuGet:
• AWSSDK.EC2
Elementos de programación:
• NamespaceAmazon.ec2
ClaseAmazonec2Client• NamespaceAmazon.ec2.model
75
AWS SDK for .NET Developer GuidePares de claves
ClaseDeleteKeyPairRequest
ClaseDescribeKeyPairsResponse
ClaseKeyPairInfo
El código
using System;using System.Threading.Tasks;using Amazon.EC2;using Amazon.EC2.Model;
namespace EC2DeleteKeyPair{ class Program { static async Task Main(string[] args) { // Create the EC2 client var ec2Client = new AmazonEC2Client();
if(args.Length == 1) { // Delete a key pair (if it exists) await DeleteKeyPair(ec2Client, args[0]);
// Display the key pairs that are left await EnumerateKeyPairs(ec2Client); } else { Console.WriteLine("\nUsage: EC2DeleteKeyPair keypair-name"); Console.WriteLine(" keypair-name - The name of the key pair you want to delete."); Console.WriteLine("\nNo arguments specified."); Console.Write( "Do you want to see a list of the existing key pairs? ((y) or n): "); string response = Console.ReadLine(); if((string.IsNullOrEmpty(response)) || (response.ToLower() == "y")) await EnumerateKeyPairs(ec2Client); } }
// // Method to delete a key pair private static async Task DeleteKeyPair(IAmazonEC2 ec2Client, string keyName) { await ec2Client.DeleteKeyPairAsync(new DeleteKeyPairRequest{ KeyName = keyName}); Console.WriteLine($"\nKey pair {keyName} has been deleted (if it existed)."); }
// // Method to show the key pairs that are available private static async Task EnumerateKeyPairs(IAmazonEC2 ec2Client) { DescribeKeyPairsResponse response = await ec2Client.DescribeKeyPairsAsync(); Console.WriteLine("Available key pairs:"); foreach (KeyPairInfo item in response.KeyPairs) Console.WriteLine($" {item.KeyName}"); }
76
AWS SDK for .NET Developer GuideRegiones y zonas de disponibilidad
}}
Ver las regiones y las zonas de disponibilidad deAmazon EC2Amazon EC2 está hospedado en varias ubicaciones de todo el mundo. Dichas ubicaciones se componende regiones de y zonas de disponibilidad. Cada región de es un área geográfica distinta que tiene variasubicaciones aisladas, denominadas zonas de disponibilidad.
Para obtener más información acerca de las regiones y las zonas de disponibilidad en laGuía del usuariode EC2 para Linuxo elGuía del usuario de EC2 para Windows.
En este ejemplo puede ver cómo utilizar laAWS SDK for .NETpara obtener detalles sobre las regiones yzonas de disponibilidad relacionadas con un cliente EC2. La aplicación muestra listas de las regiones yzonas de disponibilidad disponibles para un cliente EC2.
Referencia del SDKPaquetes NuGet:
• AWSSDK.EC2
Elementos de programación:
• NamespaceAmazon.ec2
ClaseAmazonec2Client• NamespaceAmazon.ec2.model
ClaseDescribeAvailabilityZonesResponse
ClaseDescribeRegionsResponse
ClaseAvailabilityZone
ClaseRegión
using System;using System.Threading.Tasks;using Amazon.EC2;using Amazon.EC2.Model;
namespace EC2RegionsAndZones{ class Program { static async Task Main(string[] args) { Console.WriteLine( "Finding the Regions and Availability Zones available to an EC2 client...");
// Create the EC2 client var ec2Client = new AmazonEC2Client();
// Display the Regions and Availability Zones await DescribeRegions(ec2Client); await DescribeAvailabilityZones(ec2Client);
77
AWS SDK for .NET Developer GuideInstancias EC2
}
// // Method to display Regions private static async Task DescribeRegions(IAmazonEC2 ec2Client) { Console.WriteLine("\nRegions that are enabled for the EC2 client:"); DescribeRegionsResponse response = await ec2Client.DescribeRegionsAsync(); foreach (Region region in response.Regions) Console.WriteLine(region.RegionName); }
// // Method to display Availability Zones private static async Task DescribeAvailabilityZones(IAmazonEC2 ec2Client) { Console.WriteLine("\nAvailability Zones for the EC2 client's region:"); DescribeAvailabilityZonesResponse response = await ec2Client.DescribeAvailabilityZonesAsync(); foreach (AvailabilityZone az in response.AvailabilityZones) Console.WriteLine(az.ZoneName); } }}
Uso de instancias Amazon EC2Puede utilizar elAWS SDK for .NETPara controlar las instancias de Amazon EC2 con operaciones comocrear, comenzar y terminar. En los temas de esta sección, se incluyen algunos ejemplos de cómo hacerlo.Obtenga más información sobre las instancias de EC2 en elGuía del usuario de EC2 para Linuxo elGuíadel usuario de EC2 para Windows
Para obtener más información acerca de los API y los requisitos previos, consulte la sección principal(Trabajar con Amazon EC2 (p. 57)).
Temas• Lanzamiento de una instancia Amazon EC2 (p. 78)• Terminación de una instancia Amazon EC2 (p. 89)
Lanzamiento de una instancia Amazon EC2En este ejemplo puede ver cómo utilizar laAWS SDK for .NETPara lanzar una o más instancias deAmazon EC2 con la misma configuración de la misma imagen de máquina de (AMI). Uso deVariasentradas (p. 79)que proporcione, la aplicación inicia una instancia de EC2 y, a continuación, supervisala instancia hasta que esté fuera del estado «Pendiente».
Si la instancia EC2 se está ejecutando, puede conectarse a ella de forma remota, tal y como se describeen(Opcional) Connect a la instancia (p. 86).
Puede lanzar una instancia EC2 en una VPC o en EC2-Classic (siAWSes compatible con esto). Paraobtener más información acerca de EC2 en una VPC y EC2-Classic, consulte laGuía del usuario de EC2para Linuxo elGuía del usuario de EC2 para Windows.
En las secciones siguientes se proporcionan fragmentos y otra información para este ejemplo. Lacódigocompleto para el ejemplo (p. 81)se muestra después de los fragmentos, y se puede construir y ejecutartal como está.
Temas
78
AWS SDK for .NET Developer GuideInstancias EC2
• Reúne lo que necesita (p. 79)• Lanzar una instancia (p. 79)• Monitorear la instancia (p. 80)• Completa código (p. 81)• (Opcional) Connect a la instancia (p. 86)• Eliminar recursos (p. 89)
Reúne lo que necesita
Para lanzar una instancia EC2, necesitará varias cosas.
• AVPC:donde se lanzará la instancia. Si va a ser una instancia de Windows y se va a conectar a ellaa través de RDP, lo más probable es que la VPC necesite tener una puerta de enlace de Internetconectada, así como una entrada para la puerta de enlace de Internet en la tabla de rutas. Para obtenermás información, consultePuertos de enlace a interneten laAmazon VPC User Guide.
• El ID de una subred existente en la VPC donde se lanzará la instancia. Una forma fácil de encontrar ocrear esto consiste en iniciar una sesión en laConsola de Amazon VPC, pero también puede obtenerlomediante programación utilizando el métodoCreateSubnetAsyncyDescribeSubnetsAsyncMétodos de.
Note
Si las recetasAWSCuenta con EC2-Classic y ese es el tipo de instancia que desea lanzar, esteparámetro no es necesario. Sin embargo, si su cuenta no es compatible con EC2-Classic yno proporciona este parámetro, la nueva instancia se inicia en la VPC predeterminada de sucuenta.
• Se trata del ID de un grupo de seguridad existente que pertenece a la VPC donde se lanzarála instancia. Para obtener más información, consulte Uso de grupos de seguridad en AmazonEC2 (p. 58).
• Si desea conectarse a la nueva instancia, el grupo de seguridad mencionado anteriormente debe teneruna regla de entrada adecuada que permita el tráfico SSH en el puerto 22 (instancia de Linux) o el tráficoRDP en el puerto 3389 (instancia de Windows). Para obtener información acerca de cómo hacerlo,consulteActualización de grupos de seguridad (p. 66), incluido elConsideraciones adicionalescercadel final de ese tema.
• La Imagen de máquina de Amazon (AMI) que se utilizará para crear la instancia. Consulte la informaciónacerca de las AMI en laGuía del usuario de EC2 para Linuxo elGuía del usuario de EC2 para Windows.Por ejemplo, lea acerca de las AMI compartidas en elGuía del usuario de EC2 para Linuxo elGuía delusuario de EC2 para Windows.
• Nombre de un key pair EC2 existente, que se utiliza para conectarse a la nueva instancia. Para obtenermás información, consulte Uso de pares de claves de Amazon EC2 (p. 70).
• Se trata del nombre del archivo PEM que contiene la clave privada del key pair EC2 mencionadoanteriormente. El archivo PEM se utiliza cuandoConexión remota (p. 86)a la instancia.
Lanzar una instancia
El siguiente fragmento lanza una instancia EC2.
79
AWS SDK for .NET Developer GuideInstancias EC2
El ejemploCerca del final de este tema (p. 81)muestra este fragmento en uso.
// // Method to launch the instances // Returns a list with the launched instance IDs private static async Task<List<string>> LaunchInstances( IAmazonEC2 ec2Client, RunInstancesRequest requestLaunch) { var instanceIds = new List<string>(); RunInstancesResponse responseLaunch = await ec2Client.RunInstancesAsync(requestLaunch);
Console.WriteLine("\nNew instances have been created."); foreach (Instance item in responseLaunch.Reservation.Instances) { instanceIds.Add(item.InstanceId); Console.WriteLine($" New instance: {item.InstanceId}"); }
return instanceIds; }
Monitorear la instanciaEl siguiente fragmento supervisa la instancia hasta que esté fuera del estado «Pendiente».
El ejemploCerca del final de este tema (p. 81)muestra este fragmento en uso.
Consulte laInstanceStatepara los valores válidos de la claseInstance.State.Codepropiedad.
// // Method to wait until the instances are running (or at least not pending) private static async Task CheckState(IAmazonEC2 ec2Client, List<string> instanceIds) { Console.WriteLine( "\nWaiting for the instances to start." + "\nPress any key to stop waiting. (Response might be slightly delayed.)");
int numberRunning; DescribeInstancesResponse responseDescribe; var requestDescribe = new DescribeInstancesRequest{ InstanceIds = instanceIds};
// Check every couple of seconds int wait = 2000; while(true) { // Get and check the status for each of the instances to see if it's past pending. // Once all instances are past pending, break out. // (For this example, we are assuming that there is only one reservation.) Console.Write("."); numberRunning = 0; responseDescribe = await ec2Client.DescribeInstancesAsync(requestDescribe); foreach(Instance i in responseDescribe.Reservations[0].Instances) { // Check the lower byte of State.Code property // Code == 0 is the pending state if((i.State.Code & 255) > 0) numberRunning++; } if(numberRunning == responseDescribe.Reservations[0].Instances.Count) break;
// Wait a bit and try again (unless the user wants to stop waiting) Thread.Sleep(wait);
80
AWS SDK for .NET Developer GuideInstancias EC2
if(Console.KeyAvailable) break; }
Console.WriteLine("\nNo more instances are pending."); foreach(Instance i in responseDescribe.Reservations[0].Instances) { Console.WriteLine($"For {i.InstanceId}:"); Console.WriteLine($" VPC ID: {i.VpcId}"); Console.WriteLine($" Instance state: {i.State.Name}"); Console.WriteLine($" Public IP address: {i.PublicIpAddress}"); Console.WriteLine($" Public DNS name: {i.PublicDnsName}"); Console.WriteLine($" Key pair name: {i.KeyName}"); } }
Completa códigoEn esta sección se muestran las referencias relevantes y el código completo de este ejemplo.
Referencia del SDK
Paquetes NuGet:
• AWSSDK.EC2
Elementos de programación:
• NamespaceAmazon.ec2
ClaseAmazonec2Client
ClaseInstanceType• NamespaceAmazon.ec2.model
ClaseDescribeInstancesRequest
ClaseDescribeInstancesResponse
ClaseInstance (Instancia)
ClaseInstanceNetworkInterfaceSpecification
ClaseRunInstancesRequest
ClaseRunInstancesResponse
El código
using System;using System.Threading;using System.Threading.Tasks;using System.Collections.Generic;using Amazon.EC2;using Amazon.EC2.Model;
namespace EC2LaunchInstance{ // = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = // Class to launch an EC2 instance
81
AWS SDK for .NET Developer GuideInstancias EC2
class Program { static async Task Main(string[] args) { // Parse the command line and show help if necessary var parsedArgs = CommandLine.Parse(args); if(parsedArgs.Count == 0) { PrintHelp(); return; }
// Get the application parameters from the parsed arguments string groupID = CommandLine.GetParameter(parsedArgs, null, "-g", "--group-id"); string ami = CommandLine.GetParameter(parsedArgs, null, "-a", "--ami-id"); string keyPairName = CommandLine.GetParameter(parsedArgs, null, "-k", "--keypair-name"); string subnetID = CommandLine.GetParameter(parsedArgs, null, "-s", "--subnet-id"); if( (string.IsNullOrEmpty(groupID) || !groupID.StartsWith("sg-")) || (string.IsNullOrEmpty(ami) || !ami.StartsWith("ami-")) || (string.IsNullOrEmpty(keyPairName)) || (!string.IsNullOrEmpty(subnetID) && !subnetID.StartsWith("subnet-"))) CommandLine.ErrorExit( "\nOne or more of the required arguments is missing or incorrect." + "\nRun the command with no arguments to see help.");
// Create an EC2 client var ec2Client = new AmazonEC2Client();
// Create an object with the necessary properties RunInstancesRequest request = GetRequestData(groupID, ami, keyPairName, subnetID);
// Launch the instances and wait for them to start running var instanceIds = await LaunchInstances(ec2Client, request); await CheckState(ec2Client, instanceIds); }
// // Method to put together the properties needed to launch the instance. private static RunInstancesRequest GetRequestData( string groupID, string ami, string keyPairName, string subnetID) { // Common properties var groupIDs = new List<string>() { groupID }; var request = new RunInstancesRequest() { // The first three of these would be additional command-line arguments or similar. InstanceType = InstanceType.T1Micro, MinCount = 1, MaxCount = 1, ImageId = ami, KeyName = keyPairName };
// Properties specifically for EC2 in a VPC. if(!string.IsNullOrEmpty(subnetID)) { request.NetworkInterfaces = new List<InstanceNetworkInterfaceSpecification>() { new InstanceNetworkInterfaceSpecification() { DeviceIndex = 0, SubnetId = subnetID,
82
AWS SDK for .NET Developer GuideInstancias EC2
Groups = groupIDs, AssociatePublicIpAddress = true } }; }
// Properties specifically for EC2-Classic else { request.SecurityGroupIds = groupIDs; } return request; }
// // Method to launch the instances // Returns a list with the launched instance IDs private static async Task<List<string>> LaunchInstances( IAmazonEC2 ec2Client, RunInstancesRequest requestLaunch) { var instanceIds = new List<string>(); RunInstancesResponse responseLaunch = await ec2Client.RunInstancesAsync(requestLaunch);
Console.WriteLine("\nNew instances have been created."); foreach (Instance item in responseLaunch.Reservation.Instances) { instanceIds.Add(item.InstanceId); Console.WriteLine($" New instance: {item.InstanceId}"); }
return instanceIds; }
// // Method to wait until the instances are running (or at least not pending) private static async Task CheckState(IAmazonEC2 ec2Client, List<string> instanceIds) { Console.WriteLine( "\nWaiting for the instances to start." + "\nPress any key to stop waiting. (Response might be slightly delayed.)");
int numberRunning; DescribeInstancesResponse responseDescribe; var requestDescribe = new DescribeInstancesRequest{ InstanceIds = instanceIds};
// Check every couple of seconds int wait = 2000; while(true) { // Get and check the status for each of the instances to see if it's past pending. // Once all instances are past pending, break out. // (For this example, we are assuming that there is only one reservation.) Console.Write("."); numberRunning = 0; responseDescribe = await ec2Client.DescribeInstancesAsync(requestDescribe); foreach(Instance i in responseDescribe.Reservations[0].Instances) { // Check the lower byte of State.Code property // Code == 0 is the pending state if((i.State.Code & 255) > 0) numberRunning++; } if(numberRunning == responseDescribe.Reservations[0].Instances.Count)
83
AWS SDK for .NET Developer GuideInstancias EC2
break;
// Wait a bit and try again (unless the user wants to stop waiting) Thread.Sleep(wait); if(Console.KeyAvailable) break; }
Console.WriteLine("\nNo more instances are pending."); foreach(Instance i in responseDescribe.Reservations[0].Instances) { Console.WriteLine($"For {i.InstanceId}:"); Console.WriteLine($" VPC ID: {i.VpcId}"); Console.WriteLine($" Instance state: {i.State.Name}"); Console.WriteLine($" Public IP address: {i.PublicIpAddress}"); Console.WriteLine($" Public DNS name: {i.PublicDnsName}"); Console.WriteLine($" Key pair name: {i.KeyName}"); } }
// // Command-line help private static void PrintHelp() { Console.WriteLine( "\nUsage: EC2LaunchInstance -g <group-id> -a <ami-id> -k <keypair-name> [-s <subnet-id>]" + "\n -g, --group-id: The ID of the security group." + "\n -a, --ami-id: The ID of an Amazon Machine Image." + "\n -k, --keypair-name - The name of a key pair." + "\n -s, --subnet-id: The ID of a subnet. Required only for EC2 in a VPC."); } }
// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = // Class that represents a command line on the console or terminal. // (This is the same for all examples. When you have seen it once, you can ignore it.) static class CommandLine { // Method to parse a command line of the form: "--param value" or "-p value". // If "param" is found without a matching "value", Dictionary.Value is an empty string. // If "value" is found without a matching "param", Dictionary.Key is "--NoKeyN" // where "N" represents sequential numbers. public static Dictionary<string,string> Parse(string[] args) { var parsedArgs = new Dictionary<string,string>(); int i = 0, n = 0; while(i < args.Length) { // If the first argument in this iteration starts with a dash it's an option. if(args[i].StartsWith("-")) { var key = args[i++]; var value = string.Empty;
// Is there a value that goes with this option? if((i < args.Length) && (!args[i].StartsWith("-"))) value = args[i++]; parsedArgs.Add(key, value); }
// If the first argument in this iteration doesn't start with a dash, it's a value else {
84
AWS SDK for .NET Developer GuideInstancias EC2
parsedArgs.Add("--NoKey" + n.ToString(), args[i++]); n++; } }
return parsedArgs; }
// // Method to get a parameter from the parsed command-line arguments public static string GetParameter( Dictionary<string,string> parsedArgs, string def, params string[] keys) { string retval = null; foreach(var key in keys) if(parsedArgs.TryGetValue(key, out retval)) break; return retval ?? def; }
// // Exit with an error. public static void ErrorExit(string msg, int code=1) { Console.WriteLine("\nError"); Console.WriteLine(msg); Environment.Exit(code); } }
}
Consideraciones adicionales
• Al comprobar el estado de una instancia EC2, puede agregar un filtro a laFilterde lapropiedadDescribeInstancesRequestun objeto. Con esta técnica, puede limitar la solicitud adeterminadas instancias; por ejemplo, instancias con una etiqueta específica de usuario determinada.
• Por brevedad, algunas propiedades recibieron valores típicos. En su lugar, cualquiera o todas estaspropiedades se pueden determinar mediante programación o mediante la entrada del usuario.
• Los valores que puede utilizar para laMinCountyMaxCountpropiedades de lapropiedadRunInstancesRequestEstán determinados por la zona de disponibilidad de destino y elnúmero máximo de instancias permitido para el tipo de instancia. Para obtener más información,consulte¿Cuántas instancias puedo ejecutar en Amazon EC2?en las preguntas frecuentes generales deAmazon EC2.
• Si desea utilizar un tipo de instancia diferente al de este ejemplo, hay varios tipos de instancia paraelegir, que puede ver en el cuadroGuía del usuario de EC2 para Linuxo elGuía del usuario de EC2 paraWindows.
• También puede asociar unRol de IAM (p. 115)Cuando lance dicha instancia. Para ello, creeunIamInstanceProfileSpecificationobjeto cuyo objetoNamese establece en el nombre de un rol de IAM. Acontinuación, agregue ese objeto a laIamInstanceProfilede la propiedadRunInstancesRequestunobjeto.
Note
Para iniciar una instancia de EC2 que tenga un rol de IAM asociado, la configuración de unusuario de IAM debe incluir determinados permisos. Para obtener más información acerca de
85
AWS SDK for .NET Developer GuideInstancias EC2
los permisos necesarios, consulte laGuía del usuario de EC2 para Linuxo elGuía del usuario deEC2 para Windows.
(Opcional) Connect a la instanciaUna vez que se esté ejecutando una instancia, podrá conectarse a ella de forma remota mediante el clienteremoto adecuado. En las instancias Linux y Windows, necesita la dirección IP pública o el nombre DNSpúblico de la instancia. También necesita lo siguiente.
En instancias de Linux
Puede usar un cliente SSH para conectarse a la instancia Linux. Asegúrese de que el grupo deseguridad que utilizó al iniciar la instancia permite el tráfico SSH en el puerto 22, tal y como se describeenActualización de grupos de seguridad (p. 66).
También necesita la parte privada del key pair que utilizó para lanzar la instancia; es decir, el archivo PEM.
Para obtener más información, consulteConexión con la instancia de LinuxEn la Guía del usuario deAmazon EC2 para instancias de Linux.
En instancias de Windows
Puede utilizar un cliente RDP para conectarse a la instancia. Asegúrese de que el grupo de seguridad queutilizó al iniciar la instancia permite el tráfico RDP en el puerto 3389, como se describe enActualización degrupos de seguridad (p. 66).
También necesita la contraseña de administrador. Puede obtener esto utilizando el siguiente código deejemplo, que requiere el ID de instancia y la parte privada del key pair que utilizó para lanzar la instancia;es decir, el archivo PEM.
Para obtener más información, consulteConexión con la instancia de WindowsEn la Guía del usuario deAmazon EC2 para instancias de Windows.
Warning
Este código de ejemplo devuelve la contraseña de administrador de texto sin formato de lainstancia.
Referencia del SDK
Paquetes NuGet:
• AWSSDK.EC2
Elementos de programación:
• NamespaceAmazon.ec2
ClaseAmazonec2Client• NamespaceAmazon.ec2.model
ClaseGetPasswordDataRequest
ClaseGetPasswordDataResponse
El código
using System;
86
AWS SDK for .NET Developer GuideInstancias EC2
using System.Collections.Generic;using System.IO;using System.Threading.Tasks;using Amazon.EC2;using Amazon.EC2.Model;
namespace EC2GetWindowsPassword{ // = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = // Class to get the Administrator password of a Windows EC2 instance class Program { static async Task Main(string[] args) { // Parse the command line and show help if necessary var parsedArgs = CommandLine.Parse(args); if(parsedArgs.Count == 0) { PrintHelp(); return; }
// Get the application parameters from the parsed arguments string instanceID = CommandLine.GetParameter(parsedArgs, null, "-i", "--instance-id"); string pemFileName = CommandLine.GetParameter(parsedArgs, null, "-p", "--pem-filename"); if( (string.IsNullOrEmpty(instanceID) || !instanceID.StartsWith("i-")) || (string.IsNullOrEmpty(pemFileName) || !pemFileName.EndsWith(".pem"))) CommandLine.ErrorExit( "\nOne or more of the required arguments is missing or incorrect." + "\nRun the command with no arguments to see help.");
// Create the EC2 client var ec2Client = new AmazonEC2Client();
// Get and display the password string password = await GetPassword(ec2Client, instanceID, pemFileName); Console.WriteLine($"\nPassword: {password}"); }
// // Method to get the administrator password of a Windows EC2 instance private static async Task<string> GetPassword( IAmazonEC2 ec2Client, string instanceID, string pemFilename) { string password = string.Empty; GetPasswordDataResponse response = await ec2Client.GetPasswordDataAsync(new GetPasswordDataRequest{ InstanceId = instanceID}); if(response.PasswordData != null) { password = response.GetDecryptedPassword(File.ReadAllText(pemFilename)); } else { Console.WriteLine($"\nThe password is not available for instance {instanceID}."); Console.WriteLine($"If this is a Windows instance, the password might not be ready."); } return password; }
87
AWS SDK for .NET Developer GuideInstancias EC2
// // Command-line help private static void PrintHelp() { Console.WriteLine( "\nUsage: EC2CreateKeyPair -i <instance-id> -p pem-filename" + "\n -i, --instance-id: The name of the EC2 instance." + "\n -p, --pem-filename: The name of the PEM file with the private key."); } }
// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = // Class that represents a command line on the console or terminal. // (This is the same for all examples. When you have seen it once, you can ignore it.) static class CommandLine { // Method to parse a command line of the form: "--param value" or "-p value". // If "param" is found without a matching "value", Dictionary.Value is an empty string. // If "value" is found without a matching "param", Dictionary.Key is "--NoKeyN" // where "N" represents sequential numbers. public static Dictionary<string,string> Parse(string[] args) { var parsedArgs = new Dictionary<string,string>(); int i = 0, n = 0; while(i < args.Length) { // If the first argument in this iteration starts with a dash it's an option. if(args[i].StartsWith("-")) { var key = args[i++]; var value = string.Empty;
// Is there a value that goes with this option? if((i < args.Length) && (!args[i].StartsWith("-"))) value = args[i++]; parsedArgs.Add(key, value); }
// If the first argument in this iteration doesn't start with a dash, it's a value else { parsedArgs.Add("--NoKey" + n.ToString(), args[i++]); n++; } }
return parsedArgs; }
// // Method to get a parameter from the parsed command-line arguments public static string GetParameter( Dictionary<string,string> parsedArgs, string def, params string[] keys) { string retval = null; foreach(var key in keys) if(parsedArgs.TryGetValue(key, out retval)) break; return retval ?? def; }
// // Exit with an error. public static void ErrorExit(string msg, int code=1) { Console.WriteLine("\nError"); Console.WriteLine(msg);
88
AWS SDK for .NET Developer GuideInstancias EC2
Environment.Exit(code); } }
}
Eliminar recursosSi ya no necesita la instancia EC2, asegúrese de terminarla, tal y como se describe enTerminación de unainstancia Amazon EC2 (p. 89).
Terminación de una instancia Amazon EC2Cuando ya no necesite una o más de sus instancias de Amazon EC2, podrá terminarlas.
En este ejemplo puede ver cómo utilizar laAWS SDK for .NETPara terminar las instancias EC2. Senecesita un ID de instancia como entrada.
Referencia del SDK
Paquetes NuGet:
• AWSSDK.EC2
Elementos de programación:
• NamespaceAmazon.ec2
ClaseAmazonec2Client• NamespaceAmazon.ec2.model
ClaseTerminateInstancesRequest
ClaseTerminateInstancesResponse
using System;using System.Threading.Tasks;using System.Collections.Generic;using Amazon.EC2;using Amazon.EC2.Model;
namespace EC2TerminateInstance{ class Program { static async Task Main(string[] args) { if((args.Length == 1) && (args[0].StartsWith("i-"))) { // Terminate the instance var ec2Client = new AmazonEC2Client(); await TerminateInstance(ec2Client, args[0]); } else { Console.WriteLine("\nCommand-line argument missing or incorrect."); Console.WriteLine("\nUsage: EC2TerminateInstance instance-ID"); Console.WriteLine(" instance-ID - The EC2 instance you want to terminate."); return; }
89
AWS SDK for .NET Developer GuideAprendizaje de instancias de spot
}
// // Method to terminate an EC2 instance private static async Task TerminateInstance(IAmazonEC2 ec2Client, string instanceID) { var request = new TerminateInstancesRequest{ InstanceIds = new List<string>() { instanceID }}; TerminateInstancesResponse response = await ec2Client.TerminateInstancesAsync(new TerminateInstancesRequest{ InstanceIds = new List<string>() { instanceID } }); foreach (InstanceStateChange item in response.TerminatingInstances) { Console.WriteLine("Terminated instance: " + item.InstanceId); Console.WriteLine("Instance state: " + item.CurrentState.Name); } } }}
Después de ejecutar el ejemplo, es buena idea iniciar una sesión en laConsola de Amazon EC2paraverificar que elinstancia EC2ya no está disponible.
Guía del ejemplo de spot de Amazon EC2En este tutorial se muestra cómo utilizar laAWS SDK for .NETPara gestionar las Instancias de spot deAmazon EC2.
OverviewLas instancias de spot le permiten solicitar capacidad de Amazon EC2 sin utilizar por un precio inferioral precio bajo demanda. Esto puede reducir significativamente los costos de EC2 para aplicaciones quepueden interrumpirse.
A continuación se proporciona un resumen general de cómo se solicitan y utilizan las instancias de spot.
1. Cree una solicitud de instancia de spot, especificando el precio máximo que está dispuesto a pagar.2. Cuando se satisfaga la solicitud, ejecute la instancia como lo haría con cualquier otra instancia de
Amazon EC2.3. Ejecute la instancia todo el tiempo que desee y, a continuación, finalice, a menos que la
propiedadPrecio de spotcambia de forma que la instancia se termine por usted.4. Limpie la solicitud de instancia puntual cuando ya no la necesite para que ya no se creen instancias
puntuales.
Esta ha sido una visión general de nivel muy alto de las instancias puntuales. Puede obtener una mejorcomprensión de las instancias puntuales leyendo acerca de ellas en elGuía del usuario de EC2 paraLinuxo elGuía del usuario de EC2 para Windows.
Acerca de este tutorialA medida que siga este tutorial, utilice laAWS SDK for .NETPara hacer lo siguiente:
• Crear una solicitud de instancia de spot• Determinar cuándo se ha cumplido la solicitud de instancia de spot• Cancelar la solicitud de instancia de spot• Terminar las instancias asociadas
90
AWS SDK for .NET Developer GuideAprendizaje de instancias de spot
En las secciones siguientes se proporcionan fragmentos y otra información para este ejemplo. Lacódigocompleto para el ejemplo (p. 94)se muestra después de los fragmentos, y se puede construir y ejecutartal como está.
Temas• Prerequisites (p. 91)• Reúne lo que necesita (p. 91)• Creación de una solicitud de instancia de spot (p. 92)• Determinar el estado de la solicitud de instancia de spot (p. 93)• Limpiar las solicitudes de instancias de spot (p. 93)• Limpiar las Instancias de spot (p. 94)• Completa código (p. 94)
PrerequisitesPara obtener más información acerca de los API y los requisitos previos, consulte la sección principal(Trabajar con Amazon EC2 (p. 57)).
Reúne lo que necesitaPara crear una solicitud de instancia de spot, necesitará varias cosas.
• El número de instancias y su tipo de instancia. Hay varios tipos de instancia para elegir, que puedever en laGuía del usuario de EC2 para Linuxo elGuía del usuario de EC2 para Windows. El númeropredeterminado de este tutorial es 1.
• La Imagen de máquina de Amazon (AMI) que se utilizará para crear la instancia. Consulte la informaciónacerca de las AMI en laGuía del usuario de EC2 para Linuxo elGuía del usuario de EC2 para Windows.Por ejemplo, lea acerca de las AMI compartidas en elGuía del usuario de EC2 para Linuxo elGuía delusuario de EC2 para Windows.
• El precio máximo que está dispuesto a pagar por hora de instancia. Puede ver los precios de todoslos tipos de instancia (para instancias bajo demanda e instancias de spot) en laPágina de precios deAmazon EC2. El precio predeterminado de este tutorial se explica más adelante.
• Si desea conectarse de forma remota a una instancia, un grupo de seguridad con la configuracióny los recursos adecuados. Esto se describe enUso de grupos de seguridad en AmazonEC2 (p. 58)y la información sobrereuniendo lo que necesita (p. 79)yConexión a unainstancia (p. 86)inLanzamiento de una instancia Amazon EC2 (p. 78). Para simplificar, este tutorialutiliza el grupo de seguridad denominadopredeterminadaque todos los nuevosAWScuentas tienen.
Hay muchas formas de abordar la solicitud de instancias de spot. A continuación se indican estrategiascomunes de:
• Realice solicitudes que tengan un costo menor que el precio bajo demanda.• Realice solicitudes basadas en el valor del cálculo resultante.• Haga solicitudes para adquirir capacidad informática lo más rápidamente posible.
Las siguientes explicaciones se refieren al historial de precios puntuales en laGuía del usuario de EC2 paraLinuxo elGuía del usuario de EC2 para Windows.
91
AWS SDK for .NET Developer GuideAprendizaje de instancias de spot
Reducir el costo bajo demanda
Tiene una tarea de procesamiento por lotes que tardará en ejecutarse una cantidad determinada dehoras o días. Sin embargo, es flexible con respecto a cuándo comienza y finaliza. Desea ver si puedecompletarla por menos del valor del costo de las instancias bajo demanda.
Puede examinar el historial de precios de spot para tipos de instancia mediante la consola de AmazonEC2 o la API de Amazon EC2. Una vez que haya analizado el historial de precios para su tipo de instanciadeseado en una zona de disponibilidad especificada, tendrá dos enfoques alternativos para su solicitud:
• Especificar una solicitud en el extremo superior del rango de precios de spot, que aún son inferiores alprecio bajo demanda, contando con que lo más probable es que su solicitud de instancia de spot puntualse atienda y se ejecute durante un tiempo de computación consecutivo de completar la tarea.
• Especificar una solicitud en el extremo inferior del rango de precios y tener previsto combinar muchasinstancias lanzadas con el tiempo a través de una solicitud persistente. Las instancias se ejecutarían eltiempo suficiente, combinadas, para completar la tarea con un costo total aún más reducido
Pague no más que el valor del resultado
Tiene una tarea de procesamiento de datos para ejecutar. Conoce las ventajas de los resultados de latarea lo suficientemente bien como para saber lo valiosos que son en términos de costos de computación.
Una vez que haya analizado el historial de precios de spot para el tipo de instancia, podrá elegir un precioen el que el costo del tiempo de computación no sea superior al valor de los resultados de la tarea. Puedecrear una solicitud persistente y permitir su ejecución intermitente a medida que el precio de spot fluctúa entorno a su solicitud o por debajo de esta.
Adquirir capacidad informática rápidamente
Tiene una necesidad a corto plazo no anticipada de capacidad adicional que no está disponible a travésde las instancias bajo demanda. Una vez que haya analizado el historial de precios de spot para el tipode instancia, podrá elegir un precio superior al precio histórico más alto para mejorar significativamente laprobabilidad de que su solicitud se atienda con rapidez y continúe computándose hasta completarse.
Una vez que haya recopilado lo que necesita y haya elegido una estrategia, estará listo para solicitar unainstancia de spot. En este tutorial, el precio máximo de instancias de spot predeterminado se establece quesea el mismo que el precio bajo demanda (que es 0,003 USD para este tutorial). Establecer el precio deesta manera maximiza las posibilidades de que se cumpla la solicitud.
Creación de una solicitud de instancia de spotEl siguiente fragmento muestra cómo crear una solicitud de instancia puntual con los elementosrecopilados anteriormente.
El ejemploAl final de este tema (p. 94)muestra este fragmento en uso.
// // Method to create a Spot Instance request private static async Task<SpotInstanceRequest> CreateSpotInstanceRequest( IAmazonEC2 ec2Client, string amiId, string securityGroupName, InstanceType instanceType, string spotPrice, int instanceCount) { var launchSpecification = new LaunchSpecification{ ImageId = amiId, InstanceType = instanceType }; launchSpecification.SecurityGroups.Add(securityGroupName); var request = new RequestSpotInstancesRequest{
92
AWS SDK for .NET Developer GuideAprendizaje de instancias de spot
SpotPrice = spotPrice, InstanceCount = instanceCount, LaunchSpecification = launchSpecification };
RequestSpotInstancesResponse result = await ec2Client.RequestSpotInstancesAsync(request); return result.SpotInstanceRequests[0]; }
El valor importante devuelto de este método es el Id. de solicitud de instancia puntual, que está contenidoen elSpotInstanceRequestIdmiembro de laSpotInstanceRequestun objeto.
Note
Se le cobrará por las instancias puntuales que se inicien. Para evitar costos innecesarios,asegúrese deCancelación de cualquier solicitud (p. 93)y: para terminar lasinstancias (p. 94).
Determinar el estado de la solicitud de instancia de spotEl siguiente fragmento muestra cómo obtener información sobre su solicitud de instancia puntual. Puedeusar esa información para tomar ciertas decisiones en el código, como si debe seguir esperando que secumpla una solicitud de instancia puntual.
El ejemploAl final de este tema (p. 94)muestra este fragmento en uso.
// // Method to get information about a Spot Instance request, including the status, // instance ID, etc. // It gets the information for a specific request (as opposed to all requests). private static async Task<SpotInstanceRequest> GetSpotInstanceRequestInfo( IAmazonEC2 ec2Client, string requestId) { var describeRequest = new DescribeSpotInstanceRequestsRequest(); describeRequest.SpotInstanceRequestIds.Add(requestId);
DescribeSpotInstanceRequestsResponse describeResponse = await ec2Client.DescribeSpotInstanceRequestsAsync(describeRequest); return describeResponse.SpotInstanceRequests[0]; }
El método devuelve información sobre la solicitud de instancia puntual, como el ID de instancia, su estadoy el código de estado. Puede ver los códigos de estado de las solicitudes de instancia puntual en lasecciónGuía del usuario de EC2 para Linuxo elGuía del usuario de EC2 para Windows.
Limpiar las solicitudes de instancias de spotCuando ya no necesite solicitar instancias puntuales, es importante cancelar las solicitudes pendientespara evitar que se vuelvan a tramitar. En el siguiente fragmento se muestra cómo cancelar una solicitud deinstancia de spot.
El ejemploAl final de este tema (p. 94)muestra este fragmento en uso.
// // Method to cancel a Spot Instance request private static async Task CancelSpotInstanceRequest( IAmazonEC2 ec2Client, string requestId) { var cancelRequest = new CancelSpotInstanceRequestsRequest();
93
AWS SDK for .NET Developer GuideAprendizaje de instancias de spot
cancelRequest.SpotInstanceRequestIds.Add(requestId);
await ec2Client.CancelSpotInstanceRequestsAsync(cancelRequest); }
Limpiar las Instancias de spotPara evitar costos innecesarios, es importante que termine con todas las instancias que se hayan iniciadoa partir de las solicitudes de instancias de spot; simplemente cancelando solicitudes de instancia de spotno terminará con las instancias, lo que significa que se le seguirá cobrando por ellas. En el siguientefragmento se muestra cómo terminar una instancia después de obtener el identificador de instancia de unainstancia de spot activa.
El ejemploAl final de este tema (p. 94)muestra este fragmento en uso.
// // Method to terminate a Spot Instance private static async Task TerminateSpotInstance( IAmazonEC2 ec2Client, string requestId) { var describeRequest = new DescribeSpotInstanceRequestsRequest(); describeRequest.SpotInstanceRequestIds.Add(requestId);
// Retrieve the Spot Instance request to check for running instances. DescribeSpotInstanceRequestsResponse describeResponse = await ec2Client.DescribeSpotInstanceRequestsAsync(describeRequest);
// If there are any running instances, terminate them if( (describeResponse.SpotInstanceRequests[0].Status.Code == "request-canceled-and-instance-running") || (describeResponse.SpotInstanceRequests[0].State == SpotInstanceState.Active)) { TerminateInstancesResponse response = await ec2Client.TerminateInstancesAsync(new TerminateInstancesRequest{ InstanceIds = new List<string>(){ describeResponse.SpotInstanceRequests[0].InstanceId } }); foreach (InstanceStateChange item in response.TerminatingInstances) { Console.WriteLine($"\n Terminated instance: {item.InstanceId}"); Console.WriteLine($" Instance state: {item.CurrentState.Name}\n"); } } }
Completa códigoEn el ejemplo de código siguiente se llama a los métodos descritos anteriormente para crear y cancelaruna solicitud de instancia puntual y finalizar una instancia de subasta.
Referencia del SDK
Paquetes NuGet:
• AWSSDK.EC2
Elementos de programación:
• NamespaceAmazon.ec2
ClaseAmazonec2Client
94
AWS SDK for .NET Developer GuideAprendizaje de instancias de spot
ClaseInstanceType
• NamespaceAmazon.ec2.model
ClaseCancelSpotInstanceRequestsRequest
ClaseDescribeSpotInstanceRequestsRequest
ClaseDescribeSpotInstanceRequestsResponse
ClaseInstanceStateChange
ClaseLaunchSpecification
ClaseRequestSpotInstancesRequest
ClaseRequestSpotInstancesResponse
ClaseSpotInstanceRequest
ClaseTerminateInstancesRequest
ClaseTerminateInstancesResponse
El código
using System;using System.Threading;using System.Threading.Tasks;using System.Collections.Generic;using Amazon.EC2;using Amazon.EC2.Model;
namespace EC2SpotInstanceRequests{ class Program { static async Task Main(string[] args) { // Some default values. // These could be made into command-line arguments instead. var instanceType = InstanceType.T1Micro; string securityGroupName = "default"; string spotPrice = "0.003"; int instanceCount = 1;
// Parse the command line arguments if((args.Length != 1) || (!args[0].StartsWith("ami-"))) { Console.WriteLine("\nUsage: EC2SpotInstanceRequests ami"); Console.WriteLine(" ami: the Amazon Machine Image to use for the Spot Instances."); return; }
// Create the Amazon EC2 client. var ec2Client = new AmazonEC2Client();
// Create the Spot Instance request and record its ID Console.WriteLine("\nCreating spot instance request..."); var req = await CreateSpotInstanceRequest(
95
AWS SDK for .NET Developer GuideAprendizaje de instancias de spot
ec2Client, args[0], securityGroupName, instanceType, spotPrice, instanceCount); string requestId = req.SpotInstanceRequestId;
// Wait for an EC2 Spot Instance to become active Console.WriteLine( $"Waiting for Spot Instance request with ID {requestId} to become active..."); int wait = 1; var start = DateTime.Now; while(true) { Console.Write(".");
// Get and check the status to see if the request has been fulfilled. var requestInfo = await GetSpotInstanceRequestInfo(ec2Client, requestId); if(requestInfo.Status.Code == "fulfilled") { Console.WriteLine($"\nSpot Instance request {requestId} " + $"has been fulfilled by instance {requestInfo.InstanceId}.\n"); break; }
// Wait a bit and try again, longer each time (1, 2, 4, ...) Thread.Sleep(wait); wait = wait * 2; }
// Show the user how long it took to fulfill the Spot Instance request. TimeSpan span = DateTime.Now.Subtract(start); Console.WriteLine($"That took {span.TotalMilliseconds} milliseconds");
// Perform actions here as needed. // For this example, simply wait for the user to hit a key. // That gives them a chance to look at the EC2 console to see // the running instance if they want to. Console.WriteLine("Press any key to start the cleanup..."); Console.ReadKey(true);
// Cancel the request. // Do this first to make sure that the request can't be re-fulfilled // once the Spot Instance has been terminated. Console.WriteLine("Canceling Spot Instance request..."); await CancelSpotInstanceRequest(ec2Client, requestId);
// Terminate the Spot Instance that's running. Console.WriteLine("Terminating the running Spot Instance..."); await TerminateSpotInstance(ec2Client, requestId);
Console.WriteLine("Done. Press any key to exit..."); Console.ReadKey(true); }
// // Method to create a Spot Instance request private static async Task<SpotInstanceRequest> CreateSpotInstanceRequest( IAmazonEC2 ec2Client, string amiId, string securityGroupName, InstanceType instanceType, string spotPrice, int instanceCount) { var launchSpecification = new LaunchSpecification{ ImageId = amiId, InstanceType = instanceType }; launchSpecification.SecurityGroups.Add(securityGroupName); var request = new RequestSpotInstancesRequest{ SpotPrice = spotPrice, InstanceCount = instanceCount,
96
AWS SDK for .NET Developer GuideAprendizaje de instancias de spot
LaunchSpecification = launchSpecification };
RequestSpotInstancesResponse result = await ec2Client.RequestSpotInstancesAsync(request); return result.SpotInstanceRequests[0]; }
// // Method to get information about a Spot Instance request, including the status, // instance ID, etc. // It gets the information for a specific request (as opposed to all requests). private static async Task<SpotInstanceRequest> GetSpotInstanceRequestInfo( IAmazonEC2 ec2Client, string requestId) { var describeRequest = new DescribeSpotInstanceRequestsRequest(); describeRequest.SpotInstanceRequestIds.Add(requestId);
DescribeSpotInstanceRequestsResponse describeResponse = await ec2Client.DescribeSpotInstanceRequestsAsync(describeRequest); return describeResponse.SpotInstanceRequests[0]; }
// // Method to cancel a Spot Instance request private static async Task CancelSpotInstanceRequest( IAmazonEC2 ec2Client, string requestId) { var cancelRequest = new CancelSpotInstanceRequestsRequest(); cancelRequest.SpotInstanceRequestIds.Add(requestId);
await ec2Client.CancelSpotInstanceRequestsAsync(cancelRequest); }
// // Method to terminate a Spot Instance private static async Task TerminateSpotInstance( IAmazonEC2 ec2Client, string requestId) { var describeRequest = new DescribeSpotInstanceRequestsRequest(); describeRequest.SpotInstanceRequestIds.Add(requestId);
// Retrieve the Spot Instance request to check for running instances. DescribeSpotInstanceRequestsResponse describeResponse = await ec2Client.DescribeSpotInstanceRequestsAsync(describeRequest);
// If there are any running instances, terminate them if( (describeResponse.SpotInstanceRequests[0].Status.Code == "request-canceled-and-instance-running") || (describeResponse.SpotInstanceRequests[0].State == SpotInstanceState.Active)) { TerminateInstancesResponse response = await ec2Client.TerminateInstancesAsync(new TerminateInstancesRequest{ InstanceIds = new List<string>(){ describeResponse.SpotInstanceRequests[0].InstanceId } }); foreach (InstanceStateChange item in response.TerminatingInstances) { Console.WriteLine($"\n Terminated instance: {item.InstanceId}"); Console.WriteLine($" Instance state: {item.CurrentState.Name}\n"); } } } }
97
AWS SDK for .NET Developer GuideIAM
}
Consideraciones adicionales
• Después de ejecutar el tutorial, es buena idea iniciar una sesión en laConsola de Amazon EC2paraverificar que elSolicitud de instancia de SpotSe ha cancelado y que elinstancia de Spotya no estádisponible.
Acceso aAWS Identity and AccessManagement(IAM) con elAWS SDK for .NET
LaAWS SDK for .NETes compatible conAWS Identity and Access Management, que es un servicio webque permiteAWSPara administrar usuarios y permisos de usuario enAWS.
Un registroAWS Identity and Access Management(IAM)usuario dees una entidad que se crea enAWS. Laentidad representa a la persona o la aplicación que interactúa conAWS. Para obtener más informaciónacerca de los usuarios de IAM, consulteUsuarios de IAMyLímites de IAM y STSen la guía del usuario deIAM.
Concede permisos a un usuario mediante la creación de un IAMPolítica de de. La política contieneunDocumento de políticaEn el que se enumeran las acciones que puede realizar un usuario y losrecursos que afectan a dichas acciones. Para obtener más información acerca de las políticas de IAM,consultePolíticas y permisosen laIAM User Guide.
APIsLaAWS SDK for .NETproporciona API para clientes de IAM. Las API le permiten trabajar concaracterísticas de IAM como usuarios, roles y claves de acceso.
Esta sección contiene un pequeño número de ejemplos que muestran los patrones que puede seguir altrabajar con estas API. Para ver el conjunto completo de API, consulte laAWS SDK for .NETReferencia dela API(y desplácese hasta «Amazon.identityManagement»).
Esta sección también contieneUn ejemplo de (p. 115)que muestra cómo adjuntar un rol de IAM ainstancias de Amazon EC2 para facilitar la gestión de credenciales.
Las API de IAM son proporcionadas por elAWSSDK.IdentityManagementPaquete NuGet.
PrerequisitesAntes de comenzar, asegúrese de que tieneConfiguración del entorno (p. 15). Revise también lainformación deConfiguración del proyecto (p. 17)yCaracterísticas del SDK (p. 36).
TopicsTemas
• Crear y publicar usuarios para suAWSaccount (p. 99)• Eliminación de usuarios de IAM (p. 104)• Creación de políticas administradas por IAM desde JSON (p. 108)• Mostrar el documento de directiva de una directiva administrada por IAM (p. 112)• Conceder acceso mediante un rol de IAM (p. 115)
98
AWS SDK for .NET Developer GuideCreación de usuarios
Crear y publicar usuarios para suAWSaccountEn este ejemplo puede ver cómo utilizar laAWS SDK for .NETPara crear un nuevo usuario de IAM.Con la información que proporciona a la aplicación, crea un usuario, adjunta la directiva administradadada, obtiene credenciales para el usuario y, a continuación, muestra una lista de todos los usuarios desuAWSaccount.
Si no proporciona ningún argumento de línea de comandos, la aplicación simplemente muestra una lista detodos los usuarios en suAWSaccount.
Una de las entradas que proporciona es el nombre de recurso de Amazon (ARN) de una políticagestionada existente. Puede encontrar las políticas disponibles y sus ARN en laconsola de IAM.
En las siguientes secciones, se incluyen fragmentos de este ejemplo. Lacódigo completo para elejemplo (p. 100)se muestra después de eso, y se puede construir y ejecutar tal como está.
Temas• Crear un usuario (p. 99)• Muestre una lista de usuarios (p. 100)• Finalización de código (p. 100)• Consideraciones adicionales (p. 104)
Crear un usuarioEl siguiente fragmento crea un usuario de IAM, agrega la directiva de seguridad administrada dada y, acontinuación, crea y almacena credenciales para el usuario.
El ejemploAl final de este tema (p. 100)muestra este fragmento en uso.
// // Method to create the user private static async Task<CreateUserResponse> CreateUser( IAmazonIdentityManagementService iamClient, string userName, string policyArn, string csvFilename) { // Create the user // Could also create a login profile for the user by using CreateLoginProfileAsync CreateUserResponse responseCreate = await iamClient.CreateUserAsync(new CreateUserRequest(userName));
// Attach an existing managed policy await iamClient.AttachUserPolicyAsync(new AttachUserPolicyRequest{ UserName = responseCreate.User.UserName, PolicyArn = policyArn});
// Create credentials and write them to a CSV file. CreateAccessKeyResponse responseCreds = await iamClient.CreateAccessKeyAsync(new CreateAccessKeyRequest{ UserName = responseCreate.User.UserName}); using (FileStream s = new FileStream(csvFilename, FileMode.Create)) using (StreamWriter writer = new StreamWriter(s)) { writer.WriteLine("User name,Access key ID,Secret access key"); writer.WriteLine("{0},{1},{2}", responseCreds.AccessKey.UserName, responseCreds.AccessKey.AccessKeyId, responseCreds.AccessKey.SecretAccessKey); }
return responseCreate;
99
AWS SDK for .NET Developer GuideCreación de usuarios
}
Muestre una lista de usuariosEl siguiente fragmento muestra una lista de usuarios existentes, así como información sobre cada usuario,como ID de clave de acceso y directivas adjuntas.
El ejemploAl final de este tema (p. 100)muestra este fragmento en uso.
// // Method to print out a list of the existing users and information about them private static async Task ListUsers(IAmazonIdentityManagementService iamClient) { // Get the list of users ListUsersResponse responseUsers = await iamClient.ListUsersAsync(); Console.WriteLine("\nFull list of users..."); foreach (var user in responseUsers.Users) { Console.WriteLine($"User {user.UserName}:"); Console.WriteLine($"\tCreated: {user.CreateDate.ToShortDateString()}");
// Show the list of groups this user is part of ListGroupsForUserResponse responseGroups = await iamClient.ListGroupsForUserAsync( new ListGroupsForUserRequest(user.UserName)); foreach (var group in responseGroups.Groups) Console.WriteLine($"\tGroup: {group.GroupName}");
// Show the list of access keys for this user ListAccessKeysResponse responseAccessKeys = await iamClient.ListAccessKeysAsync( new ListAccessKeysRequest{UserName = user.UserName}); foreach(AccessKeyMetadata accessKey in responseAccessKeys.AccessKeyMetadata) Console.WriteLine($"\tAccess key ID: {accessKey.AccessKeyId}");
// Show the list of managed policies attached to this user var requestManagedPolicies = new ListAttachedUserPoliciesRequest{ UserName = user.UserName}; ListAttachedUserPoliciesResponse responseManagedPolicies = await iamClient.ListAttachedUserPoliciesAsync( new ListAttachedUserPoliciesRequest{UserName = user.UserName}); foreach(var policy in responseManagedPolicies.AttachedPolicies) Console.WriteLine($"\tManaged policy name: {policy.PolicyName}");
// Show the list of inline policies attached to this user ListUserPoliciesResponse responseInlinePolicies = await iamClient.ListUserPoliciesAsync( new ListUserPoliciesRequest(user.UserName)); foreach(var policy in responseInlinePolicies.PolicyNames) Console.WriteLine($"\tInline policy name: {policy}"); } }
Finalización de códigoEn esta sección se muestran referencias relevantes y el código completo de este ejemplo.
Referencia del SDK
Paquetes NuGet:
• AWSSDK.IdentityManagement
100
AWS SDK for .NET Developer GuideCreación de usuarios
Elementos de programación:
• NamespaceAmazon.identityManagement
ClaseAmazonIdentityManagementServiceClient• NamespaceAmazon.identityManagement.model
ClaseAttachUserPolicyRequest
ClaseCreateAccessKeyRequest
ClaseCreateAccessKeyResponse
ClaseCreateUserRequest
ClaseCreateUserResponse
ClaseListAccessKeysRequest
ClaseListAccessKeysResponse
ClaseListatTachedUserPoliciesRequest
ClaseListatTachedUserPoliciesResponse
ClaseListGroupsForUserRequest
ClaseListGroupsForUserResponse
ClaseListUserPoliciesRequest
ClaseListUserPoliciesResponse
ClaseListUsersResponse
El código
using System;using System.Collections.Generic;using System.IO;using System.Threading.Tasks;using Amazon.IdentityManagement;using Amazon.IdentityManagement.Model;
namespace IamCreateUser{ // = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = // Class to create a user class Program { private const int MaxArgs = 3;
static async Task Main(string[] args) { // Create an IAM service client var iamClient = new AmazonIdentityManagementServiceClient();
// Parse the command line and show help if necessary var parsedArgs = CommandLine.Parse(args); if((parsedArgs.Count == 0) || (parsedArgs.Count > MaxArgs)) {
101
AWS SDK for .NET Developer GuideCreación de usuarios
PrintHelp(); Console.WriteLine("\nIncorrect number of arguments specified."); Console.Write("Do you want to see a list of the existing users? ((y) or n): "); string response = Console.ReadLine(); if((string.IsNullOrEmpty(response)) || (response.ToLower() == "y")) await ListUsers(iamClient); return; }
// Get the application parameters from the parsed arguments string userName = CommandLine.GetParameter(parsedArgs, null, "-u", "--user-name"); string policyArn = CommandLine.GetParameter(parsedArgs, null, "-p", "--policy-arn"); string csvFilename = CommandLine.GetParameter(parsedArgs, null, "-c", "--csv-filename"); if( (string.IsNullOrEmpty(policyArn) || !policyArn.StartsWith("arn:")) || (string.IsNullOrEmpty(csvFilename) || !csvFilename.EndsWith(".csv")) || (string.IsNullOrEmpty(userName))) CommandLine.ErrorExit( "\nOne or more of the required arguments is missing or incorrect." + "\nRun the command with no arguments to see help.");
// Create a user, attach a managed policy, and obtain credentials var responseCreate = await CreateUser(iamClient, userName, policyArn, csvFilename); Console.WriteLine($"\nUser {responseCreate.User.UserName} was created."); Console.WriteLine($"User ID: {responseCreate.User.UserId}");
// Output a list of the existing users await ListUsers(iamClient); }
// // Method to create the user private static async Task<CreateUserResponse> CreateUser( IAmazonIdentityManagementService iamClient, string userName, string policyArn, string csvFilename) { // Create the user // Could also create a login profile for the user by using CreateLoginProfileAsync CreateUserResponse responseCreate = await iamClient.CreateUserAsync(new CreateUserRequest(userName));
// Attach an existing managed policy await iamClient.AttachUserPolicyAsync(new AttachUserPolicyRequest{ UserName = responseCreate.User.UserName, PolicyArn = policyArn});
// Create credentials and write them to a CSV file. CreateAccessKeyResponse responseCreds = await iamClient.CreateAccessKeyAsync(new CreateAccessKeyRequest{ UserName = responseCreate.User.UserName}); using (FileStream s = new FileStream(csvFilename, FileMode.Create)) using (StreamWriter writer = new StreamWriter(s)) { writer.WriteLine("User name,Access key ID,Secret access key"); writer.WriteLine("{0},{1},{2}", responseCreds.AccessKey.UserName, responseCreds.AccessKey.AccessKeyId, responseCreds.AccessKey.SecretAccessKey); }
return responseCreate; }
102
AWS SDK for .NET Developer GuideCreación de usuarios
// // Method to print out a list of the existing users and information about them private static async Task ListUsers(IAmazonIdentityManagementService iamClient) { // Get the list of users ListUsersResponse responseUsers = await iamClient.ListUsersAsync(); Console.WriteLine("\nFull list of users..."); foreach (var user in responseUsers.Users) { Console.WriteLine($"User {user.UserName}:"); Console.WriteLine($"\tCreated: {user.CreateDate.ToShortDateString()}");
// Show the list of groups this user is part of ListGroupsForUserResponse responseGroups = await iamClient.ListGroupsForUserAsync( new ListGroupsForUserRequest(user.UserName)); foreach (var group in responseGroups.Groups) Console.WriteLine($"\tGroup: {group.GroupName}");
// Show the list of access keys for this user ListAccessKeysResponse responseAccessKeys = await iamClient.ListAccessKeysAsync( new ListAccessKeysRequest{UserName = user.UserName}); foreach(AccessKeyMetadata accessKey in responseAccessKeys.AccessKeyMetadata) Console.WriteLine($"\tAccess key ID: {accessKey.AccessKeyId}");
// Show the list of managed policies attached to this user var requestManagedPolicies = new ListAttachedUserPoliciesRequest{ UserName = user.UserName}; ListAttachedUserPoliciesResponse responseManagedPolicies = await iamClient.ListAttachedUserPoliciesAsync( new ListAttachedUserPoliciesRequest{UserName = user.UserName}); foreach(var policy in responseManagedPolicies.AttachedPolicies) Console.WriteLine($"\tManaged policy name: {policy.PolicyName}");
// Show the list of inline policies attached to this user ListUserPoliciesResponse responseInlinePolicies = await iamClient.ListUserPoliciesAsync( new ListUserPoliciesRequest(user.UserName)); foreach(var policy in responseInlinePolicies.PolicyNames) Console.WriteLine($"\tInline policy name: {policy}"); } }
// // Command-line help private static void PrintHelp() { Console.WriteLine( "\nUsage: IamCreateUser -u <user-name> -p <policy-arn> -c <csv-filename>" + "\n -u, --user-name: The name of the user you want to create." + "\n -p, --policy-arn: The ARN of an existing managed policy." + "\n -c, --csv-filename: The name of a .csv file to write the credentials to."); } }
// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = // Class that represents a command line on the console or terminal. // (This is the same for all examples. When you have seen it once, you can ignore it.) static class CommandLine { // Method to parse a command line of the form: "--param value" or "-p value".
103
AWS SDK for .NET Developer GuideEliminación de usuarios
// If "param" is found without a matching "value", Dictionary.Value is an empty string. // If "value" is found without a matching "param", Dictionary.Key is "--NoKeyN" // where "N" represents sequential numbers. public static Dictionary<string,string> Parse(string[] args) { var parsedArgs = new Dictionary<string,string>(); int i = 0, n = 0; while(i < args.Length) { // If the first argument in this iteration starts with a dash it's an option. if(args[i].StartsWith("-")) { var key = args[i++]; var value = string.Empty;
// Is there a value that goes with this option? if((i < args.Length) && (!args[i].StartsWith("-"))) value = args[i++]; parsedArgs.Add(key, value); }
// If the first argument in this iteration doesn't start with a dash, it's a value else { parsedArgs.Add("--NoKey" + n.ToString(), args[i++]); n++; } }
return parsedArgs; }
// // Method to get a parameter from the parsed command-line arguments public static string GetParameter( Dictionary<string,string> parsedArgs, string def, params string[] keys) { string retval = null; foreach(var key in keys) if(parsedArgs.TryGetValue(key, out retval)) break; return retval ?? def; }
// // Exit with an error. public static void ErrorExit(string msg, int code=1) { Console.WriteLine("\nError"); Console.WriteLine(msg); Environment.Exit(code); } }
}
Consideraciones adicionales• También puede ver la lista de usuarios y los resultados de este ejemplo en laconsola de IAM.
Eliminación de usuarios de IAMEn este ejemplo puede ver cómo utilizar laAWS SDK for .NETPara eliminar un usuario de IAM. Primeroelimina recursos como claves de acceso, directivas adjuntas, etc., y luego elimina el usuario.
104
AWS SDK for .NET Developer GuideEliminación de usuarios
En las siguientes secciones, se incluyen fragmentos de este ejemplo. Lacódigo completo para elejemplo (p. 106)se muestra después de eso, y se puede construir y ejecutar tal como está.
Temas• Eliminar elementos del usuario (p. 105)• Elimine el usuario (p. 105)• Finalización de código (p. 106)• Consideraciones adicionales (p. 108)
Eliminar elementos del usuarioLos siguientes fragmentos muestran ejemplos de elementos que se deben quitar de un usuario antes deque se pueda eliminar el usuario, elementos como directivas administradas y claves de acceso.
El ejemploAl final de este tema (p. 106)muestra este fragmento en uso.
// // Method to detach managed policies from a user private static async Task DetachPolicies( IAmazonIdentityManagementService iamClient, string userName) { ListAttachedUserPoliciesResponse responseManagedPolicies = await iamClient.ListAttachedUserPoliciesAsync( new ListAttachedUserPoliciesRequest{UserName = userName}); foreach(AttachedPolicyType policy in responseManagedPolicies.AttachedPolicies) { Console.WriteLine($"\tDetaching policy {policy.PolicyName}"); await iamClient.DetachUserPolicyAsync(new DetachUserPolicyRequest{ PolicyArn = policy.PolicyArn, UserName = userName}); } }
// // Method to delete access keys from a user private static async Task DeleteAccessKeys( IAmazonIdentityManagementService iamClient, string userName) { ListAccessKeysResponse responseAccessKeys = await iamClient.ListAccessKeysAsync( new ListAccessKeysRequest{UserName = userName}); foreach(AccessKeyMetadata accessKey in responseAccessKeys.AccessKeyMetadata) { Console.WriteLine($"\tDeleting Access key {accessKey.AccessKeyId}"); await iamClient.DeleteAccessKeyAsync(new DeleteAccessKeyRequest{ UserName = userName, AccessKeyId = accessKey.AccessKeyId}); } }
Elimine el usuarioEl siguiente fragmento llama a métodos para quitar elementos de un usuario y, a continuación, elimina elusuario.
El ejemploAl final de este tema (p. 106)muestra este fragmento en uso.
//
105
AWS SDK for .NET Developer GuideEliminación de usuarios
// Method to delete a user private static async Task DeleteUser( IAmazonIdentityManagementService iamClient, string userName) { Console.WriteLine($"\nDeleting user {userName}..."); // // Remove items from the user // // Detach any managed policies await DetachPolicies(iamClient, userName);
// Delete any access keys await DeleteAccessKeys(iamClient, userName);
// DeleteLoginProfileAsycn(), DeleteUserPolicyAsync(), etc. // See the description of DeleteUserAsync for a full list.
// // Delete the user // await iamClient.DeleteUserAsync(new DeleteUserRequest(userName)); Console.WriteLine("Done"); }
Finalización de códigoEn esta sección se muestran referencias relevantes y el código completo de este ejemplo.
Referencia del SDK
Paquetes NuGet:
• AWSSDK.IdentityManagement
Elementos de programación:
• NamespaceAmazon.identityManagement
ClaseAmazonIdentityManagementServiceClient• NamespaceAmazon.identityManagement.model
ClaseAccessKeyMetadata
ClaseAttachedPolicyType
ClaseDeleteAccessKeyRequest
ClaseDeleteUserRequest
ClaseDetachUserPolicyRequest
ClaseListAccessKeysRequest
ClaseListAccessKeysResponse
ClaseListatTachedUserPoliciesRequest
ClaseListatTachedUserPoliciesResponse
106
AWS SDK for .NET Developer GuideEliminación de usuarios
El código
using System;using System.Threading.Tasks;using Amazon.IdentityManagement;using Amazon.IdentityManagement.Model;
namespace IamDeleteUser{ class Program { static async Task Main(string[] args) { if(args.Length != 1) { Console.WriteLine("\nUsage: IamDeleteUser user-name"); Console.WriteLine(" user-name - The name of the user you want to delete."); return; }
// Create an IAM service client var iamClient = new AmazonIdentityManagementServiceClient();
// Delete the given user await DeleteUser(iamClient, args[0]);
// Could display a list of the users that are left. }
// // Method to delete a user private static async Task DeleteUser( IAmazonIdentityManagementService iamClient, string userName) { Console.WriteLine($"\nDeleting user {userName}..."); // // Remove items from the user // // Detach any managed policies await DetachPolicies(iamClient, userName);
// Delete any access keys await DeleteAccessKeys(iamClient, userName);
// DeleteLoginProfileAsycn(), DeleteUserPolicyAsync(), etc. // See the description of DeleteUserAsync for a full list.
// // Delete the user // await iamClient.DeleteUserAsync(new DeleteUserRequest(userName)); Console.WriteLine("Done"); }
// // Method to detach managed policies from a user private static async Task DetachPolicies( IAmazonIdentityManagementService iamClient, string userName) { ListAttachedUserPoliciesResponse responseManagedPolicies = await iamClient.ListAttachedUserPoliciesAsync( new ListAttachedUserPoliciesRequest{UserName = userName}); foreach(AttachedPolicyType policy in responseManagedPolicies.AttachedPolicies) {
107
AWS SDK for .NET Developer GuideCrear políticas administradas a partir de JSON
Console.WriteLine($"\tDetaching policy {policy.PolicyName}"); await iamClient.DetachUserPolicyAsync(new DetachUserPolicyRequest{ PolicyArn = policy.PolicyArn, UserName = userName}); } }
// // Method to delete access keys from a user private static async Task DeleteAccessKeys( IAmazonIdentityManagementService iamClient, string userName) { ListAccessKeysResponse responseAccessKeys = await iamClient.ListAccessKeysAsync( new ListAccessKeysRequest{UserName = userName}); foreach(AccessKeyMetadata accessKey in responseAccessKeys.AccessKeyMetadata) { Console.WriteLine($"\tDeleting Access key {accessKey.AccessKeyId}"); await iamClient.DeleteAccessKeyAsync(new DeleteAccessKeyRequest{ UserName = userName, AccessKeyId = accessKey.AccessKeyId}); } } }}
Consideraciones adicionales• Para obtener información acerca de los recursos que se deben quitar del usuario, consulte la descripción
de laDeleteUserAsync, pero asegúrese de utilizar las versiones Async de los métodos a los que se hacereferencia.
• También puede ver la lista de usuarios y los resultados de este ejemplo en laconsola de IAM.
Creación de políticas administradas por IAM desdeJSONEn este ejemplo puede ver cómo utilizar laAWS SDK for .NETpara crear unPolítica administrada por IAMdeun documento de política dado en JSON. La aplicación crea un objeto cliente de IAM, lee el documento dedirectiva de un archivo y, a continuación, crea la directiva.
Note
Para obtener un documento de política de ejemplo en JSON, consulte laConsideracionesadicionales (p. 111)al final de este tema.
En las siguientes secciones, se incluyen fragmentos de este ejemplo. Lacódigo completo para elejemplo (p. 109)se muestra después de eso, y se puede construir y ejecutar tal como está.
Temas• Cree la política de . (p. 109)• Finalización de código (p. 109)• Consideraciones adicionales (p. 111)
108
AWS SDK for .NET Developer GuideCrear políticas administradas a partir de JSON
Cree la política de .El siguiente fragmento crea una directiva administrada por IAM con el nombre dado y el documento depolítica.
El ejemploAl final de este tema (p. 109)muestra este fragmento en uso.
// // Method to create an IAM policy from a JSON file private static async Task<CreatePolicyResponse> CreateManagedPolicy( IAmazonIdentityManagementService iamClient, string policyName, string jsonFilename) { return await iamClient.CreatePolicyAsync(new CreatePolicyRequest{ PolicyName = policyName, PolicyDocument = File.ReadAllText(jsonFilename)}); }
Finalización de códigoEn esta sección se muestran referencias relevantes y el código completo de este ejemplo.
Referencia del SDK
Paquetes NuGet:
• AWSSDK.IdentityManagement
Elementos de programación:
• NamespaceAmazon.identityManagement
ClaseAmazonIdentityManagementServiceClient• NamespaceAmazon.identityManagement.model
ClaseCreatePolicyRequest
ClaseCreatePolicyResponse
El código
using System;using System.Collections.Generic;using System.IO;using System.Threading.Tasks;using Amazon.IdentityManagement;using Amazon.IdentityManagement.Model;
namespace IamCreatePolicyFromJson{ // = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = // Class to create an IAM policy with a given policy document class Program { private const int MaxArgs = 2;
static async Task Main(string[] args) { // Parse the command line and show help if necessary
109
AWS SDK for .NET Developer GuideCrear políticas administradas a partir de JSON
var parsedArgs = CommandLine.Parse(args); if((parsedArgs.Count == 0) || (parsedArgs.Count > MaxArgs)) { PrintHelp(); return; }
// Get the application parameters from the parsed arguments string policyName = CommandLine.GetParameter(parsedArgs, null, "-p", "--policy-name"); string policyFilename = CommandLine.GetParameter(parsedArgs, null, "-j", "--json-filename"); if( string.IsNullOrEmpty(policyName) || (string.IsNullOrEmpty(policyFilename) || !policyFilename.EndsWith(".json"))) CommandLine.ErrorExit( "\nOne or more of the required arguments is missing or incorrect." + "\nRun the command with no arguments to see help.");
// Create an IAM service client var iamClient = new AmazonIdentityManagementServiceClient();
// Create the new policy var response = await CreateManagedPolicy(iamClient, policyName, policyFilename); Console.WriteLine($"\nPolicy {response.Policy.PolicyName} has been created."); Console.WriteLine($" Arn: {response.Policy.Arn}"); }
// // Method to create an IAM policy from a JSON file private static async Task<CreatePolicyResponse> CreateManagedPolicy( IAmazonIdentityManagementService iamClient, string policyName, string jsonFilename) { return await iamClient.CreatePolicyAsync(new CreatePolicyRequest{ PolicyName = policyName, PolicyDocument = File.ReadAllText(jsonFilename)}); }
// // Command-line help private static void PrintHelp() { Console.WriteLine( "\nUsage: IamCreatePolicyFromJson -p <policy-name> -j <json-filename>" + "\n -p, --policy-name: The name you want the new policy to have." + "\n -j, --json-filename: The name of the JSON file with the policy document."); } }
// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = // Class that represents a command line on the console or terminal // (This is the same for all examples. When you have seen it once, you can ignore it) static class CommandLine { // Method to parse a command line of the form: "--param value" or "-p value". // If "param" is found without a matching "value", Dictionary.Value is an empty string. // If "value" is found without a matching "param", Dictionary.Key is "--NoKeyN" // where "N" represents sequential numbers. public static Dictionary<string,string> Parse(string[] args) { var parsedArgs = new Dictionary<string,string>(); int i = 0, n = 0; while(i < args.Length)
110
AWS SDK for .NET Developer GuideCrear políticas administradas a partir de JSON
{ // If the first argument in this iteration starts with a dash it's an option. if(args[i].StartsWith("-")) { var key = args[i++]; var value = string.Empty;
// Is there a value that goes with this option? if((i < args.Length) && (!args[i].StartsWith("-"))) value = args[i++]; parsedArgs.Add(key, value); }
// If the first argument in this iteration doesn't start with a dash, it's a value else { parsedArgs.Add("--NoKey" + n.ToString(), args[i++]); n++; } }
return parsedArgs; }
// // Method to get a parameter from the parsed command-line arguments public static string GetParameter( Dictionary<string,string> parsedArgs, string def, params string[] keys) { string retval = null; foreach(var key in keys) if(parsedArgs.TryGetValue(key, out retval)) break; return retval ?? def; }
// // Exit with an error. public static void ErrorExit(string msg, int code=1) { Console.WriteLine("\nError"); Console.WriteLine(msg); Environment.Exit(code); } }
}
Consideraciones adicionales• A continuación se muestra un documento de política de ejemplo que se puede copiar en un archivo
JSON y utilizar como entrada para esta aplicación:
{ "Version" : "2012-10-17", "Id" : "DotnetTutorialPolicy", "Statement" : [ { "Sid" : "DotnetTutorialPolicyS3", "Effect" : "Allow", "Action" : [ "s3:Get*", "s3:List*" ], "Resource" : "*"
111
AWS SDK for .NET Developer GuideVisualización de documentos de políticas
}, { "Sid" : "DotnetTutorialPolicyPolly", "Effect": "Allow", "Action": [ "polly:DescribeVoices", "polly:SynthesizeSpeech" ], "Resource": "*" } ]}
• Para verificar que la política se creó, consulte en laconsola de IAM. En el navegadorPolíticas de filtro,seleccioneAdministración por el cliente. Elimine la política cuando ya no la necesite.
• Para obtener más información acerca de la creación de políticas, consulteCreación de directivas de IAMylaReferencia de política JSON de IAMen laIAM User Guide
Mostrar el documento de directiva de una directivaadministrada por IAMEn este ejemplo puede ver cómo utilizar laAWS SDK for .NETPara mostrar un documento de política. Laaplicación crea un objeto cliente de IAM, encuentra la versión predeterminada de la directiva administradade IAM dada y, a continuación, muestra el documento de directiva en JSON.
En las siguientes secciones, se incluyen fragmentos de este ejemplo. Lacódigo completo para elejemplo (p. 113)se muestra después de eso, y se puede construir y ejecutar tal como está.
Temas• Buscar la versión predeterminada (p. 112)• Mostrar el documento de la política (p. 113)• Finalización de código (p. 113)
Buscar la versión predeterminadaEl siguiente fragmento busca la versión predeterminada de la directiva de IAM dada.
El ejemploAl final de este tema (p. 113)muestra este fragmento en uso.
// // Method to determine the default version of an IAM policy // Returns a string with the version private static async Task<string> GetDefaultVersion( IAmazonIdentityManagementService iamClient, string policyArn) { // Retrieve all the versions of this policy string defaultVersion = string.Empty; ListPolicyVersionsResponse reponseVersions = await iamClient.ListPolicyVersionsAsync(new ListPolicyVersionsRequest{ PolicyArn = policyArn});
// Find the default version foreach(PolicyVersion version in reponseVersions.Versions) {
112
AWS SDK for .NET Developer GuideVisualización de documentos de políticas
if(version.IsDefaultVersion) { defaultVersion = version.VersionId; break; } }
return defaultVersion; }
Mostrar el documento de la políticaEl siguiente fragmento muestra el documento de directiva en JSON de la directiva de IAM dada.
El ejemploAl final de este tema (p. 113)muestra este fragmento en uso.
// // Method to retrieve and display the policy document of an IAM policy private static async Task ShowPolicyDocument( IAmazonIdentityManagementService iamClient, string policyArn, string defaultVersion) { // Retrieve the policy document of the default version GetPolicyVersionResponse responsePolicy = await iamClient.GetPolicyVersionAsync(new GetPolicyVersionRequest{ PolicyArn = policyArn, VersionId = defaultVersion});
// Display the policy document (in JSON) Console.WriteLine($"Version {defaultVersion} of the policy (in JSON format):"); Console.WriteLine( $"{HttpUtility.UrlDecode(responsePolicy.PolicyVersion.Document)}"); }
Finalización de códigoEn esta sección se muestran referencias relevantes y el código completo de este ejemplo.
Referencia del SDK
Paquetes NuGet:
• AWSSDK.IdentityManagement
Elementos de programación:
• NamespaceAmazon.identityManagement
ClaseAmazonIdentityManagementServiceClient• NamespaceAmazon.identityManagement.model
ClaseGetPolicyVersionRequest
ClaseGetPolicyVersionResponse
ClaseListPolicyVersionsRequest
ClaseListPolicyVersionsResponse
ClasePolicyVersion
113
AWS SDK for .NET Developer GuideVisualización de documentos de políticas
El código
using System;using System.Web;using System.Threading.Tasks;using Amazon.IdentityManagement;using Amazon.IdentityManagement.Model;
namespace IamDisplayPolicyJson{ class Program { static async Task Main(string[] args) { // Parse the command line and show help if necessary if(args.Length != 1) { Console.WriteLine("\nUsage: IamDisplayPolicyJson policy-arn"); Console.WriteLine(" policy-arn: The ARN of the policy to retrieve."); return; } if(!args[0].StartsWith("arn:")) { Console.WriteLine("\nCould not find policy ARN in the command-line arguments:"); Console.WriteLine($"{args[0]}"); return; }
// Create an IAM service client var iamClient = new AmazonIdentityManagementServiceClient();
// Retrieve and display the policy document of the given policy string defaultVersion = await GetDefaultVersion(iamClient, args[0]); if(string.IsNullOrEmpty(defaultVersion)) Console.WriteLine($"Could not find the default version for policy {args[0]}."); else await ShowPolicyDocument(iamClient, args[0], defaultVersion); }
// // Method to determine the default version of an IAM policy // Returns a string with the version private static async Task<string> GetDefaultVersion( IAmazonIdentityManagementService iamClient, string policyArn) { // Retrieve all the versions of this policy string defaultVersion = string.Empty; ListPolicyVersionsResponse reponseVersions = await iamClient.ListPolicyVersionsAsync(new ListPolicyVersionsRequest{ PolicyArn = policyArn});
// Find the default version foreach(PolicyVersion version in reponseVersions.Versions) { if(version.IsDefaultVersion) { defaultVersion = version.VersionId; break; } }
return defaultVersion; }
114
AWS SDK for .NET Developer GuideConceder acceso con un rol
// // Method to retrieve and display the policy document of an IAM policy private static async Task ShowPolicyDocument( IAmazonIdentityManagementService iamClient, string policyArn, string defaultVersion) { // Retrieve the policy document of the default version GetPolicyVersionResponse responsePolicy = await iamClient.GetPolicyVersionAsync(new GetPolicyVersionRequest{ PolicyArn = policyArn, VersionId = defaultVersion});
// Display the policy document (in JSON) Console.WriteLine($"Version {defaultVersion} of the policy (in JSON format):"); Console.WriteLine( $"{HttpUtility.UrlDecode(responsePolicy.PolicyVersion.Document)}"); } }}
Conceder acceso mediante un rol de IAMEn este tutorial se muestra cómo utilizar laAWS SDK for .NETPara habilitar las funciones de IAM eninstancias Amazon EC2.
OverviewTodas las solicitudesAWSDebe firmarse criptográficamente mediante credenciales emitidas porAWS. Portanto, es necesaria una estrategia para administrar credenciales para las aplicaciones que se ejecutan eninstancias de Amazon EC2. Debe distribuir, almacenar y rotar estas credenciales de forma segura, perotambién mantenerlas accesibles para las aplicaciones.
Con los roles de IAM, puede administrar eficazmente estas credenciales. Cree un rol de IAM y lo configurecon los permisos que requiere una aplicación y, a continuación, asóese rol a una instancia EC2. Leamás acerca de las ventajas de utilizar roles de IAM en laGuía del usuario de EC2 para Linuxo elGuía delusuario de EC2 para Windows. Vea también la información sobreRoles de IAMen la guía del usuario deIAM.
Para una aplicación que se crea utilizando el métodoAWS SDK for .NET, cuando la aplicación construyeun objeto cliente para un objetoAWS, el objeto busca credenciales de varias fuentes potenciales. El ordenen que se realiza la búsqueda se muestra enCredenciales y resolución de perfiles (p. 25).
Si el objeto cliente no encuentra credenciales de ningún otro origen, recuperará credenciales temporalescon los mismos permisos que aquellos que se han configurado en el rol de IAM y que están en losmetadatos de la instancia EC2. Estas credenciales se utilizan para realizar llamadas aAWSdesde el objetocliente.
Acerca de este tutorialA medida que siga este tutorial, se utiliza laAWS SDK for .NET(y otras herramientas) para iniciar unainstancia de Amazon EC2 con una función de IAM adjunta y, a continuación, ver una aplicación en lainstancia utilizando los permisos del rol de IAM.
Temas• Cree una aplicación de ejemplo de Amazon S3 (p. 116)• Crear un rol de IAM (p. 118)• Lance una instancia EC2 y adjunte la función de IAM (p. 119)• Connect a la instancia EC2 (p. 119)
115
AWS SDK for .NET Developer GuideConceder acceso con un rol
• Ejecutar la aplicación de ejemplo en la instancia EC2 (p. 119)• Eliminar recursos (p. 120)
Cree una aplicación de ejemplo de Amazon S3Esta aplicación de ejemplo recuperará un objeto de Amazon S3. Para ejecutar la aplicación, necesita losiguiente:
• Un bucket de Amazon S3 que contiene un archivo de texto.• AWSen su máquina de desarrollo que le permiten acceder al bucket.
Para obtener información acerca de cómo crear un bucket de Amazon S3 y cargar un objeto,consulte laGuía de introducción a Amazon S3. Para obtener información sobreAWScredenciales,consulteConfiguraciónAWScredenciales (p. 20).
Cree un proyecto de .NET Core con el siguiente código. A continuación, pruebe la aplicación en sumáquina de desarrollo.
Note
En su máquina de desarrollo, se instala de.NET Core Runtime, lo que le permite ejecutar laaplicación sin publicarla. Cuando cree una instancia de EC2 más adelante en este aprendizaje,puede optar por instalar de.NET Core Runtime en la instancia. Esto le da una experiencia similar yuna transferencia de archivos más pequeña.Sin embargo, también puede elegir no instalar de.NET Core Runtime en la instancia. Si eligeeste curso de acción, debe publicar la aplicación para que se incluyan todas las dependencias altransferirla a la instancia.
Referencia del SDK
Paquetes NuGet:
• AWSSDK.S3
Elementos de programación:
• NamespaceAmazon.S3
ClaseAmazons3Client• NamespaceAmazon.S3.Model
ClaseGetObjectResponse
El código
using System;using System.Collections.Generic;using System.IO;using System.Threading.Tasks;using Amazon.S3;using Amazon.S3.Model;
namespace S3GetTextItem{ // = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = // Class to retrieve a text file from an S3 bucket and write it to a local file
116
AWS SDK for .NET Developer GuideConceder acceso con un rol
class Program { static async Task Main(string[] args) { // Parse the command line and show help if necessary var parsedArgs = CommandLine.Parse(args); if(parsedArgs.Count == 0) { PrintHelp(); return; }
// Get the application parameters from the parsed arguments string bucket = CommandLine.GetParameter(parsedArgs, null, "-b", "--bucket-name"); string item = CommandLine.GetParameter(parsedArgs, null, "-t", "--text-object"); string outFile = CommandLine.GetParameter(parsedArgs, null, "-o", "--output-filename"); if( string.IsNullOrEmpty(bucket) || string.IsNullOrEmpty(item) || string.IsNullOrEmpty(outFile)) CommandLine.ErrorExit( "\nOne or more of the required arguments is missing or incorrect." + "\nRun the command with no arguments to see help.");
// Create the S3 client object and get the file object from the bucket. var response = await GetObject(new AmazonS3Client(), bucket, item);
// Write the contents of the file object to the given output file. var reader = new StreamReader(response.ResponseStream); string contents = reader.ReadToEnd(); using (var s = new FileStream(outFile, FileMode.Create)) using (var writer = new StreamWriter(s)) writer.WriteLine(contents); }
// // Method to get an object from an S3 bucket. private static async Task<GetObjectResponse> GetObject( IAmazonS3 s3Client, string bucket, string item) { Console.WriteLine($"Retrieving {item} from bucket {bucket}."); return await s3Client.GetObjectAsync(bucket, item); }
// // Command-line help private static void PrintHelp() { Console.WriteLine( "\nUsage: S3GetTextItem -b <bucket-name> -t <text-object> -o <output-filename>" + "\n -b, --bucket-name: The name of the S3 bucket." + "\n -t, --text-object: The name of the text object in the bucket." + "\n -o, --output-filename: The name of the file to write the text to."); } }
// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = // Class that represents a command line on the console or terminal // (This is the same for all examples. When you have seen it once, you can ignore it) static class CommandLine
117
AWS SDK for .NET Developer GuideConceder acceso con un rol
{ // Method to parse a command line of the form: "--param value" or "-p value". // If "param" is found without a matching "value", Dictionary.Value is an empty string. // If "value" is found without a matching "param", Dictionary.Key is "--NoKeyN" // where "N" represents sequential numbers. public static Dictionary<string,string> Parse(string[] args) { var parsedArgs = new Dictionary<string,string>(); int i = 0, n = 0; while(i < args.Length) { // If the first argument in this iteration starts with a dash it's an option. if(args[i].StartsWith("-")) { var key = args[i++]; var value = string.Empty;
// Is there a value that goes with this option? if((i < args.Length) && (!args[i].StartsWith("-"))) value = args[i++]; parsedArgs.Add(key, value); }
// If the first argument in this iteration doesn't start with a dash, it's a value else { parsedArgs.Add("--NoKey" + n.ToString(), args[i++]); n++; } }
return parsedArgs; }
// // Method to get a parameter from the parsed command-line arguments public static string GetParameter( Dictionary<string,string> parsedArgs, string def, params string[] keys) { string retval = null; foreach(var key in keys) if(parsedArgs.TryGetValue(key, out retval)) break; return retval ?? def; }
// // Exit with an error. public static void ErrorExit(string msg, int code=1) { Console.WriteLine("\nError"); Console.WriteLine(msg); Environment.Exit(code); } }
}
Si lo desea, puede quitar temporalmente las credenciales que utiliza en su máquina de desarrollo para vercómo responde la aplicación. (Pero asegúrese de restaurar las credenciales cuando haya terminado).
Crear un rol de IAMCree un rol de IAM que tenga los permisos adecuados para obtener acceso a Amazon S3.
1. Abra la consola de IAM.
118
AWS SDK for .NET Developer GuideConceder acceso con un rol
2. En el panel de navegación, seleccioneRoles dey luego seleccioneCreación de un rol.3. SelectAWSServicio de, busque y seleccioneEC2, y elijaSiguiente: Permisos.4. BajoAdjuntar políticas de permisos, busque y seleccioneAmazonS3ReadOnlyAccess. Revise la
política si lo desea y, a continuación, elijaSiguiente: Tags (Etiquetas).5. Agregue etiquetas si lo desea y, a continuación, elijaSiguiente: Consulte.6. Escriba un nombre y una descripción para el rol y, a continuación, elija Create rol (Crear rol).
Recuerde este nombre, ya que lo necesitará cuando lance su instancia EC2.
Lance una instancia EC2 y adjunte la función de IAMLance una instancia EC2 con el rol de IAM que creó anteriormente. Puede hacerlo de las siguientesmaneras:
• Uso de la consola de EC2
Siga las indicaciones para iniciar una instancia en laGuía del usuario de EC2 para Linuxo elGuía delusuario de EC2 para Windows.
A medida que pasa por el asistente, al menos debe visitar elPágina Configure Instance Details(Configurar los detalles de la instancia)para que pueda seleccionar la opciónRol de IAMCreó antes.
• Mediante la AWS SDK for .NET
Para obtener más información acerca de este tema, consulteLanzamiento de una instancia AmazonEC2 (p. 78), incluido elConsideraciones adicionalescerca del final de ese tema.
Para iniciar una instancia de EC2 que tenga un rol de IAM asociado, la configuración de un usuario de IAMdebe incluir determinados permisos. Para obtener más información acerca de los permisos necesarios,consulte laGuía del usuario de EC2 para Linuxo elGuía del usuario de EC2 para Windows.
Connect a la instancia EC2Connect a la instancia de EC2 para que pueda transferir la aplicación de ejemplo a ella y, a continuación,ejecute la aplicación. Necesitará el archivo que contiene la parte privada del key pair que utilizó para lanzarla instancia; es decir, el archivo PEM.
Puede hacerlo siguiendo el procedimiento de conexión en el cuadro de diálogoGuía del usuario de EC2para Linuxo elGuía del usuario de EC2 para Windows. Cuando se conecte, hágalo de tal manera quepueda transferir archivos de su máquina de desarrollo a su instancia.
Si utiliza Visual Studio en Windows, también puede conectarse a la instancia mediante el Toolkit for VisualStudio. Para obtener más información, consulteConexión a una instancia de Amazon EC2en laAWS Toolkitfor Visual StudioGuía del usuario de .
Ejecutar la aplicación de ejemplo en la instancia EC21. Copie los archivos de aplicación de la unidad local a la instancia.
Los archivos que transfiera dependen de cómo creó la aplicación y de si la instancia tiene instaladode.NET Core Runtime. Para obtener información acerca de cómo transferir archivos a la instancia,consulte laGuía del usuario de EC2 para Linuxo elGuía del usuario de EC2 para Windows.
2. Inicie la aplicación y compruebe que se ejecuta con los mismos resultados que en su máquina dedesarrollo.
119
AWS SDK for .NET Developer GuideAmazon S3
3. Compruebe que la aplicación utiliza las credenciales proporcionadas por el rol de IAM.
a. Abra la consola de Amazon EC2.b. Seleccione la instancia y desconecte el rol de IAM a través deActions,Configuración de la
instancia,Adjuntar/reemplazar rol de IAM.c. Vuelva a ejecutar la aplicación y compruebe que devuelve un error de autorización.
Eliminar recursosCuando haya terminado con este aprendizaje, y si ya no desea la instancia de EC2 creada, asegúresede terminar la instancia para evitar costes no deseados. Puede hacerlo en elConsola de Amazon EC2omediante programación, como se describe enTerminación de una instancia Amazon EC2 (p. 89). Si lodesea, puede eliminar otros recursos que creó para este tutorial. Estos pueden incluir un rol de IAM, un parde claves EC2 y un archivo PEM, un grupo de seguridad, etc.
Uso del almacenamiento en Internet de AmazonSimple Storage Service
LaAWS SDK for .NETes compatible conAmazon S3, que es almacenamiento para Internet. Está diseñadopara facilitar a los desarrolladores recursos de computación escalables basados en Web.
APIsLaAWS SDK for .NETproporciona API para clientes de Amazon S3. Las API le permiten trabajar conrecursos de Amazon S3, como depósitos y elementos. Para ver el conjunto completo de API para AmazonS3, consulte lo siguiente:
• AWS SDK for .NETReferencia de la API(y desplácese hasta «Amazon.S3").• Amazon.Extensions.S3.CifradoDocumentación de
Las API de Amazon S3 se proporcionan mediante los siguientes paquetes NuGet:
• AWSSDK.S3• Amazon.Extensions.S3.Cifrado
PrerequisitesAntes de comenzar, asegúrese de que tieneConfiguración del entorno (p. 15). Revise también lainformación deConfiguración del proyecto (p. 17)yCaracterísticas del SDK (p. 36).
Ejemplos de este documentoEn los siguientes temas de este documento, se muestra cómo utilizar la claseAWS SDK for .NETParatrabajar con Amazon S3.
• Uso de claves KMS para el cifrado S3 (p. 121)
120
AWS SDK for .NET Developer GuideEjemplos en otros documentos
Ejemplos en otros documentosLos siguientes enlaces a laGuía para desarrolladores de Amazon S3Proporciona ejemplos adicionales decómo usar la claseAWS SDK for .NETPara trabajar con Amazon S3.
Note
Aunque estos ejemplos y consideraciones de programación adicionales se crearon para la versión3 delAWS SDK for .NETusando .NET Framework, también son viables para versiones posterioresde laAWS SDK for .NETUso de .NET Core. A veces son necesarios pequeños ajustes en elcódigo.
Ejemplos de programación de Amazon S3
• Administración de las ACL• Creación de un bucket• Carga de un objeto• Carga multiparte con la API de alto nivel (Amazon.S3.transfer.Transfer.TransferUtility)• Carga multiparte con la API de bajo nivel• Listas de objetos• Lista de claves• Obtención de un objeto• Copia de un objeto• Copia de un objeto con la API de carga multiparte• Eliminación de un objeto• Eliminación de varios objetos• Restauración de un objeto• Configuración de un bucket para las notificaciones• Administración del ciclo de vida de un objeto• Generación de una URL de objeto prefirmada• Administración de sitios web• Habilitación del uso compartido de recursos entre orígenes (CORS)
Consideraciones adicionales sobre la programación
• Mediante laAWS SDK for .NETProgramación de Amazon S3• Realización de solicitudes con las credenciales temporales de usuario de IAM• Realización de solicitudes con credenciales temporales de usuario federado• Especificación de cifrado del lado del servidor• Especificación de cifrado del lado del servidor con claves de cifrado proporcionadas por el cliente
Uso deAWS KMSPara el cifrado de Amazon S3 en laclaseAWS SDK for .NETEn este ejemplo puede ver cómo utilizar el uso deAWS Key Management Servicepara cifrar objetosde Amazon S3. La aplicación crea una clave maestra de cliente (CMK) y la utiliza para crear una clavemaestra de cliente (CMK).Amazons3EncryptionClientv2Para el cifrado del lado del cliente. La aplicación
121
AWS SDK for .NET Developer GuideUso de claves KMS para el cifrado S3
utiliza ese cliente para crear un objeto cifrado a partir de un archivo de texto determinado en un depósitode Amazon S3 existente. A continuación, descifra el objeto y muestra su contenido.
Warning
Una clase similar llamadaAmazonS3EncryptionClientestá en desuso y es menosseguro que elAmazonS3EncryptionClientV2La clase. Para migrar código existente queutilizaAmazonS3EncryptionClient, consulteMigración de clientes de cifrado de S3 (p. 167).
Temas• Creación de materiales de cifrado (p. 122)• Creación y cifrado de un objeto de Amazon S3 (p. 122)• Completa el código (p. 123)
Creación de materiales de cifradoEl siguiente fragmento crea un objeto deEncryptionMaterialsque contiene un ID de clave de KMS.
El ejemploAl final de este tema (p. 123)muestra este fragmento en uso.
// Create a customer master key (CMK) and store the result CreateKeyResponse createKeyResponse = await new AmazonKeyManagementServiceClient().CreateKeyAsync(new CreateKeyRequest()); var kmsEncryptionContext = new Dictionary<string, string>(); var kmsEncryptionMaterials = new EncryptionMaterialsV2( createKeyResponse.KeyMetadata.KeyId, KmsType.KmsContext, kmsEncryptionContext);
Creación y cifrado de un objeto de Amazon S3El siguiente fragmento crea un objeto deAmazonS3EncryptionClientV2que utiliza los materiales decifrado creados anteriormente. A continuación, utiliza el cliente para crear y cifrar un nuevo objeto deAmazon S3.
El ejemploAl final de este tema (p. 123)muestra este fragmento en uso.
// // Method to create and encrypt an object in an S3 bucket static async Task<GetObjectResponse> CreateAndRetrieveObjectAsync( EncryptionMaterialsV2 materials, string bucketName, string fileName, string itemName) { // CryptoStorageMode.ObjectMetadata is required for KMS EncryptionMaterials var config = new AmazonS3CryptoConfigurationV2(SecurityProfile.V2AndLegacy) { StorageMode = CryptoStorageMode.ObjectMetadata }; var s3EncClient = new AmazonS3EncryptionClientV2(config, materials);
// Create, encrypt, and put the object await s3EncClient.PutObjectAsync(new PutObjectRequest { BucketName = bucketName, Key = itemName, ContentBody = File.ReadAllText(fileName) });
// Get, decrypt, and return the object return await s3EncClient.GetObjectAsync(new GetObjectRequest {
122
AWS SDK for .NET Developer GuideUso de claves KMS para el cifrado S3
BucketName = bucketName, Key = itemName }); }
Completa el códigoEn esta sección se muestran las referencias relevantes y el código completo de este ejemplo.
Referencias de SDK de
Paquetes NuGet:
• Amazon.Extensions.S3.Cifrado
Elementos de programación:
• NamespaceAmazon.Extensions.S3.Cifrado
ClaseAmazons3EncryptionClientv2
ClaseAmazons3CryptoConfigurationv2
ClaseCryptoStorageMode
ClaseEncryptionMaterialSv2• NamespaceAmazon.Extensions.S3.Encryption.Primitives
ClaseKmStype• NamespaceAmazon.S3.Modelo
ClaseGetObjectRequest
ClaseGetObjectResponse
ClasePutObjectRequest• NamespaceAmazon.keymanagementService
ClaseAmazonKeyManagementServiceClient• NamespaceAmazon.keymanagementService.model
ClaseCreateKeyRequest
ClaseCreateKeyResponse
El código
using System;using System.Collections.Generic;using System.IO;using System.Threading.Tasks;using Amazon.Extensions.S3.Encryption;using Amazon.Extensions.S3.Encryption.Primitives;using Amazon.S3.Model;using Amazon.KeyManagementService;using Amazon.KeyManagementService.Model;
namespace KmsS3Encryption
123
AWS SDK for .NET Developer GuideUso de claves KMS para el cifrado S3
{ // = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = // Class to store text in an encrypted S3 object. class Program { private const int MaxArgs = 3;
public static async Task Main(string[] args) { // Parse the command line and show help if necessary var parsedArgs = CommandLine.Parse(args); if((parsedArgs.Count == 0) || (parsedArgs.Count > MaxArgs)) { PrintHelp(); return; }
// Get the application parameters from the parsed arguments string bucketName = CommandLine.GetParameter(parsedArgs, null, "-b", "--bucket-name"); string fileName = CommandLine.GetParameter(parsedArgs, null, "-f", "--file-name"); string itemName = CommandLine.GetParameter(parsedArgs, null, "-i", "--item-name"); if(string.IsNullOrEmpty(bucketName) || (string.IsNullOrEmpty(fileName))) CommandLine.ErrorExit( "\nOne or more of the required arguments is missing or incorrect." + "\nRun the command with no arguments to see help."); if(!File.Exists(fileName)) CommandLine.ErrorExit($"\nThe given file {fileName} doesn't exist."); if(string.IsNullOrEmpty(itemName)) itemName = Path.GetFileName(fileName);
// Create a customer master key (CMK) and store the result CreateKeyResponse createKeyResponse = await new AmazonKeyManagementServiceClient().CreateKeyAsync(new CreateKeyRequest()); var kmsEncryptionContext = new Dictionary<string, string>(); var kmsEncryptionMaterials = new EncryptionMaterialsV2( createKeyResponse.KeyMetadata.KeyId, KmsType.KmsContext, kmsEncryptionContext);
// Create the object in the bucket, then display the content of the object var putObjectResponse = await CreateAndRetrieveObjectAsync(kmsEncryptionMaterials, bucketName, fileName, itemName); Stream stream = putObjectResponse.ResponseStream; StreamReader reader = new StreamReader(stream); Console.WriteLine(reader.ReadToEnd()); }
// // Method to create and encrypt an object in an S3 bucket static async Task<GetObjectResponse> CreateAndRetrieveObjectAsync( EncryptionMaterialsV2 materials, string bucketName, string fileName, string itemName) { // CryptoStorageMode.ObjectMetadata is required for KMS EncryptionMaterials var config = new AmazonS3CryptoConfigurationV2(SecurityProfile.V2AndLegacy) { StorageMode = CryptoStorageMode.ObjectMetadata }; var s3EncClient = new AmazonS3EncryptionClientV2(config, materials);
// Create, encrypt, and put the object
124
AWS SDK for .NET Developer GuideUso de claves KMS para el cifrado S3
await s3EncClient.PutObjectAsync(new PutObjectRequest { BucketName = bucketName, Key = itemName, ContentBody = File.ReadAllText(fileName) });
// Get, decrypt, and return the object return await s3EncClient.GetObjectAsync(new GetObjectRequest { BucketName = bucketName, Key = itemName }); }
// // Command-line help private static void PrintHelp() { Console.WriteLine( "\nUsage: KmsS3Encryption -b <bucket-name> -f <file-name> [-i <item-name>]" + "\n -b, --bucket-name: The name of an existing S3 bucket." + "\n -f, --file-name: The name of a text file with content to encrypt and store in S3." + "\n -i, --item-name: The name you want to use for the item." + "\n If item-name isn't given, file-name will be used."); }
}
// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = // Class that represents a command line on the console or terminal // (This is the same for all examples. When you have seen it once, you can ignore it) static class CommandLine { // Method to parse a command line of the form: "--param value" or "-p value". // If "param" is found without a matching "value", Dictionary.Value is an empty string. // If "value" is found without a matching "param", Dictionary.Key is "--NoKeyN" // where "N" represents sequential numbers. public static Dictionary<string,string> Parse(string[] args) { var parsedArgs = new Dictionary<string,string>(); int i = 0, n = 0; while(i < args.Length) { // If the first argument in this iteration starts with a dash it's an option. if(args[i].StartsWith("-")) { var key = args[i++]; var value = string.Empty;
// Is there a value that goes with this option? if((i < args.Length) && (!args[i].StartsWith("-"))) value = args[i++]; parsedArgs.Add(key, value); }
// If the first argument in this iteration doesn't start with a dash, it's a value else { parsedArgs.Add("--NoKey" + n.ToString(), args[i++]); n++; } }
125
AWS SDK for .NET Developer GuideAmazon SQS
return parsedArgs; }
// // Method to get a parameter from the parsed command-line arguments public static string GetParameter( Dictionary<string,string> parsedArgs, string def, params string[] keys) { string retval = null; foreach(var key in keys) if(parsedArgs.TryGetValue(key, out retval)) break; return retval ?? def; }
// // Exit with an error. public static void ErrorExit(string msg, int code=1) { Console.WriteLine("\nError"); Console.WriteLine(msg); Environment.Exit(code); } }
}
Consideraciones adicionales
• Puede comprobar los resultados de este ejemplo. Para ello, vaya a la páginaConsola de Amazon S3yabra el depósito que proporcionó a la aplicación. A continuación, busque el objeto nuevo, descárguelo yábralo en un editor de texto.
• LaAmazons3EncryptionClientv2La clase implementa la misma interfaz que la claseAmazonS3ClientLaclase. Esto facilita el puerto del código alAmazonS3EncryptionClientV2para que el cifrado y eldescifrado se realicen de forma automática y transparente en el cliente.
• Una ventaja de usar unAWS KMSLa clave maestra es que no necesita almacenar y administrarsus propias claves maestras; esto se realiza medianteAWS. Una segunda ventaja es queelAmazonS3EncryptionClientV2La claseAWS SDK for .NETes interoperable conelAmazonS3EncryptionClientV2La claseAWS SDK for Java. Esto significa que puede cifrar conAWS SDK for Java y descifrar con AWS SDK for .NET y viceversa.
Note
LaAmazonS3EncryptionClientV2La claseAWS SDK for .NETadmite las claves maestrasde KMS solo cuando se ejecuta en modo de metadatos. El modo de archivo de instruccionesdelAmazonS3EncryptionClientV2La claseAWS SDK for .NETes incompatible conelAmazonS3EncryptionClientV2La claseAWS SDK for Java.
• Para obtener más información sobre el cifrado del lado del cliente conelAmazonS3EncryptionClientV2La clase y cómo funciona el cifrado de sobre, consulteCifrado dedatos del lado del clienteAWS SDK for .NETy Amazon S3.
Mensajes mediante Amazon SQSLaAWS SDK for .NETes compatible conAmazon Simple Queue Service (Amazon SQS)El es un servicio decolas de mensaje que gestiona mensajes o flujos de trabajo entre componentes en un sistema.
126
AWS SDK for .NET Developer GuideAPIs
Las colas de Amazon SQS proporcionan un mecanismo que permite enviar, almacenar y recibir mensajesentre componentes de software, como microservicios, sistemas distribuidos y aplicaciones sin servidor.Esto le permite desacoplar dichos componentes y le libera de la necesidad de diseñar y operar su propiosistema de mensajería. Para obtener información acerca del funcionamiento de las colas y los mensajes enAmazon SQS, consulteAprendizajes de Amazon SQSyCómo funciona Amazon SQSen laAmazon SimpleQueue Service.
Important
Debido a las características de distribución de las colas, Amazon SQS no puede garantizar quevaya a recibir los mensajes en el mismo orden en que se envían. Si necesita conservar el ordende los mensajes, utilice unCola de Amazon SQS.
APIsLaAWS SDK for .NETproporciona API para clientes de Amazon SQS. Las API le permiten trabajar confunciones de Amazon SQS, como colas y mensajes. Esta sección contiene un pequeño número deejemplos que muestran los patrones que puede seguir al trabajar con estas API. Para ver el conjuntocompleto de API, consulte laAWS SDK for .NETReferencia de la API(y desplácese hasta «Amazon.sqs»).
Las API de Amazon SQS son proporcionadas por elAWSSDK.SQSPaquete NuGet
PrerequisitesAntes de comenzar, asegúrese de que tieneConfiguración del entorno (p. 15). Revise también lainformación deConfiguración del proyecto (p. 17)yCaracterísticas del SDK (p. 36).
TopicsTemas
• Creación de colas de Amazon SQS (p. 127)• Actualización de las colas de Amazon SQS (p. 133)• Eliminación de las colas de Amazon SQS (p. 138)• Envío de mensajes de Amazon SQS (p. 142)• Recepción de mensajes de Amazon SQS (p. 145)
Creación de colas de Amazon SQSEn este ejemplo puede ver cómo utilizar elAWS SDK for .NETPara crear una cola de Amazon SQS. Laaplicación crea unCola de mensajes muertassi no suministra el ARN para uno. A continuación, crea unacola de mensajes estándar, que incluye una cola de letras muertas (la que proporcionó o la que se creó).
Si no proporciona ningún argumento de línea de comandos, la aplicación simplemente muestrainformación sobre todas las colas existentes.
En las secciones siguientes, se incluyen fragmentos de este ejemplo. Lacódigo completo para elejemplo (p. 129)se muestra después de eso, y se puede construir y ejecutar tal como está.
Temas• Mostrar colas existentes (p. 128)• Creación de la cola (p. 128)• Obtener el ARN de una cola (p. 129)• Completa código (p. 129)
127
AWS SDK for .NET Developer GuideCreación de colas
Mostrar colas existentesEl siguiente fragmento muestra una lista de las colas existentes en la región del cliente SQS y los atributosde cada cola.
El ejemploal final de este tema (p. 129)muestra este fragmento en uso.
// // Method to show a list of the existing queues private static async Task ShowQueues(IAmazonSQS sqsClient) { ListQueuesResponse responseList = await sqsClient.ListQueuesAsync(""); Console.WriteLine(); foreach(string qUrl in responseList.QueueUrls) { // Get and show all attributes. Could also get a subset. await ShowAllAttributes(sqsClient, qUrl); } }
// // Method to show all attributes of a queue private static async Task ShowAllAttributes(IAmazonSQS sqsClient, string qUrl) { var attributes = new List<string>{ QueueAttributeName.All }; GetQueueAttributesResponse responseGetAtt = await sqsClient.GetQueueAttributesAsync(qUrl, attributes); Console.WriteLine($"Queue: {qUrl}"); foreach(var att in responseGetAtt.Attributes) Console.WriteLine($"\t{att.Key}: {att.Value}"); }
Creación de la colaEl siguiente fragmento crea una cola. El fragmento incluye el uso de una cola de letras muertas, pero unacola de letras muertas no es necesariamente necesaria para las colas.
El ejemploal final de este tema (p. 129)muestra este fragmento en uso.
// // Method to create a queue. Returns the queue URL. private static async Task<string> CreateQueue( IAmazonSQS sqsClient, string qName, string deadLetterQueueUrl=null, string maxReceiveCount=null, string receiveWaitTime=null) { var attrs = new Dictionary<string, string>();
// If a dead-letter queue is given, create a message queue if(!string.IsNullOrEmpty(deadLetterQueueUrl)) { attrs.Add(QueueAttributeName.ReceiveMessageWaitTimeSeconds, receiveWaitTime); attrs.Add(QueueAttributeName.RedrivePolicy, $"{{\"deadLetterTargetArn\":\"{await GetQueueArn(sqsClient, deadLetterQueueUrl)}\"," + $"\"maxReceiveCount\":\"{maxReceiveCount}\"}}"); // Add other attributes for the message queue such as VisibilityTimeout }
// If no dead-letter queue is given, create one of those instead //else //{ // // Add attributes for the dead-letter queue as needed // attrs.Add();
128
AWS SDK for .NET Developer GuideCreación de colas
//}
// Create the queue CreateQueueResponse responseCreate = await sqsClient.CreateQueueAsync( new CreateQueueRequest{QueueName = qName, Attributes = attrs}); return responseCreate.QueueUrl; }
Obtener el ARN de una colaEl siguiente fragmento obtiene el ARN de la cola identificada por la URL de la cola dada.
El ejemploal final de este tema (p. 129)muestra este fragmento en uso.
// // Method to get the ARN of a queue private static async Task<string> GetQueueArn(IAmazonSQS sqsClient, string qUrl) { GetQueueAttributesResponse responseGetAtt = await sqsClient.GetQueueAttributesAsync( qUrl, new List<string>{QueueAttributeName.QueueArn}); return responseGetAtt.QueueARN; }
Completa códigoEn esta sección puede ver las referencias relevantes y el código completo de este ejemplo.
Referencia del SDK
Paquetes NuGet:
• AWSSDK.SQS
Elementos de programación:
• NamespaceAmazon.sqs
ClaseAmazonSQSClient
ClaseQueueAttributeName• NamespaceAmazon.sqs.model
ClaseCreateQueueRequest
ClaseCreateQueueResponse
ClasegetQueueAttributesResponse
ClaseListQueuesResponse
El código
using System;using System.Threading.Tasks;using System.Collections.Generic;using Amazon.SQS;using Amazon.SQS.Model;
namespace SQSCreateQueue
129
AWS SDK for .NET Developer GuideCreación de colas
{ // = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = // Class to create a queue class Program { private const string MaxReceiveCount = "10"; private const string ReceiveMessageWaitTime = "2"; private const int MaxArgs = 3;
static async Task Main(string[] args) { // Parse the command line and show help if necessary var parsedArgs = CommandLine.Parse(args); if(parsedArgs.Count > MaxArgs) CommandLine.ErrorExit( "\nToo many command-line arguments.\nRun the command with no arguments to see help.");
// Create the Amazon SQS client var sqsClient = new AmazonSQSClient();
// In the case of no command-line arguments, just show help and the existing queues if(parsedArgs.Count == 0) { PrintHelp(); Console.WriteLine("\nNo arguments specified."); Console.Write("Do you want to see a list of the existing queues? ((y) or n): "); string response = Console.ReadLine(); if((string.IsNullOrEmpty(response)) || (response.ToLower() == "y")) await ShowQueues(sqsClient); return; }
// Get the application parameters from the parsed arguments string queueName = CommandLine.GetParameter(parsedArgs, null, "-q", "--queue-name"); string deadLetterQueueUrl = CommandLine.GetParameter(parsedArgs, null, "-d", "--dead-letter-queue"); string maxReceiveCount = CommandLine.GetParameter(parsedArgs, MaxReceiveCount, "-m", "--max-receive-count"); string receiveWaitTime = CommandLine.GetParameter(parsedArgs, ReceiveMessageWaitTime, "-w", "--wait-time");
if(string.IsNullOrEmpty(queueName)) CommandLine.ErrorExit( "\nYou must supply a queue name.\nRun the command with no arguments to see help.");
// If a dead-letter queue wasn't given, create one if(string.IsNullOrEmpty(deadLetterQueueUrl)) { Console.WriteLine("\nNo dead-letter queue was specified. Creating one..."); deadLetterQueueUrl = await CreateQueue(sqsClient, queueName + "__dlq"); Console.WriteLine($"Your new dead-letter queue:"); await ShowAllAttributes(sqsClient, deadLetterQueueUrl); }
// Create the message queue string messageQueueUrl = await CreateQueue( sqsClient, queueName, deadLetterQueueUrl, maxReceiveCount, receiveWaitTime); Console.WriteLine($"Your new message queue:"); await ShowAllAttributes(sqsClient, messageQueueUrl); }
130
AWS SDK for .NET Developer GuideCreación de colas
// // Method to show a list of the existing queues private static async Task ShowQueues(IAmazonSQS sqsClient) { ListQueuesResponse responseList = await sqsClient.ListQueuesAsync(""); Console.WriteLine(); foreach(string qUrl in responseList.QueueUrls) { // Get and show all attributes. Could also get a subset. await ShowAllAttributes(sqsClient, qUrl); } }
// // Method to create a queue. Returns the queue URL. private static async Task<string> CreateQueue( IAmazonSQS sqsClient, string qName, string deadLetterQueueUrl=null, string maxReceiveCount=null, string receiveWaitTime=null) { var attrs = new Dictionary<string, string>();
// If a dead-letter queue is given, create a message queue if(!string.IsNullOrEmpty(deadLetterQueueUrl)) { attrs.Add(QueueAttributeName.ReceiveMessageWaitTimeSeconds, receiveWaitTime); attrs.Add(QueueAttributeName.RedrivePolicy, $"{{\"deadLetterTargetArn\":\"{await GetQueueArn(sqsClient, deadLetterQueueUrl)}\"," + $"\"maxReceiveCount\":\"{maxReceiveCount}\"}}"); // Add other attributes for the message queue such as VisibilityTimeout }
// If no dead-letter queue is given, create one of those instead //else //{ // // Add attributes for the dead-letter queue as needed // attrs.Add(); //}
// Create the queue CreateQueueResponse responseCreate = await sqsClient.CreateQueueAsync( new CreateQueueRequest{QueueName = qName, Attributes = attrs}); return responseCreate.QueueUrl; }
// // Method to get the ARN of a queue private static async Task<string> GetQueueArn(IAmazonSQS sqsClient, string qUrl) { GetQueueAttributesResponse responseGetAtt = await sqsClient.GetQueueAttributesAsync( qUrl, new List<string>{QueueAttributeName.QueueArn}); return responseGetAtt.QueueARN; }
// // Method to show all attributes of a queue private static async Task ShowAllAttributes(IAmazonSQS sqsClient, string qUrl) { var attributes = new List<string>{ QueueAttributeName.All }; GetQueueAttributesResponse responseGetAtt = await sqsClient.GetQueueAttributesAsync(qUrl, attributes); Console.WriteLine($"Queue: {qUrl}"); foreach(var att in responseGetAtt.Attributes)
131
AWS SDK for .NET Developer GuideCreación de colas
Console.WriteLine($"\t{att.Key}: {att.Value}"); }
// // Command-line help private static void PrintHelp() { Console.WriteLine( "\nUsage: SQSCreateQueue -q <queue-name> [-d <dead-letter-queue>]" + " [-m <max-receive-count>] [-w <wait-time>]" + "\n -q, --queue-name: The name of the queue you want to create." + "\n -d, --dead-letter-queue: The URL of an existing queue to be used as the dead-letter queue."+ "\n If this argument isn't supplied, a new dead-letter queue will be created." + "\n -m, --max-receive-count: The value for maxReceiveCount in the RedrivePolicy of the queue." + $"\n Default is {MaxReceiveCount}." + "\n -w, --wait-time: The value for ReceiveMessageWaitTimeSeconds of the queue for long polling." + $"\n Default is {ReceiveMessageWaitTime}."); } }
// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = // Class that represents a command line on the console or terminal. // (This is the same for all examples. When you have seen it once, you can ignore it.) public static class CommandLine { // Method to parse a command line of the form: "--param value" or "-p value". // If "param" is found without a matching "value", Dictionary.Value is an empty string. // If "value" is found without a matching "param", Dictionary.Key is "--NoKeyN" // where "N" represents sequential numbers. public static Dictionary<string,string> Parse(string[] args) { var parsedArgs = new Dictionary<string,string>(); int i = 0, n = 0; while(i < args.Length) { // If the first argument in this iteration starts with a dash it's an option. if(args[i].StartsWith("-")) { var key = args[i++]; var value = string.Empty;
// Is there a value that goes with this option? if((i < args.Length) && (!args[i].StartsWith("-"))) value = args[i++]; parsedArgs.Add(key, value); }
// If the first argument in this iteration doesn't start with a dash, it's a value else { parsedArgs.Add("--NoKey" + n.ToString(), args[i++]); n++; } }
return parsedArgs; }
// // Method to get a parameter from the parsed command-line arguments public static string GetParameter(
132
AWS SDK for .NET Developer GuideActualizar colas
Dictionary<string,string> parsedArgs, string def, params string[] keys) { string retval = null; foreach(var key in keys) if(parsedArgs.TryGetValue(key, out retval)) break; return retval ?? def; }
// // Exit with an error. public static void ErrorExit(string msg, int code=1) { Console.WriteLine("\nError"); Console.WriteLine(msg); Environment.Exit(code); } }
}
Consideraciones adicionales
• El nombre de la cola debe estar formado por caracteres alfanuméricos, guiones y guiones bajos.
• Los nombres y las URL de las colas distinguen entre mayúsculas y minúsculas
• Si necesita la URL de la cola pero solo tiene el nombre de la cola, use uno delosAmazonSQSClient.GetQueueUrlAsyncMétodos de.
• Para obtener información acerca de los diversos atributos de cola que puede establecer,consulteCreateQueueRequesten laAWS SDK for .NETReferencia de la APIorSetQueueAttributesenlaReferencia de la API de Amazon Simple Queue Service.
• En este ejemplo se especifica un sondeo largo para todos los mensajes de la cola que cree. Esto sehace mediante el uso de laReceiveMessageWaitTimeSecondsAtributo.
También puede especificar sondeo largo durante una llamada a laReceiveMessageAsyncMétodosde laAmazonSQSClientClase de. Para obtener más información, consulte Recepción de mensajes deAmazon SQS (p. 145).
Para obtener información acerca del sondeo corto y el sondeo largo, consulteSondeos cortos y largosenlaAmazon Simple Queue Service.
• Una cola de mensajes fallidos es una cola a la que otras colas (de origen) pueden enviar mensajes queno se han sido procesados correctamente. Para obtener más información, consulteColas de mensajesfallidos de Amazon SQSen la Guía para desarrolladores de Amazon Simple Queue Service.
• También puede ver la lista de colas y los resultados de este ejemplo en elConsola de Amazon SQS.
Actualización de las colas de Amazon SQSEn este ejemplo puede ver cómo utilizar elAWS SDK for .NETPara actualizar una cola de Amazon SQS.Después de algunas comprobaciones, la aplicación actualiza el atributo dado con el valor dado y, acontinuación, muestra todos los atributos de la cola.
133
AWS SDK for .NET Developer GuideActualizar colas
Si sólo se incluye la URL de la cola en los argumentos de la línea de comandos, la aplicación simplementemuestra todos los atributos de la cola.
En las secciones siguientes, se incluyen fragmentos de este ejemplo. Lacódigo completo para elejemplo (p. 135)se muestra después de eso, y se puede construir y ejecutar tal como está.
Temas• Mostrar atributos de cola (p. 134)• Validar nombre de atributo (p. 134)• Actualización del atributo de cola (p. 134)• Completa código (p. 135)
Mostrar atributos de colaEl siguiente fragmento muestra los atributos de la cola identificados por la URL de la cola dada.
El ejemploal final de este tema (p. 135)muestra este fragmento en uso.
// // Method to show all attributes of a queue private static async Task ShowAllAttributes(IAmazonSQS sqsClient, string qUrl) { GetQueueAttributesResponse responseGetAtt = await sqsClient.GetQueueAttributesAsync(qUrl, new List<string>{ QueueAttributeName.All }); Console.WriteLine($"Queue: {qUrl}"); foreach(var att in responseGetAtt.Attributes) Console.WriteLine($"\t{att.Key}: {att.Value}"); }
Validar nombre de atributoEl siguiente fragmento valida el nombre del atributo que se está actualizando.
El ejemploal final de este tema (p. 135)muestra este fragmento en uso.
// // Method to check the name of the attribute private static bool ValidAttribute(string attribute) { var attOk = false; var qAttNameType = typeof(QueueAttributeName); List<string> qAttNamefields = new List<string>(); foreach(var field in qAttNameType.GetFields()) qAttNamefields.Add(field.Name); foreach(var name in qAttNamefields) if(attribute == name) { attOk = true; break; } return attOk; }
Actualización del atributo de colaEl siguiente fragmento actualiza un atributo de la cola identificado por la URL de la cola dada.
El ejemploal final de este tema (p. 135)muestra este fragmento en uso.
134
AWS SDK for .NET Developer GuideActualizar colas
// // Method to update a queue attribute private static async Task UpdateAttribute( IAmazonSQS sqsClient, string qUrl, string attribute, string value) { await sqsClient.SetQueueAttributesAsync(qUrl, new Dictionary<string, string>{{attribute, value}}); }
Completa códigoEn esta sección puede ver las referencias relevantes y el código completo de este ejemplo.
Referencia del SDK
Paquetes NuGet:
• AWSSDK.SQS
Elementos de programación:
• NamespaceAmazon.sqs
ClaseAmazonSQSClient
ClaseQueueAttributeName• NamespaceAmazon.sqs.model
ClasegetQueueAttributesResponse
El código
using System;using System.Collections.Generic;using System.Threading.Tasks;using Amazon.SQS;using Amazon.SQS.Model;
namespace SQSUpdateQueue{ // = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = // Class to update a queue class Program { private const int MaxArgs = 3; private const int InvalidArgCount = 2;
static async Task Main(string[] args) { // Parse the command line and show help if necessary var parsedArgs = CommandLine.Parse(args); if(parsedArgs.Count == 0) { PrintHelp(); return; } if((parsedArgs.Count > MaxArgs) || (parsedArgs.Count == InvalidArgCount)) CommandLine.ErrorExit("\nThe number of command-line arguments is incorrect." +
135
AWS SDK for .NET Developer GuideActualizar colas
"\nRun the command with no arguments to see help.");
// Get the application parameters from the parsed arguments var qUrl = CommandLine.GetParameter(parsedArgs, null, "-q"); var attribute = CommandLine.GetParameter(parsedArgs, null, "-a"); var value = CommandLine.GetParameter(parsedArgs, null, "-v", "--value");
if(string.IsNullOrEmpty(qUrl)) CommandLine.ErrorExit("\nYou must supply at least a queue URL." + "\nRun the command with no arguments to see help.");
// Create the Amazon SQS client var sqsClient = new AmazonSQSClient();
// In the case of one command-line argument, just show the attributes for the queue if(parsedArgs.Count == 1) await ShowAllAttributes(sqsClient, qUrl);
// Otherwise, attempt to update the given queue attribute with the given value else { // Check to see if the attribute is valid if(ValidAttribute(attribute)) { // Perform the update and then show all the attributes of the queue await UpdateAttribute(sqsClient, qUrl, attribute, value); await ShowAllAttributes(sqsClient, qUrl); } else { Console.WriteLine($"\nThe given attribute name, {attribute}, isn't valid."); } } }
// // Method to show all attributes of a queue private static async Task ShowAllAttributes(IAmazonSQS sqsClient, string qUrl) { GetQueueAttributesResponse responseGetAtt = await sqsClient.GetQueueAttributesAsync(qUrl, new List<string>{ QueueAttributeName.All }); Console.WriteLine($"Queue: {qUrl}"); foreach(var att in responseGetAtt.Attributes) Console.WriteLine($"\t{att.Key}: {att.Value}"); }
// // Method to check the name of the attribute private static bool ValidAttribute(string attribute) { var attOk = false; var qAttNameType = typeof(QueueAttributeName); List<string> qAttNamefields = new List<string>(); foreach(var field in qAttNameType.GetFields()) qAttNamefields.Add(field.Name); foreach(var name in qAttNamefields) if(attribute == name) { attOk = true; break; } return attOk; }
// // Method to update a queue attribute
136
AWS SDK for .NET Developer GuideActualizar colas
private static async Task UpdateAttribute( IAmazonSQS sqsClient, string qUrl, string attribute, string value) { await sqsClient.SetQueueAttributesAsync(qUrl, new Dictionary<string, string>{{attribute, value}}); }
// // Command-line help private static void PrintHelp() { Console.WriteLine("\nUsage: SQSUpdateQueue -q queue_url [-a attribute -v value]"); Console.WriteLine(" -q: The URL of the queue you want to update."); Console.WriteLine(" -a: The name of the attribute to update."); Console.WriteLine(" -v, --value: The value to assign to the attribute."); } }
// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = // Class that represents a command line on the console or terminal. // (This is the same for all examples. When you have seen it once, you can ignore it.) static class CommandLine { // Method to parse a command line of the form: "--param value" or "-p value". // If "param" is found without a matching "value", Dictionary.Value is an empty string. // If "value" is found without a matching "param", Dictionary.Key is "--NoKeyN" // where "N" represents sequential numbers. public static Dictionary<string,string> Parse(string[] args) { var parsedArgs = new Dictionary<string,string>(); int i = 0, n = 0; while(i < args.Length) { // If the first argument in this iteration starts with a dash it's an option. if(args[i].StartsWith("-")) { var key = args[i++]; var value = string.Empty;
// Is there a value that goes with this option? if((i < args.Length) && (!args[i].StartsWith("-"))) value = args[i++]; parsedArgs.Add(key, value); }
// If the first argument in this iteration doesn't start with a dash, it's a value else { parsedArgs.Add("--NoKey" + n.ToString(), args[i++]); n++; } }
return parsedArgs; }
// // Method to get a parameter from the parsed command-line arguments public static string GetParameter( Dictionary<string,string> parsedArgs, string def, params string[] keys) { string retval = null; foreach(var key in keys) if(parsedArgs.TryGetValue(key, out retval)) break;
137
AWS SDK for .NET Developer GuideEliminación de colas
return retval ?? def; }
// // Exit with an error. public static void ErrorExit(string msg, int code=1) { Console.WriteLine("\nError"); Console.WriteLine(msg); Environment.Exit(code); } }
}
Consideraciones adicionales
• Para actualizar elRedrivePolicy, debe citar todo el valor y escapar de las comillas para los paresclave/valor, según corresponda para su sistema operativo.
En Windows, por ejemplo, el valor se construye de una manera similar a la siguiente:
"{\"deadLetterTargetArn\":\"DEAD_LETTER-QUEUE-ARN\",\"maxReceiveCount\":\"10\"}"
Eliminación de las colas de Amazon SQSEn este ejemplo puede ver cómo utilizar elAWS SDK for .NETPara eliminar una cola de Amazon SQS. Laaplicación elimina la cola, espera hasta un determinado período de tiempo para que la cola se vaya y, acontinuación, muestra una lista de las colas restantes.
Si no proporciona ningún argumento de línea de comandos, la aplicación simplemente muestra una lista delas colas existentes.
En las secciones siguientes, se incluyen fragmentos de este ejemplo. Lacódigo completo para elejemplo (p. 139)se muestra después de eso, y se puede construir y ejecutar tal como está.
Temas• Eliminación de la cola (p. 138)• Espere a que la cola se haya ido (p. 139)• Mostrar una lista de colas existentes (p. 139)• Completa código (p. 139)
Eliminación de la colaEl siguiente fragmento elimina la cola identificada por la URL de la cola dada.
El ejemploal final de este tema (p. 139)muestra este fragmento en uso.
// // Method to delete an SQS queue private static async Task DeleteQueue(IAmazonSQS sqsClient, string qUrl) { Console.WriteLine($"Deleting queue {qUrl}..."); await sqsClient.DeleteQueueAsync(qUrl); Console.WriteLine($"Queue {qUrl} has been deleted.");
138
AWS SDK for .NET Developer GuideEliminación de colas
}
Espere a que la cola se haya idoEl siguiente fragmento espera a que finalice el proceso de eliminación, lo que puede tardar 60 segundos.
El ejemploal final de este tema (p. 139)muestra este fragmento en uso.
// // Method to wait up to a given number of seconds private static async Task Wait( IAmazonSQS sqsClient, int numSeconds, string qUrl) { Console.WriteLine($"Waiting for up to {numSeconds} seconds."); Console.WriteLine("Press any key to stop waiting. (Response might be slightly delayed.)"); for(int i=0; i<numSeconds; i++) { Console.Write("."); Thread.Sleep(1000); if(Console.KeyAvailable) break;
// Check to see if the queue is gone yet var found = false; ListQueuesResponse responseList = await sqsClient.ListQueuesAsync(""); foreach(var url in responseList.QueueUrls) { if(url == qUrl) { found = true; break; } } if(!found) break; } }
Mostrar una lista de colas existentesEl siguiente fragmento muestra una lista de las colas existentes en la región del cliente SQS.
El ejemploal final de este tema (p. 139)muestra este fragmento en uso.
// // Method to show a list of the existing queues private static async Task ListQueues(IAmazonSQS sqsClient) { ListQueuesResponse responseList = await sqsClient.ListQueuesAsync(""); Console.WriteLine("\nList of queues:"); foreach(var qUrl in responseList.QueueUrls) Console.WriteLine($"- {qUrl}"); }
Completa códigoEn esta sección se muestran las referencias relevantes y el código completo de este ejemplo.
Referencia del SDK
Paquetes NuGet:
139
AWS SDK for .NET Developer GuideEliminación de colas
• AWSSDK.SQS
Elementos de programación:
• NamespaceAmazon.sqs
ClaseAmazonSQSClient• NamespaceAmazon.sqs.model
ClaseListQueuesResponse
El código
using System;using System.Threading;using System.Threading.Tasks;using Amazon.SQS;using Amazon.SQS.Model;
namespace SQSDeleteQueue{ // = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = // Class to update a queue class Program { private const int TimeToWait = 60;
static async Task Main(string[] args) { // Create the Amazon SQS client var sqsClient = new AmazonSQSClient();
// If no command-line arguments, just show a list of the queues if(args.Length == 0) { Console.WriteLine("\nUsage: SQSCreateQueue queue_url"); Console.WriteLine(" queue_url - The URL of the queue you want to delete."); Console.WriteLine("\nNo arguments specified."); Console.Write("Do you want to see a list of the existing queues? ((y) or n): "); var response = Console.ReadLine(); if((string.IsNullOrEmpty(response)) || (response.ToLower() == "y")) await ListQueues(sqsClient); return; }
// If given a queue URL, delete that queue if(args[0].StartsWith("https://sqs.")) { // Delete the queue await DeleteQueue(sqsClient, args[0]); // Wait for a little while because it takes a while for the queue to disappear await Wait(sqsClient, TimeToWait, args[0]); // Show a list of the remaining queues await ListQueues(sqsClient); } else { Console.WriteLine("The command-line argument isn't a queue URL:"); Console.WriteLine($"{args[0]}"); } }
140
AWS SDK for .NET Developer GuideEliminación de colas
// // Method to delete an SQS queue private static async Task DeleteQueue(IAmazonSQS sqsClient, string qUrl) { Console.WriteLine($"Deleting queue {qUrl}..."); await sqsClient.DeleteQueueAsync(qUrl); Console.WriteLine($"Queue {qUrl} has been deleted."); }
// // Method to wait up to a given number of seconds private static async Task Wait( IAmazonSQS sqsClient, int numSeconds, string qUrl) { Console.WriteLine($"Waiting for up to {numSeconds} seconds."); Console.WriteLine("Press any key to stop waiting. (Response might be slightly delayed.)"); for(int i=0; i<numSeconds; i++) { Console.Write("."); Thread.Sleep(1000); if(Console.KeyAvailable) break;
// Check to see if the queue is gone yet var found = false; ListQueuesResponse responseList = await sqsClient.ListQueuesAsync(""); foreach(var url in responseList.QueueUrls) { if(url == qUrl) { found = true; break; } } if(!found) break; } }
// // Method to show a list of the existing queues private static async Task ListQueues(IAmazonSQS sqsClient) { ListQueuesResponse responseList = await sqsClient.ListQueuesAsync(""); Console.WriteLine("\nList of queues:"); foreach(var qUrl in responseList.QueueUrls) Console.WriteLine($"- {qUrl}"); } }}
Consideraciones adicionales
• LaDeleteQueueAsyncLa llamada a la API no comprueba si la cola que está eliminando se estáutilizando como cola de cartas muertas. Un procedimiento más sofisticado podría verificar esto.
• También puede ver la lista de colas y los resultados de este ejemplo en elConsola de Amazon SQS.
141
AWS SDK for .NET Developer GuideEnvío de mensajes
Envío de mensajes de Amazon SQSEn este ejemplo puede ver cómo utilizar elAWS SDK for .NETPara enviar mensajes a una cola de AmazonSQS, que puede crearProgramáticamente (p. 127)o mediante el uso de la funciónConsola de AmazonSQS. La aplicación envía un solo mensaje a la cola y, a continuación, un lote de mensajes. A continuación,la aplicación espera la entrada del usuario, que puede ser mensajes adicionales para enviar a la cola o unasolicitud para salir de la aplicación.
Este ejemplo y elsiguiente ejemplo sobre la recepción de mensajes (p. 145)se pueden utilizarconjuntamente para ver el flujo de mensajes en Amazon SQS.
En las secciones siguientes, se incluyen fragmentos de este ejemplo. Lacódigo completo para elejemplo (p. 143)se muestra después de eso, y se puede construir y ejecutar tal como está.
Temas• Enviar un mensaje (p. 142)• Enviar un lote de mensajes (p. 142)• Eliminar todos los mensajes de la cola (p. 143)• Completa código (p. 143)
Enviar un mensajeEl siguiente fragmento envía un mensaje a la cola identificada por la URL de la cola dada.
El ejemploal final de este tema (p. 143)muestra este fragmento en uso.
// // Method to put a message on a queue // Could be expanded to include message attributes, etc., in a SendMessageRequest private static async Task SendMessage( IAmazonSQS sqsClient, string qUrl, string messageBody) { SendMessageResponse responseSendMsg = await sqsClient.SendMessageAsync(qUrl, messageBody); Console.WriteLine($"Message added to queue\n {qUrl}"); Console.WriteLine($"HttpStatusCode: {responseSendMsg.HttpStatusCode}"); }
Enviar un lote de mensajesEl siguiente fragmento envía un lote de mensajes a la cola identificada por la URL de la cola dada.
El ejemploal final de este tema (p. 143)muestra este fragmento en uso.
// // Method to put a batch of messages on a queue // Could be expanded to include message attributes, etc., // in the SendMessageBatchRequestEntry objects private static async Task SendMessageBatch( IAmazonSQS sqsClient, string qUrl, List<SendMessageBatchRequestEntry> messages) { Console.WriteLine($"\nSending a batch of messages to queue\n {qUrl}"); SendMessageBatchResponse responseSendBatch = await sqsClient.SendMessageBatchAsync(qUrl, messages); // Could test responseSendBatch.Failed here foreach(SendMessageBatchResultEntry entry in responseSendBatch.Successful) Console.WriteLine($"Message {entry.Id} successfully queued.");
142
AWS SDK for .NET Developer GuideEnvío de mensajes
}
Eliminar todos los mensajes de la colaEl siguiente fragmento elimina todos los mensajes de la cola identificados por la URL de la cola dada. Estoes lo que también se conoce comoDepuración de la cola.
El ejemploal final de este tema (p. 143)muestra este fragmento en uso.
// // Method to delete all messages from the queue private static async Task DeleteAllMessages(IAmazonSQS sqsClient, string qUrl) { Console.WriteLine($"\nPurging messages from queue\n {qUrl}..."); PurgeQueueResponse responsePurge = await sqsClient.PurgeQueueAsync(qUrl); Console.WriteLine($"HttpStatusCode: {responsePurge.HttpStatusCode}"); }
Completa códigoEn esta sección se muestran las referencias relevantes y el código completo de este ejemplo.
Referencia del SDK
Paquetes NuGet:
• AWSSDK.SQS
Elementos de programación:
• NamespaceAmazon.sqs
ClaseAmazonSQSClient• NamespaceAmazon.sqs.model
ClasePurgeQueuerResponse
ClasesendMessageBatchResponse
ClaseSendMessageResponse
ClasesendMessageBatchRequestEntry
ClaseSendMessageBatchResultEntry
El código
using System;using System.Collections.Generic;using System.Threading.Tasks;using Amazon.SQS;using Amazon.SQS.Model;
namespace SQSSendMessages{ // = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
143
AWS SDK for .NET Developer GuideEnvío de mensajes
// Class to send messages to a queue class Program { // Some example messages to send to the queue private const string JsonMessage = "{\"product\":[{\"name\":\"Product A\",\"price\": \"32\"},{\"name\": \"Product B\",\"price\": \"27\"}]}"; private const string XmlMessage = "<products><product name=\"Product A\" price=\"32\" /><product name=\"Product B\" price=\"27\" /></products>"; private const string CustomMessage = "||product|Product A|32||product|Product B|27||"; private const string TextMessage = "Just a plain text message.";
static async Task Main(string[] args) { // Do some checks on the command-line if(args.Length == 0) { Console.WriteLine("\nUsage: SQSSendMessages queue_url"); Console.WriteLine(" queue_url - The URL of an existing SQS queue."); return; } if(!args[0].StartsWith("https://sqs.")) { Console.WriteLine("\nThe command-line argument isn't a queue URL:"); Console.WriteLine($"{args[0]}"); return; }
// Create the Amazon SQS client var sqsClient = new AmazonSQSClient();
// (could verify that the queue exists) // Send some example messages to the given queue // A single message await SendMessage(sqsClient, args[0], JsonMessage);
// A batch of messages var batchMessages = new List<SendMessageBatchRequestEntry>{ new SendMessageBatchRequestEntry("xmlMsg", XmlMessage), new SendMessageBatchRequestEntry("customeMsg", CustomMessage), new SendMessageBatchRequestEntry("textMsg", TextMessage)}; await SendMessageBatch(sqsClient, args[0], batchMessages);
// Let the user send their own messages or quit await InteractWithUser(sqsClient, args[0]);
// Delete all messages that are still in the queue await DeleteAllMessages(sqsClient, args[0]); }
// // Method to put a message on a queue // Could be expanded to include message attributes, etc., in a SendMessageRequest private static async Task SendMessage( IAmazonSQS sqsClient, string qUrl, string messageBody) { SendMessageResponse responseSendMsg = await sqsClient.SendMessageAsync(qUrl, messageBody); Console.WriteLine($"Message added to queue\n {qUrl}"); Console.WriteLine($"HttpStatusCode: {responseSendMsg.HttpStatusCode}"); }
// // Method to put a batch of messages on a queue // Could be expanded to include message attributes, etc.,
144
AWS SDK for .NET Developer GuideRecepción de mensajes
// in the SendMessageBatchRequestEntry objects private static async Task SendMessageBatch( IAmazonSQS sqsClient, string qUrl, List<SendMessageBatchRequestEntry> messages) { Console.WriteLine($"\nSending a batch of messages to queue\n {qUrl}"); SendMessageBatchResponse responseSendBatch = await sqsClient.SendMessageBatchAsync(qUrl, messages); // Could test responseSendBatch.Failed here foreach(SendMessageBatchResultEntry entry in responseSendBatch.Successful) Console.WriteLine($"Message {entry.Id} successfully queued."); }
// // Method to get input from the user // They can provide messages to put in the queue or exit the application private static async Task InteractWithUser(IAmazonSQS sqsClient, string qUrl) { string response; while (true) { // Get the user's input Console.WriteLine("\nType a message for the queue or \"exit\" to quit:"); response = Console.ReadLine(); if(response.ToLower() == "exit") break;
// Put the user's message in the queue await SendMessage(sqsClient, qUrl, response); } }
// // Method to delete all messages from the queue private static async Task DeleteAllMessages(IAmazonSQS sqsClient, string qUrl) { Console.WriteLine($"\nPurging messages from queue\n {qUrl}..."); PurgeQueueResponse responsePurge = await sqsClient.PurgeQueueAsync(qUrl); Console.WriteLine($"HttpStatusCode: {responsePurge.HttpStatusCode}"); } }}
Consideraciones adicionales
• Para obtener información acerca de las diversas limitaciones de los mensajes, incluidos los caracterespermitidos, consulteCuotas relacionadas con los mensajesen laAmazon Simple Queue Service.
• Los mensajes permanecen en las colas hasta que se eliminan o se purga la cola. Cuando una aplicaciónha recibido un mensaje, no será visible en la cola aunque todavía exista en la cola. Para obtener másinformación acerca de los tiempos de espera de visibilidad, consulteTiempo de espera de visibilidad deAmazon SQS.
• Además del cuerpo del mensaje, también puede agregar atributos a los mensajes. Para obtener másinformación, consulteMetadatos de mensajes.
Recepción de mensajes de Amazon SQSEn este ejemplo puede ver cómo utilizar elAWS SDK for .NETPara recibir mensajes de una cola deAmazon SQS, que puede crearProgramáticamente (p. 127)o mediante el uso de la funciónConsola de
145
AWS SDK for .NET Developer GuideRecepción de mensajes
Amazon SQS. La aplicación lee un solo mensaje de la cola, procesa el mensaje (en este caso, muestrael cuerpo del mensaje en la consola) y, a continuación, elimina el mensaje de la cola. La aplicación repiteestos pasos hasta que el usuario escribe una tecla en el teclado.
Este ejemplo y elejemplo anterior sobre el envío de mensajes (p. 142)se pueden utilizar conjuntamentepara ver el flujo de mensajes en Amazon SQS.
En las secciones siguientes, se incluyen fragmentos de este ejemplo. Lacódigo completo para elejemplo (p. 146)se muestra después de eso, y se puede construir y ejecutar tal como está.
Temas• Recibir un mensaje (p. 146)• Eliminación de un mensaje (p. 146)• Completa código (p. 146)
Recibir un mensajeEl siguiente fragmento recibe un mensaje de la cola identificada por la URL de la cola dada.
El ejemploal final de este tema (p. 146)muestra este fragmento en uso.
// // Method to read a message from the given queue // In this example, it gets one message at a time private static async Task<ReceiveMessageResponse> GetMessage( IAmazonSQS sqsClient, string qUrl, int waitTime=0) { return await sqsClient.ReceiveMessageAsync(new ReceiveMessageRequest{ QueueUrl=qUrl, MaxNumberOfMessages=MaxMessages, WaitTimeSeconds=waitTime // (Could also request attributes, set visibility timeout, etc.) }); }
Eliminación de un mensajeEl siguiente fragmento elimina un mensaje de la cola identificada por la URL de la cola dada.
El ejemploal final de este tema (p. 146)muestra este fragmento en uso.
// // Method to delete a message from a queue private static async Task DeleteMessage( IAmazonSQS sqsClient, Message message, string qUrl) { Console.WriteLine($"\nDeleting message {message.MessageId} from queue..."); await sqsClient.DeleteMessageAsync(qUrl, message.ReceiptHandle); }
Completa códigoEn esta sección puede ver las referencias relevantes y el código completo de este ejemplo.
Referencia del SDK
Paquetes NuGet:
• AWSSDK.SQS
146
AWS SDK for .NET Developer GuideRecepción de mensajes
Elementos de programación:
• NamespaceAmazon.sqs
ClaseAmazonSQSClient• NamespaceAmazon.sqs.model
ClaseReceiveMessageRequest
ClaseReceiveMessageResponse
El código
using System;using System.Threading.Tasks;using Amazon.SQS;using Amazon.SQS.Model;
namespace SQSReceiveMessages{ class Program { private const int MaxMessages = 1; private const int WaitTime = 2; static async Task Main(string[] args) { // Do some checks on the command-line if(args.Length == 0) { Console.WriteLine("\nUsage: SQSReceiveMessages queue_url"); Console.WriteLine(" queue_url - The URL of an existing SQS queue."); return; } if(!args[0].StartsWith("https://sqs.")) { Console.WriteLine("\nThe command-line argument isn't a queue URL:"); Console.WriteLine($"{args[0]}"); return; }
// Create the Amazon SQS client var sqsClient = new AmazonSQSClient();
// (could verify that the queue exists) // Read messages from the queue and perform appropriate actions Console.WriteLine($"Reading messages from queue\n {args[0]}"); Console.WriteLine("Press any key to stop. (Response might be slightly delayed.)"); do { var msg = await GetMessage(sqsClient, args[0], WaitTime); if(msg.Messages.Count != 0) { if(ProcessMessage(msg.Messages[0])) await DeleteMessage(sqsClient, msg.Messages[0], args[0]); } } while(!Console.KeyAvailable); }
// // Method to read a message from the given queue // In this example, it gets one message at a time private static async Task<ReceiveMessageResponse> GetMessage(
147
AWS SDK for .NET Developer GuideAWS OpsWorks
IAmazonSQS sqsClient, string qUrl, int waitTime=0) { return await sqsClient.ReceiveMessageAsync(new ReceiveMessageRequest{ QueueUrl=qUrl, MaxNumberOfMessages=MaxMessages, WaitTimeSeconds=waitTime // (Could also request attributes, set visibility timeout, etc.) }); }
// // Method to process a message // In this example, it simply prints the message private static bool ProcessMessage(Message message) { Console.WriteLine($"\nMessage body of {message.MessageId}:"); Console.WriteLine($"{message.Body}"); return true; }
// // Method to delete a message from a queue private static async Task DeleteMessage( IAmazonSQS sqsClient, Message message, string qUrl) { Console.WriteLine($"\nDeleting message {message.MessageId} from queue..."); await sqsClient.DeleteMessageAsync(qUrl, message.ReceiptHandle); } }}
Consideraciones adicionales
• Para especificar sondeo largo, en este ejemplo se utiliza el métodoWaitTimeSecondspara cadallamada a la propiedadReceiveMessageAsyncMétodo de.
También puede especificar un sondeo largo para todos los mensajes de unacola mediante el comandoReceiveMessageWaitTimeSecondsatributocuandocreating (p. 127)oractualizar (p. 133)La cola de.
Para obtener información acerca del sondeo corto y el sondeo largo, consulteSondeos cortos y largosenlaAmazon Simple Queue Service.
• Durante el procesamiento de mensaje, puede usar el identificador de recepción para cambiar el tiempode espera de visibilidad del mensaje. Para obtener información acerca de cómo hacerlo, consultelaChangeMessageVisibilityAsyncMétodos de laAmazonSQSClientClase de.
• Llamada alDeleteMessageAsyncEl método elimina sin condiciones el mensaje de la cola, sin importarla configuración del tiempo de espera de visibilidad.
ProgramaciónAWS OpsWorksPara Trabajar conpilas y aplicaciones
El AWS SDK for .NET es compatible con AWS OpsWorks, que ofrece una forma sencilla y flexible decrear y administrar pilas y aplicaciones. conAWS OpsWorks, puede aprovisionarAWSrecursos, administrar
148
AWS SDK for .NET Developer GuideAPIs
su configuración, implementar aplicaciones en dichos recursos y monitorear su salud. Para obtener másinformación, consulte laPágina del producto OpsWorksy laAWS OpsWorksGuía del usuario de.
APIsLaAWS SDK for .NETproporciona API paraAWS OpsWorks. Las API le permiten trabajar conAWSOpsWorksCaracterísticas dePilas decon suCapas de,Instancias de, yAplicaciones. Para ver elconjunto completo de API, consulte laAWS SDK for .NETReferencia de la API(y desplácese hasta«Amazon.opsWorks»).
LaAWS OpsWorkslas API son proporcionadas por elawssdk.opsWorksPaquete de NuGet.
PrerequisitesAntes de comenzar, asegúrese de tenerPara configurar el entorno (p. 15). Revise también la informacióndeConfiguración del proyecto (p. 17)yCaracterísticas del SDK (p. 36).
OtrosAWSServicios y configuraciónLaAWS SDK for .NETes compatible conAWSAdemás de los que se describen en las secciones anteriores.Para obtener información acerca de las API de de todos los servicios admitidos, consulteAWS SDKfor .NETReferencia de la API.
Además de los espacios de nombres paraAWSLos servicios deAWS SDK for .NETEl proporciona ademáslas siguientes API:
Area Descripción Recursos
Compatibilidad con AWS Acceso programáticoaAWSCasos de Support ycaracterísticas de TrustedAdvisor.
Consulte Amazon.AWSSupport yAmazon.AWSSupport.Model.
Generales Clases auxiliares yenumeraciones.
Consulte Amazon y Amazon.Util.
149
AWS SDK for .NET Developer GuideHerramienta de implementación
Herramientas adicionales para usarcon elAWS SDK for .NET
En esta sección se proporciona información acerca de las herramientas adicionales disponibles junto conelAWS SDK for .NET. Utilice estas herramientas para ayudar con el desarrollo, la implementación y elmantenimiento de sus aplicaciones.
Utilice estas herramientas junto conConfiguración del entorno (p. 15),Configuración del proyecto (p. 17)ycrear aplicaciones para trabajar conAWS, ejemplos de los cuales se dan enUso deAWSServiciosde (p. 55).
Las siguientes herramientas están disponibles:• AWSHerramienta de implementación de.NET para la CLI de.NET (p. 150)
AWSHerramienta de implementación de.NET parala CLI de.NET
Esta es una documentación preliminar para una característica en versión de vista previa. Está sujeta acambios.
Después de desarrollar su aplicación de.NET Core nativa de la nube en una máquina de desarrollo, lo másprobable es que desee implementarla enAWS.
Implementación enAWSa veces implica múltiplesAWSservicios y recursos, cada uno de los cuales debeestar configurado. Para facilitar este trabajo de implementación, puede usar la herramientaAWS.NET parala CLI de.NET, oHerramienta de implementaciónPara abreviar.
Cuando ejecuta la herramienta de implementación para una aplicación de.NET Core, la herramientamuestra todos losAWSque están disponibles para implementar la aplicación. Sugiere la opción másprobable, así como la configuración más probable para ir junto con esa elección. A continuación, construyey empaqueta su aplicación según lo requiera el servicio de computación elegido. Genera la infraestructurade implementación, implementa la aplicación mediante elAWS Cloud Development Kit (CDK)y, acontinuación, muestra el extremo.
Información adicional sobre la herramienta de implementación está disponible en el repositorio de GitHubenhttps://github.com/aws/aws-dotnet-deployy en la publicación del blogReimaginando elAWSExperienciade implementación .NET.
Capabilities
• Se implementa enAWS Elastic Beanstalko Amazon ECS (utilizandoAWS Fargate).• Implementa aplicaciones de.NET nativas de la nube que se crean con .NET Core 2.1 y versiones
posteriores y que se escriben con la intención de implementar en Linux. Dicha aplicación no estávinculada a ninguna tecnología específica de Windows, como el Registro de Windows, IIS o MSMQ, y sepuede implementar en procesos virtualizados.
150
AWS SDK for .NET Developer GuideConfiguración del entorno
• Implementa aplicaciones web ASP.NET Core, aplicaciones Blazor WebAssembly, aplicaciones deservicio de larga duración y tareas programadas. Para obtener más información, consulte laLÉAMEen elrepositorio de GitHub.
Temas• Configuración del entorno (p. 151)• Configuración de la herramienta de implementación (p. 152)• Configuración de credenciales para la herramienta de implementación (p. 152)• Ejecución de la herramienta de implementación (p. 153)• Tutoriales para implementar la aplicación (p. 154)• Volver a desplegar la aplicación después de los cambios (p. 158)• Configuración de implementación disponible a través de la herramienta de implementación (p. 159)
Configuración del entorno
Esta es una documentación preliminar para una característica en versión de vista previa. Está sujeta acambios.
En las secciones siguientes se muestra cómo configurar el entorno para ejecutar la herramienta deimplementación.
Node.jsLa herramienta de implementación requiereAWS CDK, y elAWS CDKrequiereNode.js, versión 10.13.0o posterior (excluyendo las versiones 13.0.0 a 13.6.0). Para ver la versión de Node.js que ha instalado,ejecute el siguiente comando en el símbolo del sistema o en una terminal:
node --version
Note
Si el archivo deAWS CDKno está instalado en su equipo o si elAWS CDKque está instalado esanterior a la versión mínima requerida (1.95.2), la herramienta de implementación instalará unacopia temporal y «privada» del CDK que solo será utilizada por la herramienta, dejando intacta laconfiguración global de su equipo.
.NET Core y .NETLa aplicación debe crearse a partir de .NET Core 3.1 o posterior (por ejemplo, .NET Core 3.1, .NET 5.0,etc.). Para ver qué versión tiene, ejecute lo siguiente en el símbolo del sistema o en una terminal:
dotnet --version
Para obtener información acerca de cómo instalar o actualizar .NET, consultehttps://dotnet.microsoft.com/.
(Opcional) DockerSi tiene previsto implementar su aplicación en Amazon Elastic Container Service (Amazon ECS)medianteAWS Fargate, debe tener instalado Docker donde ejecute la herramienta de implementación.Para obtener más información, consultehttps://docs.docker.com/engine/install/.
151
AWS SDK for .NET Developer GuideConfiguración de la herramienta
CLI ZIP (Linux y macOS)La CLI ZIP se utiliza al crear paquetes ZIP para paquetes de implementación. Se utiliza para mantenerpermisos de archivos Linux.
Configuración de la herramienta de implementación
Esta es una documentación preliminar para una característica en versión de vista previa. Está sujeta acambios.
Las siguientes instrucciones le muestran cómo instalar, actualizar y desinstalar la herramienta deimplementación.
Para instalar la herramienta de implementación
1. Abra un símbolo del sistema o terminal.2. Instale la herramienta:dotnet tool install --global aws.deploy.cli3. Verifique la instalación comprobando la versión:dotnet aws --version
Para actualizar la herramienta de implementación
1. Abra un símbolo del sistema o terminal.2. Compruebe la versión:dotnet aws --version3. (Opcional) Compruebe si hay una versión posterior de la herramienta disponible en la pestañaPágina
NuGet para la herramienta de implementación.4. Actualizar la herramienta:dotnet tool update -g aws.deploy.cli5. Verifique la instalación comprobando de nuevo la versión:dotnet aws --version
Para quitar la herramienta de implementación del sistema
1. Abra un símbolo del sistema o terminal.2. Desinstalar la herramienta:dotnet tool uninstall -g aws.deploy.cli3. Compruebe que la herramienta ya no está instalada:dotnet aws --version
Configuración de credenciales para la herramienta deimplementación
Esta es una documentación preliminar para una característica en versión de vista previa. Está sujeta acambios.
Esta información es acerca de cómo configurar las credenciales para la herramienta de implementación.Si está buscando información acerca de cómo configurar las credenciales de su proyecto,consulteConfiguraciónAWScredenciales (p. 20)En su lugar,
Para ejecutar la herramienta de implementación en suAWS, debe tener un perfil de credenciales. El perfildebe configurarse con al menos un ID de clave de acceso y una clave de acceso secreta para unAWS
152
AWS SDK for .NET Developer GuideEjecución de la herramienta
Identity and Access Management(IAM). Para obtener información acerca de cómo hacerlo, consulteCrearusuarios y roles (p. 18)yUso delAWSarchivo de credenciales (p. 21).
Las credenciales que utilice para ejecutar la herramienta de implementación deben tener permisos paradeterminados servicios, en función de las tareas que intente realizar. Los siguientes son algunos ejemplosde los permisos típicos que se requieren para ejecutar la herramienta. Es posible que se requieranpermisos adicionales, en función del tipo de aplicación que esté implementando y de los servicios queutilice.
Tarea Permisos de servicios
Mostrar una lista deAWS CloudFormationpilas(implementaciones de listas)
CloudFormation
Implementar y volver a implementar en ElasticBeanstalk (implementar)
CloudFormation, Elastic Beanstalk
Implementar y volver a implementar en AmazonECS (implementar)
CloudFormation, Elastic Beanstalk, ElasticContainer Registry
La herramienta de implementación utiliza automáticamente el[default]perfil desuCompartidoAWSarchivos de configuración y credenciales (p. 21)si ese perfil existe. Puede cambiar estecomportamiento especificando un perfil para la herramienta que se va a utilizar, ya sea en todo el sistemao en un contexto determinado.
Para especificar un perfil de todo el sistema, haga lo siguiente:
• Especifique laAWS_PROFILEEn todo el mundo, según sea apropiado para su sistema operativo.Asegúrese de volver a abrir las indicaciones de comando o terminales según sea necesario. Si el perfilque especifique no incluye unAWSRegión, es posible que la herramienta le pida que elija una.
Warning
Si establece la propiedadAWS_PROFILEglobalmente para su sistema, otros SDK, CLI yherramientas también utilizarán ese perfil. Si este comportamiento es inaceptable, especifiqueun perfil para un contexto determinado.
Para especificar un perfil para un contexto determinado, realice alguna de las siguientes operaciones:
• Especifique laAWS_PROFILEen el símbolo del sistema o la sesión de terminal desde la que estáejecutando la herramienta (según corresponda para su sistema operativo).
• Especifique la--profiley--regiondentro del comando. Por ejemplo: dotnet aws list-stacks--region us-west-2. Para obtener información adicional acerca de los comandos de la herramientade implementación, consulteEjecución de la herramienta de implementación (p. 153).
• No especifique nada y la herramienta le pedirá que elija un perfil y unAWSRegión .
Ejecución de la herramienta de implementación
Esta es una documentación preliminar para una característica en versión de vista previa. Está sujeta acambios.
Para ayudarle a familiarizarse con la herramienta de implementación, este tema contiene un recorridorápido por la línea de comandos de la herramienta.
153
AWS SDK for .NET Developer GuideImplementación: Tutoriales
Ayuda de la línea de comandosPara obtener ayuda básica, ejecute lo siguiente:
dotnet aws --help
Los comandos disponibles se enumeran en el cuadroComandosdel texto de ayuda; porejemplo,deployylist-deployments.
Para obtener ayuda sobre un comando específico, utilice--helpen el contexto de esa orden. Por ejemplo:
dotnet aws deploy --help
Secuencias más comunes de comandosPara implementar o volver a implementar una aplicación:
cd <dotnet_core_app_directory>dotnet aws deploy [--profile <profile_name>] [--region <region_code>]
Para mostrar una lista de las pilas de CloudFormation que ha creado mediante la herramienta:
dotnet aws list-deployments [—region <region_code>] [--profile <profile_name>]
Tutoriales para implementar la aplicación
Esta es una documentación preliminar para una característica en versión de vista previa. Está sujeta acambios.
Después de desarrollar la aplicación, la implementa enAWS. Cuando utiliza la herramienta deimplementación, la herramienta muestra todos losAWSque están disponibles para implementar laaplicación. A continuación, sugiere la opción más probable, así como la configuración más probable para irjunto con esa elección.
En las secciones siguientes se muestran algunos ejemplos de implementaciones enAWS. Los ejemplosutilizan aplicaciones rudimentarias, el[default]y la configuración predeterminada que proporciona laherramienta de implementación.
Tutoriales• Implementación de una aplicación web en Elastic Beanstalk (p. 154)• Implementar una aplicación web en Amazon ECS (p. 156)
Implementación de una aplicación web en Elastic Beanstalk
Esta es una documentación preliminar para una característica en versión de vista previa. Está sujeta acambios.
En este tutorial se muestra una implementación en Elastic Beanstalk. El aprendizaje utiliza los valorespredeterminados proporcionados por la herramienta de despliegue.
154
AWS SDK for .NET Developer GuideImplementación: Tutoriales
Prerequisites
• Ha completadoConfiguración del entorno de (p. 151)yConfiguración de la herramienta (p. 152).• La[default]El perfil de credenciales cuenta con los permisos necesarios.
Deploy
Cuando esté listo para implementar la aplicación enAWSPor primera vez que empieza aquí.
Para implementar la aplicación web de ejemplo en Elastic Beanstalk
1. Vaya a un directorio donde desee trabajar y cree la aplicación web básica:
dotnet new webapp --name SimpleWebAppForBeanstalk
2. Vaya al directorio de la aplicación:
cd SimpleWebAppForBeanstalk
3. Para ejecutar la herramienta de implementación:
dotnet aws deploy
4. EnNombra el nombreAWSPara implementar la aplicación en, pulse laEscribaPara aceptar elnombre predeterminado. Si hay pilas existentes, esto muestraSeleccione laAWSPara implementarla aplicación enEn su lugar, En este caso, elija la última opción paraCrear nuevosy, a continuación,presione laEscribaPara aceptar el nombre predeterminado.
5. Para la próxima investigación,Elija la opción de implementación, elija la opción paraAWS ElasticBeanstalken Linuxy pulse la teclaEscribaClave. En este tutorial, esta es la opción predeterminada.
Note
Al implementar una aplicación real, si la herramienta no encuentra un Dockerfile para elproyecto, la herramienta de implementación muestraAWS Elastic Beanstalken LinuxComoopción predeterminada. Si hay un archivo Dockerfile para el proyecto, la herramienta muestraun valor predeterminado diferente. Para obtener más información acerca de esta situaciónalternativa, consulteImplementar una aplicación web en Amazon ECS (p. 156).
6. Pulse la.Escribapara aceptar los valores predeterminados para la configuración de la aplicación y lapila e iniciar la implementación.
7. Espere a que termine el proceso de implementación.8. Al final de la salida de la herramienta, verá la siguiente línea:
«SimpleWebAppForBeanstalk.EndPointURL...». Esta línea contiene la dirección URL del sitio webresultante. Puede abrir esta URL en un navegador web. También puede abrir el sitio web resultantedesde la consola de Elastic Beanstalk, como se muestra a continuación.
9. Inicie sesión enAWS Management ConsoleY abra la consola de Elastic Beanstalk enhttps://console.aws.amazon.com/elasticbeanstalk/.
Seleccione la opción adecuadaAWSRegión, si fuera necesario.10. En la páginaEntornos, elija laSimpleWebAppForBeanstalk-devMedio ambiente.11. En la sección superior de la página del entorno, compruebe que elEstadoEl estado de esAceptary, a
continuación, abra el vínculo para ver el sitio web resultante. Deje este sitio web abierto por ahora.
Actualización y reimplementación
Ahora que ha implementado una aplicación y puede ver el sitio web resultante, es hora de realizar algunoscambios en el contenido y volver a desplegar la aplicación.
155
AWS SDK for .NET Developer GuideImplementación: Tutoriales
Para realizar cambios en el contenido web y volver a desplegar la aplicación
1. En el navegadorPagessubdirectorio del proyecto tutorial, abraIndex.cshtmlen un editor de texto.2. Realice algunos cambios en el contenido HTML y guarde el archivo.3. En el directorio principal del proyecto, vuelva a ejecutar la herramienta de implementación:
dotnet aws deploy
4. EnSeleccione laAWSPara implementar la aplicación en, elija el nombre de pila que corresponde a estetutorial y pulse el botónEscribaClave. Para este tutorial, este modelo esSimpleWebAppForBeanStalk, yes la opción predeterminada.
5. Pulse la.Escribade nuevo para aceptar los mismos valores predeterminados que antes y esperar a quela aplicación se vuelva a implementar.
6. En el navegadorConsola de Elastic Beanstalk, mire laSimpleWebAppForBeanstalk-devde nuevoentorno. Compruebe que laEstadoEl estado de esAceptary, a continuación, actualice el sitio web de laaplicación para ver los cambios.
Cleanup
Para evitar costes inesperados, asegúrese de eliminar el entorno y la aplicación del tutorial cuando hayaterminado con ellos.
También puede realizar esta limpieza manualmente a través de la consola de Elastic Beanstalk enhttps://console.aws.amazon.com/elasticbeanstalk.
Para eliminar artefactos de aprendizaje
1. Obtenga una lista de aplicaciones en la nube existentes:
dotnet aws list-deployments.
La lista incluye la implementación de este tutorial: SimpleWebAppForBeanStalk.2. Elimine la implementación:
dotnet aws delete-deployment SimpleWebAppForBeanstalk
3. Escriba «y» para confirmar la eliminación y espere a que se elimine la implementación.4. En el navegadorConsola de Elastic Beanstalk, mire laEntornosyAplicacionespara comprobar que se ha
eliminado la implementación del tutorial.5. Actualice el sitio web que se creó durante el aprendizaje para comprobar que ya no está disponible.
Implementar una aplicación web en Amazon ECS
Esta es una documentación preliminar para una característica en versión de vista previa. Está sujeta acambios.
En este tutorial se muestra una implementación en Amazon ECS medianteAWS Fargate. El aprendizajeutiliza los valores predeterminados proporcionados por la herramienta de despliegue.
Prerequisites
• Ha completadoConfiguración del entorno de (p. 151)yConfiguración de la herramienta (p. 152).• La[default]El perfil de credenciales cuenta con los permisos necesarios.
156
AWS SDK for .NET Developer GuideImplementación: Tutoriales
• Docker está instalado y en ejecución, pero no existe Dockerfile para el tutorial.
Deploy
Cuando esté listo para implementar la aplicación enAWSPor primera vez que empieza aquí.
Para implementar la aplicación web de ejemplo en Amazon ECS medianteAWS Fargate
1. Vaya a un directorio donde desee trabajar y cree la aplicación web básica:
dotnet new webapp --name SimpleWebAppForECS
2. Vaya al directorio de la aplicación:
cd SimpleWebAppForECS
3. Para ejecutar la herramienta de implementación:
dotnet aws deploy
4. EnNombra el nombreAWSPara implementar la aplicación en, pulse laEscribaPara aceptar elnombre predeterminado. Si hay pilas existentes, esto muestraSeleccione laAWSPara implementarla aplicación enEn su lugar, En este caso, elija la última opción paraCrear nuevosy, a continuación,presione laEscribaPara aceptar el nombre predeterminado.
5. Para la próxima investigación,Elija la opción de implementación, elija la opción paraAmazonECS utilizando Fargatey pulse la teclaEscribaClave. Para este tutorial, esta es la segunda opción(enOpciones de implementación adicionales), no el valor predeterminado.
Note
Al implementar una aplicación real, si la herramienta de implementación encuentraun Dockerfile para el proyecto, muestraAmazon ECS utilizando FargateComo opciónpredeterminada. Si no hay Dockerfile para el proyecto, pero elige la opciónAmazon ECSutilizando Fargate, la herramienta genera un archivo Dockerfile.
6. Pulse la.Escribapara aceptar los valores predeterminados para la configuración de la aplicación y lapila e iniciar la implementación. Para este tutorial, ya que no se encontró ningún archivo Dockerfilepara el proyecto, sino elAmazon ECS utilizando Fargate, la herramienta también genera un archivoDockerfile.
7. Espere a que termine el proceso de implementación.8. Al final de la salida de la herramienta, verá la siguiente línea:
«SimpleWebAppForecs.fargatesServiceServiceURL...». Esta línea contiene la dirección URL del sitioweb resultante. Abra la URL en un navegador web para ver el sitio web resultante. Deje este sitio webabierto por ahora.
9. Si desea ver los recursos creados por la herramienta, abra la consola de Amazon ECS enhttps://console.aws.amazon.com/ecs/. Seleccione la opción adecuadaAWSRegión, si fuera necesario. En lapáginaClústerespuede ver el nuevo clúster que se creó: SimpleWebAppForecs.
Actualización y reimplementación
Ahora que ha implementado una aplicación y puede ver el sitio web resultante, es hora de realizar algunoscambios en el contenido y volver a desplegar la aplicación.
Para realizar cambios en el contenido web y volver a desplegar la aplicación
1. En el navegadorPagessubdirectorio del proyecto tutorial, abraIndex.cshtmlen un editor de texto.2. Realice algunos cambios en el contenido HTML y guarde el archivo.3. En el directorio principal del proyecto, vuelva a ejecutar la herramienta de implementación:
157
AWS SDK for .NET Developer GuideVolver a implementar
dotnet aws deploy
4. EnSeleccione laAWSPara implementar la aplicación en, elija el nombre de pila que corresponde a estetutorial y pulse el botónEscribaClave. Para este tutorial, este modelo esSimpleWebAppForecs, y es laopción predeterminada.
5. Pulse la.Escribade nuevo para aceptar los mismos valores predeterminados que antes y esperar a quela aplicación se vuelva a implementar.
6. Actualice el sitio web de la aplicación para ver los cambios.
CleanupPara evitar costes inesperados, asegúrese de quitar los clústeres, las tareas y los repositorios ECR deltutorial cuando haya terminado con ellos.
También puede realizar esta limpieza manualmente a través de la consola de Amazon ECS enhttps://console.aws.amazon.com/ecs/.
Para eliminar artefactos de aprendizaje
1. Obtenga una lista de aplicaciones en la nube existentes:
dotnet aws list-deployments
La lista incluye la implementación de este tutorial: SimpleWebAppForecs.2. Elimine la implementación:
dotnet aws delete-deployment SimpleWebAppForECS
3. Escriba «y» para confirmar la eliminación y espere a que se elimine la implementación.4. En el navegadorConsola de Amazon ECS, mire laClústeresyDefiniciones de tareas depara comprobar
que se ha eliminado la implementación del tutorial.5. (Opcional) En elAmazon ECR,Repositorios de, puede eliminar el repositorio que se creó para el
tutorial:simplewebappforecs6. Actualice el sitio web que se creó durante el aprendizaje para comprobar que ya no está disponible.
Volver a desplegar la aplicación después de loscambios
Esta es una documentación preliminar para una característica en versión de vista previa. Está sujeta acambios.
Si realiza cambios en la aplicación, puede utilizar la herramienta de implementación para volver aimplementarla. Para ello, vaya al directorio del proyecto de la aplicación y ejecutedotnet aws deploydenuevo.
En un momento determinado del redespliegue, la herramienta muestraSeleccione laAWSPara implementarla aplicación en. Analice la lista de pilas de implementación y realice alguna de las siguientes operaciones:
• Elija el nombre de pila que corresponde a su aplicación .NET.
Si lo hace, se muestran los ajustes de la última implementación de la aplicación. Sólo se pueden cambiaralgunas de las configuraciones avanzadas, el resto son de sólo lectura.
• Elija la última opción,Crear nuevosy, a continuación, escriba un nuevo nombre.
158
AWS SDK for .NET Developer GuideConfiguración de implementación
Si lo hace, la herramienta creará una nueva pila de implementación y podrá decidir qué desea hacer conla configuración: aceptar los valores predeterminados o realizar cambios.
Configuración de implementación disponible a travésde la herramienta de implementación
Esta es una documentación preliminar para una característica en versión de vista previa. Está sujeta acambios.
Uno de los pasos durante la implementación o la reimplementación es elegir el servicio informático quedesea utilizar, que suele ser la sugerencia predeterminada de la herramienta de implementación. Unavez que haya elegido la opción de implementación que desee, la herramienta le mostrará una lista de losparámetros comunes que están disponibles para esa opción. La configuración avanzada también estádisponible, que puede ver introduciendo»more«en el símbolo del sistema.
Muchas de las opciones de configuración son autoexplicativas. Las siguientes configuraciones son menosobvias.
Implementación en AWS Elastic Beanstalk
• Rol de IAM de aplicación
LaRol de IAM de aplicaciónproporcionaAWSpara su aplicación, que se ha implementado enAWSen sunombre. Con un rol de IAM, la aplicación puede acceder aAWSRecursos como Buckets de Amazon S3.
Con esta configuración, puede elegir entre los roles de IAM existentes o permitir que la herramientacree un rol específicamente para su aplicación, que es el comportamiento predeterminado.Puede ver las definiciones de los roles de IAM existentes abriendo la consola de IAM enhttps://console.aws.amazon.com/iam/y eligiendo elRoles de(Se ha creado el certificado).
• Tipo de instancia EC2
Mediante esta configuración, puede especificar un tipo de instancia de Amazon EC2 distinto del quesugiere la herramienta. Para encontrar los tipos de instancias disponibles, abra la consola de AmazonEC2 enhttps://console.aws.amazon.com/ec2/y eligiendo elTipos de instancia depágina bajoInstancias.Para obtener descripciones detalladas de los tipos de instancias EC2, consultehttps://aws.amazon.com/ec2/instance-types/.
• Par de claves
El valor predeterminado para esta configuración es «VACY» (sin key pair), lo que significa que nopodrá SSH en la instancia EC2. Si desea SSH en la instancia de EC2, puede elegir un key pair dela lista. Puede ver los pares de claves en la lista abriendo elConsola de EC2y eligiendo elPares declavespágina bajoRed y seguridad. También puede hacer que la herramienta cree un nuevo key pair. Sielige esta opción, introduzca un nombre para el key pair y (cuando se le solicite) un directorio donde sealmacenará la clave privada.
Warning
Si eligió crear un nuevo key pair y almacenarlo en el equipo, tome las precauciones apropiadaspara proteger el key pair.
Implementar en Amazon ECS mediante AWS Fargate
• Rol de IAM de aplicación
159
AWS SDK for .NET Developer GuideConfiguración de implementación
LaRol de IAM de aplicaciónproporcionaAWSpara su aplicación, que se ha implementado enAWSen sunombre. Con un rol de IAM, la aplicación puede acceder aAWSRecursos como Buckets de Amazon S3.
Con esta configuración, puede elegir entre los roles de IAM existentes o permitir que la herramientacree un rol específicamente para su aplicación, que es el comportamiento predeterminado.Puede ver las definiciones de los roles de IAM existentes abriendo la consola de IAM enhttps://console.aws.amazon.com/iam/y eligiendo elRoles de(Se ha creado el certificado). Si no se enumeranroles de IAM, significa que no existe ningún rol de IAM apropiado, por lo que la única opción es que laherramienta cree uno.
• Cloud virtual privada
El valor predeterminado de esta configuración es la cuenta VPC predeterminada, que puede encontrarabriendo la consola de VPC enhttps://console.aws.amazon.com/vpc/y eligiendoSus VPC. La cuentade VPC predeterminada tieneSíen laVPC predeterminadade la tabla VPC. Puede que tenga quedesplazarse horizontalmente para ver esa columna. Puede elegir otra VPC o hacer que la herramientacree una nueva VPC para su aplicación.
160
AWS SDK for .NET Developer GuideProtección de los datos
Seguridad para estoAWSProducto oservicio
La seguridad en la nube de Amazon Web Services (AWS) es la máxima prioridad. Como cliente deAWS, se beneficia de una arquitectura de red y un centro de datos que se han diseñado para satisfacerlos requisitos de seguridad de las organizaciones más exigentes. La seguridad es una responsabilidadcompartida entre AWS y usted. En el modelo de responsabilidad compartida, se habla de «seguridad de lanube» y «seguridad en la nube»:
Seguridad de la nube: AWS es responsable de proteger la infraestructura que ejecuta todos los serviciosofrecidos en la nube de AWS y proporcionar servicios que usted puede utilizar de forma segura. Nuestraresponsabilidad en torno a la seguridad es la mayor prioridad en AWS y auditores externos prueban yverifican la eficacia de nuestra seguridad con frecuencia como parte de los programas de conformidad deAWS.
Seguridad en la nube: su responsabilidad viene determinada por el servicio de AWS que usa y otrosfactores, como la confidencialidad de los datos, los requisitos de la organización y las normas yreglamentos aplicables.
EsteAWSproducto o servicio sigue elModelo de responsabilidad compartidaa través de la Amazon WebServices (AWS) que soporta. Para obtener información sobre la seguridad de los servicios de AWS,consulte la página de documentación sobre la seguridad de los servicios de AWS y los servicios de AWSsujetos a las medidas de conformidad de AWS de cada programa de conformidad.
Temas• Protección de datos enAWSproducto o servicio (p. 161)• Identity and Access Management paraAWSProducto o servicio (p. 162)• Validación de la conformidad paraAWSProducto o servicio (p. 162)• Resiliencia para estoAWSProducto o servicio (p. 163)• Seguridad de la infraestructura para esteAWSProducto o servicio (p. 164)• Aplicación de TLS 1.2 en esteAWSProducto o servicio (p. 164)• Migración de cliente de cifrado de Amazon S3 (p. 167)
Protección de datos enAWSproducto o servicioLaAWS Modelo de responsabilidad compartidase aplica a la protección de datos enAWSProducto oservicio. Como se describe en este modelo, AWS es responsable de proteger la infraestructura global queejecuta toda la Nube de AWS . Usted es responsable de mantener el control sobre el contenido alojado enesta infraestructura. Este contenido incluye la configuración de seguridad y las tareas de administraciónde los servicios de AWS que utiliza usted. Para obtener más información acerca de la privacidad de datos,consulte las Preguntas frecuentes sobre privacidad de datos. Para obtener información acerca de laprotección de datos en Europa, consulte la publicación de blog The AWS Shared Responsability Model andGDPR en el Blog de seguridad de AWS.
Para fines de protección de datos, recomendamos proteger Cuenta de AWS y configurar cuentas deusuario individuales conAWS Identity and Access Management(IAM). De esta manera, solo se otorgana cada usuario los permisos necesarios para cumplir con sus obligaciones laborales. También lerecomendamos proteger sus datos de las siguientes formas:
161
AWS SDK for .NET Developer GuideIdentity and Access Management
• Utilice Multi-Factor Authentication (MFA) con cada cuenta.• Utilice SSL/TLS para comunicarse con los recursos de AWS. Le recomendamos TLS 1.2 o una versión
posterior.• Configure la API y el registro de actividad de los usuarios con AWS CloudTrail.• Utilice las soluciones de cifrado de AWS, junto con todos los controles de seguridad predeterminados de
los servicios de AWS.• Utilice avanzados servicios de seguridad administrados, como Amazon Macie, que le ayuden a detectar
y proteger los datos personales almacenados en Amazon S3.• Si necesita módulos criptográficos validados FIPS 140-2 cuando accede a AWS a través de una interfaz
de línea de comandos o una API, utilice un punto de enlace de FIPS. Para obtener más informaciónacerca de los puntos de enlace de FIPS disponibles, consulte Estándar de procesamiento de lainformación federal (FIPS) 140-2.
Le recomendamos encarecidamente que nunca introduzca información de identificación confidencial,como, por ejemplo, direcciones de email de sus clientes, en etiquetas o en los campos de formatolibre, como el campo Name (Nombre). Esto incluye cuando trabaje con esteAWSproducto o serviciou otroAWSutilizando la consola, API,AWS CLI, o bienAWSSDK. Los datos que ingresa en etiquetas ocampos de formato libre utilizados para los nombres se pueden utilizar para los registros de facturacióno diagnóstico. Si proporciona una URL a un servidor externo, le recomendamos encarecidamente que noincluya información de credenciales en la URL para validar la solicitud para ese servidor.
Identity and Access ManagementparaAWSProducto o servicio
AWS Identity and Access Management(IAM) es un Amazon Web Services (AWS) que ayuda aladministrador a controlar de forma segura el acceso aAWSde AWS. Los administradores de IAM controlanquién puedeautenticado(iniciado sesión) yAutorizado(tienen permisos) para usar recursos enAWSServiciosde . IAM es un servicio de AWS que puede utilizar sin cargo adicional.
Para usar esteAWSproducto o servicio para accederAWS, necesita unaAWSCuenta de yAWSCredencialesde . Para aumentar la seguridad de su cuenta de AWS, le recomendamos que utilice un usuario de IAM ala hora de proporcionar credenciales de acceso en lugar de usar las credenciales de su cuenta de AWS.
Para obtener más información acerca de cómo trabajar con IAM, consulteAWS Identity and AccessManagement.
Para obtener información general acerca de los usuarios de IAM y por qué son importantes para laseguridad de su cuenta, consulteAWSCredenciales de seguridad deen laReferencia general de AmazonWeb Services.
EsteAWSproducto o servicio sigue elModelo de responsabilidad compartidaa través de la Amazon WebServices (AWS) que soporta. Para obtener información sobre la seguridad de los servicios de AWS,consulte la página de documentación sobre la seguridad de los servicios de AWS y los servicios de AWSsujetos a las medidas de conformidad de AWS de cada programa de conformidad.
Validación de la conformidad paraAWSProducto oservicio
EsteAWSproducto o servicio sigue elModelo de responsabilidad compartidaa través de la Amazon WebServices (AWS) que soporta. Para obtener información sobre la seguridad de los servicios de AWS,
162
AWS SDK for .NET Developer GuideResiliencia
consulte la página de documentación sobre la seguridad de los servicios de AWS y los servicios de AWSsujetos a las medidas de conformidad de AWS de cada programa de conformidad.
Hay auditores externos que evalúan la seguridad y la conformidad de los servicios de AWS en diferentesprogramas de conformidad de AWS. Entre estos se incluyen SOC, PCI, FedRAMP, HIPAA y otros. AWSproporciona una lista actualizada con frecuencia de los servicios de AWS adscritos al ámbito de programasde conformidad específicos en Servicios de AWS en el ámbito del programa de conformidad.
Los informes de auditoría de terceros están disponibles para su descarga utilizando AWS Artifact. Paraobtener más información, consulte Descarga de informes en AWS Artifact.
Para obtener más información acerca de los programas de conformidad de AWS, consulte Programas deconformidad de AWS.
Su responsabilidad de cumplimiento al usar esteAWSproducto o servicio para acceder a unAWSsedetermina en función de la sensibilidad de los datos, los objetivos de conformidad de su organización,así como de la legislación y los reglamentos aplicables. Si su uso de AWS está sujeto a estándares deconformidad como HIPAA, PCI o FedRAMP, AWS cuenta con recursos que le servirán de ayuda:
• Guías de inicio rápido de seguridad y conformidad: guías de implementación que ofrecenconsideraciones sobre la arquitectura y los pasos para implementar entornos de referencia centrados enla seguridad y la conformidad de AWS.
• Documento técnico de Architecting for HIPAA Security and Compliance— Un documento técnico quedescribe cómo las empresas pueden usarAWSpara crear aplicaciones que se ajusten al estándarHIPAA.
• AWSRecursos de conformidad: un conjunto de manuales y guías que podrían aplicarse a su sector yubicación.
• AWS Config: un servicio que evalúa en qué medida las configuraciones de los recursos cumplen lasprácticas internas, las directrices del sector y la normativa.
• AWS Security Hub: un servicio que ofrece una vista integral de su estado de seguridad en AWSque lo ayuda a comprobar la conformidad con las normas del sector de seguridad y las prácticasrecomendadas.
Resiliencia para estoAWSProducto o servicioLa infraestructura global de Amazon Web Services (AWS) se basa en regiones y zonas de disponibilidadde AWS.
Las regiones de AWS proporcionan varias zonas de disponibilidad físicamente independientes y aisladasque se encuentran conectadas mediante redes con un alto nivel de rendimiento y redundancia, además debaja latencia.
Con las zonas de disponibilidad, puede diseñar y utilizar aplicaciones y bases de datos que realizanuna conmutación por error automática entre zonas de disponibilidad sin interrupciones. Las zonas dedisponibilidad tienen una mayor disponibilidad, tolerancia a errores y escalabilidad que las infraestructurastradicionales de centros de datos únicos o múltiples.
Para obtener más información sobre zonas de disponibilidad y las regiones de AWS, consulteInfraestructura global de AWS.
EsteAWSproducto o servicio sigue elModelo de responsabilidad compartidaa través de la Amazon WebServices (AWS) que soporta. Para obtener información sobre la seguridad de los servicios de AWS,consulte la página de documentación sobre la seguridad de los servicios de AWS y los servicios de AWSsujetos a las medidas de conformidad de AWS de cada programa de conformidad.
163
AWS SDK for .NET Developer GuideSeguridad de la infraestructura
Seguridad de la infraestructura paraesteAWSProducto o servicio
EsteAWSproducto o servicio sigue elModelo de responsabilidad compartidaa través de la Amazon WebServices (AWS) que soporta. Para obtener información sobre la seguridad de los servicios de AWS,consulte la página de documentación sobre la seguridad de los servicios de AWS y los servicios de AWSsujetos a las medidas de conformidad de AWS de cada programa de conformidad.
Aplicación de TLS 1.2 en esteAWSProducto oservicio
Para aumentar la seguridad al comunicarse conAWS, debe configurar esteAWSpara utilizar TLS 1.2 o unaversión posterior.
El AWS SDK for .NET utiliza el tiempo de ejecución de .NET subyacente para determinar qué protocolode seguridad utilizar. De forma predeterminada, las versiones actuales de .NET utilizan el último protocoloconfigurado que admite el sistema operativo. Su aplicación puede anular este comportamiento del SDK,pero no se recomienda hacerlo.
.NET CoreDe forma predeterminada, .NET Core utiliza el último protocolo configurado que admite el sistemaoperativo. El AWS SDK for .NET no proporciona un mecanismo para anular esto.
Si está utilizando una versión de .NET Core anterior a la 2.1, le recomendamos encarecidamente queactualice la versión de .NET Core.
Consulte lo siguiente para obtener información específica de cada sistema operativo.
Windows
Las distribuciones modernas de Windows tienen la compatibilidad con TLS 1.2 habilitada de formapredeterminada. Si está ejecutando en Windows 7 SP1 o Windows Server 2008 R2 SP1, debe asegurarsede que la compatibilidad con TLS 1.2 esté habilitada en el registro, como se describe en https://docs.microsoft.com/en-us/windows-server/security/tls/tls-registry-settings#tls-12. Si está ejecutando unadistribución anterior, debe actualizar el sistema operativo.
macOS
Si ejecuta .NET Core 2.1 o una versión posterior, TLS 1.2 está habilitado de forma predeterminada. TLS1.2 es compatible conOS X Mavericks v10.9 o posterior. .NET Core versión 2.1 y posteriores requierenversiones más recientes de macOS, como se describe enhttps://docs.microsoft.com/en-us/dotnet/core/install/dependencies?tabs=netcore21&pivots=os-macos.
Si está utilizando.NET Core 1.0, .NET Core usa OpenSSL en macOS, una dependencia que debeinstalarse por separado. OpenSSL agregó soporte para TLS 1.2 en la versión 1.0.1 (14/03/2012).
Linux
.NET Core en Linux requiere OpenSSL, que viene incluido con muchas distribuciones de Linux. Perotambién se puede instalar por separado. OpenSSL agregó soporte para TLS 1.2 en la versión 1.0.1
164
AWS SDK for .NET Developer Guide.NET Framework
(14/03/2012). Si está utilizando una versión moderna de .NET Core (2.1 o posterior) y ha instalado unadministrador de paquetes, es probable que se haya instalado una versión más moderna de OpenSSLpara usted.
Para estar seguro, puede ejecutar openssl version en un terminal y verificar que la versión seaposterior a 1.0.1.
.NET FrameworkSi está ejecutando una versión moderna de .NET Framework (4.7 o posterior) y una versión moderna deWindows (al menos Windows 8 para clientes, Windows Server 2012 o posterior para servidores), TLS 1.2está habilitado y utilizado de forma predeterminada.
Si está utilizando un tiempo de ejecución de .NET Framework que no utiliza la configuración del sistemaoperativo (.NET Framework 3.5 a 4.5.2), AWS SDK for .NET intentará agregar compatibilidad con TLS 1.1y TLS 1.2 a los protocolos compatibles. Si está utilizando .NET Framework 3.5, esto tendrá éxito solo si seinstala la revisión activa adecuada, de la siguiente manera:
• Windows 10 versión 1511 y Windows Server 2016 —KB3156421• Windows 8.1 y Windows Server 2012 R2 —KB3154520 ADAPTADOR DE CABLE• Windows Server 2012:KB3154519• Windows 7 SP1 y Server 2008 R2 SP1:KB3154518 ADAPTADOR DE CABLE
Si la aplicación se está ejecutando en .NET Framework más reciente en Windows 7 SP1 o WindowsServer 2008 R2 SP1, debe asegurarse de que la compatibilidad con TLS 1.2 esté habilitada en elregistro, como se describe en https://docs.microsoft.com/en-us/windows-server/security/tls/tls-registry-settings#tls-12. Las versiones más recientes de Windows lo tienen habilitado de forma predeterminada.
Para obtener las prácticas recomendadas detalladas sobre el uso de TLS con .NET Framework, consulte elartículo de Microsoft en https://docs.microsoft.com/en-us/dotnet/framework/network-programming/tls.
AWS Tools for PowerShellAWS Tools for PowerShell usar el AWS SDK for .NET para todas las llamadas a servicios de AWS. Elcomportamiento del entorno depende de la versión de Windows PowerShell que esté ejecutando, de lasiguiente manera.
Windows PowerShell 2.0 a 5.x
Windows PowerShell 2.0 a 5.x se ejecuta en .NET Framework. Puede comprobar qué tiempo de ejecuciónde .NET (2.0 o 4.0) está utilizando PowerShell mediante el siguiente comando.
$PSVersionTable.CLRVersion
• Al utilizar .NET Runtime 2.0, siga las instrucciones proporcionadas anteriormente con relación a AWSSDK for .NET y .NET Framework 3.5.
• Al utilizar .NET Runtime 4.0, siga las instrucciones proporcionadas anteriormente con relación a AWSSDK for .NET y .NET Framework 4+.
Windows PowerShell 6.0
Windows PowerShell 6.0 y versiones posteriores se ejecutan en .NET Core. Puede verificar qué versiónde .NET Core se está utilizando ejecutando el siguiente comando.
165
AWS SDK for .NET Developer GuideXamarin
[System.Reflection.Assembly]::GetEntryAssembly().GetCustomAttributes([System.Runtime.Versioning.TargetFrameworkAttribute], $true).FrameworkName
Siga las instrucciones proporcionadas anteriormente con respecto a AWS SDK for .NET y la versiónpertinente de .NET Core.
XamarinPara Xamarin, consulte las instrucciones en https://docs.microsoft.com/en-us/xamarin/cross-platform/app-fundamentals/transport-layer-security. En resumen:
Para Android
• Requiere Android 5.0 o posterior.• Propiedades del proyecto,Opciones de Android: La implementación de HttpClient se debe establecer
enAndroidy la implementación SSL/TLS establecida enTLS nativo 1.2+.
Para iOS
• Requiere iOS 7 o posterior.• Propiedades del proyecto,Construir iOS: La implementación de HttpClient se debe establecer
enNSURLSession.
Para macOS
• Requiere macOS 10.9 o posterior.• Opciones del proyecto,Build,Creación de Mac: La implementación de HttpClient se debe establecer
enNSURLSession.
UnityDebe usar Unity 2018.2 o una versión posterior y usar el tiempo de ejecución de scripting equivalentede.NET 4.x. Puede configurarlo en Project Settings (Configuración del proyecto), Configuration(Configuración), Player (Reproductor), tal como se describe en https://docs.unity3d.com/2019.1/Documentation/Manual/ScriptingRuntimeUpgrade.html. El tiempo de ejecución de scripting equivalentede .NET 4.x permite la compatibilidad con TLS 1.2 para todas las plataformas Unity que ejecutan Mono oIL2CPP. Para obtener más información, consulte https://blogs.unity3d.com/2018/07/11/scripting-runtime-improvements-in-unity-2018-2/.
Navegador (para Blazor WebAssembly)WebAssembly se ejecuta en el navegador en lugar de en el servidor, y utiliza el navegador para gestionarel tráfico HTTP. Por lo tanto, la compatibilidad con TLS está determinada por la compatibilidad con elnavegador.
Blazor WebAssembly, en vista previa para ASP.NET Core 3.1, solo es compatible con navegadorescompatibles con WebAssembly, como se describe enhttps://docs.microsoft.com/en-us/aspnet/core/blazor/supported-platforms. Todos los navegadores principales admiten TLS 1.2 antes de admitir WebAssembly.Si este es el caso de su navegador, si su aplicación se ejecuta, puede comunicarse a través de TLS 1.2.
Consulte la documentación de su navegador para obtener más información y verificación.
166
AWS SDK for .NET Developer GuideMigración de clientes de cifrado de S3
Migración de cliente de cifrado de Amazon S3En este tema se muestra cómo migrar las aplicaciones desde la versión 1 (V1) del cliente de cifrado deAmazon Simple Storage Service (Amazon S3) a la versión 2 (V2) y garantizar la disponibilidad de lasaplicaciones durante todo el proceso de migración.
Los objetos cifrados con el cliente V2 no se pueden descifrar con el cliente V1. Para facilitar la migración alnuevo cliente sin tener que volver a cifrar todos los objetos a la vez, se ha proporcionado un cliente «V1-Transition». Este cliente puedeDescifradotanto objetos cifrados V1 como V2, peroCifrasólo en formatocompatible con V1. El cliente V2 puedeDescifradotanto objetos cifrados V1 como V2 (cuando estánhabilitados para objetos V1), peroCifrasólo en formato compatible con V2.
Información general sobre migraciónEsta migración ocurre en tres fases. Estas fases se introducen aquí y se describen en detalle másadelante. Cada fase debe completarse paraTodoque utilizan objetos compartidos antes de que se inicie lasiguiente fase.
1. Actualice los clientes existentes a los clientes V1-Transition para leer nuevos formatos. Primero,actualice sus aplicaciones para tomar una dependencia en el cliente de transición V1 en lugar delcliente V1. El cliente V1-Transition permite que el código existente descifre objetos escritos por losnuevos clientes V2 y objetos escritos en formato compatible con V1.
Note
El cliente de transición V1 se proporciona únicamente para fines de migración. Continúe conla actualización al cliente V2 después de pasar al cliente de transición V1.
2. Migrar clientes de transición V1 a clientes V2 para escribir nuevos formatos. A continuación,reemplace todos los clientes de transición V1 en sus aplicaciones con clientes V2 y establezca el perfilde seguridad enV2AndLegacy. La configuración de este perfil de seguridad en clientes V2 permite aesos clientes descifrar objetos cifrados en formato compatible con V1.
3. Actualice los clientes V2 para que ya no lean los formatos V1. Finalmente, después de que todoslos clientes se hayan migrado a V2 y todos los objetos se hayan cifrado o vuelto a cifrar en formatocompatible con V2, establezca el perfil de seguridad V2 enV2en lugar deV2AndLegacy. Esto evita eldescifrado de objetos que están en formato compatible con V1.
Actualizar clientes existentes a clientes de transiciónV1 para leer nuevos formatosEl cliente de cifrado V2 utiliza algoritmos de cifrado que las versiones anteriores del cliente no admiten.El primer paso en la migración es actualizar los clientes de descifrado V1 para que puedan leer el nuevoformato.
El cliente de transición V1 permite a las aplicaciones descifrar objetos cifrados V1 y V2. Este cliente formaparte de laAmazon.Extensions.S3.CifradoPaquete de NuGet. Realice los siguientes pasos en cada una delas aplicaciones para utilizar el cliente V1-Transition.
1. Tome una nueva dependencia en elAmazon.Extensions.S3.CifradoEl paquete. Si su proyectodepende directamente de laAWSSDK.S3orAWSSDK.KeyManagementService, debe actualizar esasdependencias o eliminarlas para que sus versiones actualizadas se introduzcan con este nuevopaquete.
2. Cambie elusingDeclaración deAmazon.S3.EncryptionDeaAmazon.Extensions.S3.Encryption, de la siguiente manera:
167
AWS SDK for .NET Developer GuideMigración de clientes de transición V1 a
clientes V2 para escribir nuevos formatos
// using Amazon.S3.Encryption; using Amazon.Extensions.S3.Encryption;
3. Reconstruya y vuelva a implementar la aplicación.
El cliente de transición V1 es totalmente compatible con API con el cliente V1, por lo que no se requierenotros cambios de código.
Migración de clientes de transición V1 a clientes V2para escribir nuevos formatosEl cliente V2 forma parte delAmazon.Extensions.S3.CifradoPaquete de NuGet. Permite a las aplicacionesdescifrar objetos cifrados V1 y V2 (si están configurados para hacerlo), pero cifra los objetos sólo enformato compatible con V2.
Después de actualizar sus clientes existentes para leer el nuevo formato de cifrado, puede proceder aactualizar de forma segura las aplicaciones a los clientes de cifrado y descifrado V2. Realice los siguientespasos en cada una de las aplicaciones para utilizar el cliente V2:
1. Cambie EncryptionMaterials a EncryptionMaterialsV2.
a. Cuando utilice KMS:
i. Proporcione un ID de clave de KMS.ii. Declarar el método de cifrado que está utilizando; es decir,KmsType.KmsContext.iii. Proporcione un contexto de cifrado a KMS para asociarlo con esta clave de datos. Puede
enviar un diccionario vacío (el contexto de cifrado de Amazon aún se fusionará), pero serecomienda proporcionar contexto adicional.
b. Cuando se utilizan métodos de ajuste de claves proporcionados por el usuario (cifrado simétrico oasimétrico):
i. Proporcione unaAESo unRSAque contiene los materiales de cifrado.ii. Declarar qué algoritmo de cifrado utilizar; es
decir,SymmetricAlgorithmType.AesGcmorAsymmetricAlgorithmType.RsaOaepSha1.2. CambiarAmazonS3CryptoConfigurationDe
aAmazonS3CryptoConfigurationV2conSecurityProfileEstableceenSecurityProfile.V2AndLegacy.
3. Cambie AmazonS3EncryptionClient a AmazonS3EncryptionClientV2. Este cliente tomaelAmazonS3CryptoConfigurationV2yEncryptionMaterialsV2Objetos de los pasos anteriores.
Ejemplo: Contexto de KMS a KMS+Premigración
using System.Security.Cryptography;using Amazon.S3.Encryption;
var encryptionMaterial = new EncryptionMaterials("1234abcd-12ab-34cd-56ef-1234567890ab");var configuration = new AmazonS3CryptoConfiguration(){ StorageMode = CryptoStorageMode.ObjectMetadata};var encryptionClient = new AmazonS3EncryptionClient(configuration, encryptionMaterial);
168
AWS SDK for .NET Developer GuideMigración de clientes de transición V1 a
clientes V2 para escribir nuevos formatos
Postransformación
using System.Security.Cryptography;using Amazon.Extensions.S3.Encryption;using Amazon.Extensions.S3.Encryption.Primitives;
var encryptionContext = new Dictionary<string, string>();var encryptionMaterial = new EncryptionMaterialsV2("1234abcd-12ab-34cd-56ef-1234567890ab", KmsType.KmsContext, encryptionContext);var configuration = new AmazonS3CryptoConfigurationV2(SecurityProfile.V2AndLegacy){ StorageMode = CryptoStorageMode.ObjectMetadata};var encryptionClient = new AmazonS3EncryptionClientV2(configuration, encryptionMaterial);
Ejemplo: Algoritmo simétrico (ajuste de claves AES-CBC a AES-GCM)StorageModepuede serObjectMetadataorInstructionFile.
Premigración
using System.Security.Cryptography;using Amazon.S3.Encryption;
var symmetricAlgorithm = Aes.Create();var encryptionMaterial = new EncryptionMaterials(symmetricAlgorithm);var configuration = new AmazonS3CryptoConfiguration(){ StorageMode = CryptoStorageMode.ObjectMetadata};var encryptionClient = new AmazonS3EncryptionClient(configuration, encryptionMaterial);
Postransformación
using System.Security.Cryptography;using Amazon.Extensions.S3.Encryption;using Amazon.Extensions.S3.Encryption.Primitives;
var symmetricAlgorithm = Aes.Create();var encryptionMaterial = new EncryptionMaterialsV2(symmetricAlgorithm, SymmetricAlgorithmType.AesGcm);var configuration = new AmazonS3CryptoConfigurationV2(SecurityProfile.V2AndLegacy){ StorageMode = CryptoStorageMode.ObjectMetadata};var encryptionClient = new AmazonS3EncryptionClientV2(configuration, encryptionMaterial);
Note
Al descifrar con AES-GCM, lea todo el objeto hasta el final antes de empezar a utilizar los datosdescifrados. Esto es para verificar que el objeto no se ha modificado desde que se cifró.
Ejemplo: Algoritmo asimétrico (ajuste de clave RSA a RSA-OAEP-SHA1)StorageModepuede serObjectMetadataorInstructionFile.
169
AWS SDK for .NET Developer GuideActualizar clientes V2 para que ya no lean los formatos V1
Premigración
using System.Security.Cryptography;using Amazon.S3.Encryption;
var asymmetricAlgorithm = RSA.Create();var encryptionMaterial = new EncryptionMaterials(asymmetricAlgorithm);var configuration = new AmazonS3CryptoConfiguration(){ StorageMode = CryptoStorageMode.ObjectMetadata};var encryptionClient = new AmazonS3EncryptionClient(configuration, encryptionMaterial);
Postransformación
using System.Security.Cryptography;using Amazon.Extensions.S3.Encryption;using Amazon.Extensions.S3.Encryption.Primitives;
var asymmetricAlgorithm = RSA.Create();var encryptionMaterial = new EncryptionMaterialsV2(asymmetricAlgorithm, AsymmetricAlgorithmType.RsaOaepSha1);var configuration = new AmazonS3CryptoConfigurationV2(SecurityProfile.V2AndLegacy){ StorageMode = CryptoStorageMode.ObjectMetadata};var encryptionClient = new AmazonS3EncryptionClientV2(configuration, encryptionMaterial);
Actualizar clientes V2 para que ya no lean losformatos V1Eventualmente, todos los objetos se habrán cifrado o re-cifrado usando un cliente V2. Una vezcompletada esta conversión, puede deshabilitar la compatibilidad de V1 en los clientes V2 configurando lapropiedadSecurityProfilepropiedad aSecurityProfile.V2, tal y como se muestra en el siguientefragmento.
//var configuration = new AmazonS3CryptoConfigurationV2(SecurityProfile.V2AndLegacy);var configuration = new AmazonS3CryptoConfigurationV2(SecurityProfile.V2);
170
AWS SDK for .NET Developer GuideObtención de ensamblados de AWSSDK
Consideraciones especialesparaAWS SDK for .NET
Esta sección contiene consideraciones para casos especiales en los que las configuraciones oprocedimientos normales no son adecuados o suficientes.
Temas• Obtención de ensamblados para elAWS SDK for .NET (p. 171)• Acceso a credenciales y perfiles en una aplicación (p. 172)• Consideraciones especiales para el soporte de Unity (p. 174)• Consideraciones especiales para soporte Xamarin (p. 175)
Obtención de ensamblados para elAWS SDKfor .NET
En este tema se describe cómo obtener los ensamblados AWSSDK y almacenarlos localmente (o en lasinstalaciones) para utilizarlos en los proyectos. Esto esnoel método recomendado para manejar referenciasde SDK, pero es necesario en algunos entornos.
Note
El método recomendado para manejar referencias de SDK es descargar e instalar solo lospaquetes NuGet que cada proyecto necesita. Ese método se describe enInstalar paquetesAWSSDK con NuGet (p. 29).
Si no puede o no tiene permiso para descargar e instalar paquetes NuGet por proyecto, las siguientesopciones están disponibles para usted.
Descargue y extraiga archivos de(Recuerde que este no es elMétodo recomendado (p. 29)para el manejo de referencias a laAWS SDKfor .NET.)
1. Descargue el siguiente archivo ZIP:aws-sdk-netstandard2.0.zipNote
Si necesita ensamblados AWSSDK para .NET Framework en lugar de .NET Core,consulteDescargue y extraiga archivos deen la guía del desarrollador de la versión 3.
2. Extraiga los ensamblados a alguna carpeta de «descarga» en su sistema de archivos; no importadónde. Anote esta carpeta.
3. Al configurar el proyecto, obtiene los ensamblados necesarios de esta carpeta, tal y como se describeenInstalar ensamblados AWSSDK sin NuGet (p. 31).
Instalar el MSI en Windows(Recuerde que este no es elMétodo recomendado (p. 29)para el manejo de referencias a laAWS SDKfor .NET.)
171
AWS SDK for .NET Developer GuideAcceso a credenciales y perfiles en una aplicación
Si necesita instalar un MSI en lugar de usar NuGet o uno de los métodos descritos anteriormente,puede encontrar elheredadoMSI enhttps://sdk-for-net.amazonwebservices.com/latest/AWSToolsAndSDKForNet.msi.
De forma predeterminada, elAWS SDK for .NETSe ha instalado en elProgram FilesDe, que requiereprivilegios de administrador. Para instalar el SDK sin privilegios de administrador, elija una carpetadiferente.
Acceso a credenciales y perfiles en una aplicaciónEl método preferido para utilizar credenciales es permitir que la claseAWS SDK for .NETpara encontrarlosy recuperarlos por usted, como se describe enCredenciales y resolución de perfiles (p. 25).
Sin embargo, también puede configurar la aplicación para recuperar perfiles y credenciales de forma activay luego usar explícitamente dichas credenciales al crear una claseAWScliente de servicio.
Para recuperar perfiles y credenciales de forma activa, utilice las clasesdelAmazon.runtime.CredentialManagementespacio de nombres de.
• Para buscar un perfil en un archivo que utilice la herramientaAWSformato de archivo de credenciales (yasea elCompartidoAWSarchivo de credenciales en su ubicación predeterminada (p. 21)o un archivo decredenciales personalizado), utilice la herramientaSharedCredentialsFileLa clase Los archivos en esteformato a veces se llaman simplementearchivos de credencialesen este texto por brevedad.
• Para encontrar un perfil en el SDK Store, utilice la herramientaNetSDKCredentialsFileLa clase• Para buscar tanto en un archivo de credenciales como en el almacén SDK, en función de la
configuración de una propiedad de clase, utilice la herramientaCredentialProfileStoreChainLa clase
Puede utilizar esta clase para buscar perfiles de. También puede utilizar esta clase parasolicitarAWSdirectamente en lugar de usar el comandoAWSCredentialsFactoryclase (descrita acontinuación).
• Para recuperar o crear varios tipos de credenciales desde un perfil, utilice laherramientaAWScredentialsFactoryLa clase
En las secciones siguientes se proporcionan ejemplos para estas clases.
Ejemplos de la clase CredentialProfileStoreChainPuede obtener credenciales o perfiles deCredentialProfileStoreChainmediante el uso de laclaseTryGetawScredentialsorTryGetProfileMétodos de LaProfilesLocationLa clase determina elcomportamiento de los métodos, como se indica a continuación:
• SiProfilesLocationes nulo o vacío, busque en el SDK Store si la plataforma lo admite y, acontinuación, busque el archivo compartidoAWSen la ubicación predeterminada.
• Si el archivo deProfilesLocationcontiene un valor, busque en el archivo de credencialesespecificado en la propiedad.
Obtenga las credenciales del SDK Store o del archivocompartidoAWSarchivo de credencialesEste ejemplo muestra cómo obtener credenciales mediante la claseCredentialProfileStoreChainyluego use las credenciales para crear una claseAmazons3ClientUn objeto de. Las credenciales puedenprovenir del SDK Store o delAWSen la ubicación predeterminada.
172
AWS SDK for .NET Developer GuideEjemplos de clases SharedCredentialsFile
y awScredentialsFactory
En este ejemplo también se utiliza el métodoAmazon.runtime.awscredentialsLa clase
var chain = new CredentialProfileStoreChain();AWSCredentials awsCredentials;if (chain.TryGetAWSCredentials("some_profile", out awsCredentials)){ // Use awsCredentials to create an Amazon S3 service client using (var client = new AmazonS3Client(awsCredentials)) { var response = await client.ListBucketsAsync(); Console.WriteLine($"Number of buckets: {response.Buckets.Count}"); }}
Obtener un perfil desde el SDK Store o desde elAWSarchivo decredencialesEn este ejemplo se muestra cómo obtener un perfil mediante la clase CredentialProfileStORECHain. Lascredenciales pueden provenir del SDK Store o delAWSen la ubicación predeterminada.
En este ejemplo también se utiliza el métodoCredentialProfileLa clase
var chain = new CredentialProfileStoreChain();CredentialProfile basicProfile;if (chain.TryGetProfile("basic_profile", out basicProfile)){ // Use basicProfile}
Obtener credenciales de un archivo de credencialespersonalizadoEn este ejemplo se muestra cómo obtener credenciales mediante la clase CredentialProfileStORECHain.Las credenciales provienen de un archivo que utiliza la propiedadAWSpero se encuentra en una ubicaciónalternativa.
En este ejemplo también se utiliza el métodoAmazon.runtime.awscredentialsLa clase
var chain = new CredentialProfileStoreChain("c:\\Users\\sdkuser\\customCredentialsFile.ini");AWSCredentials awsCredentials;if (chain.TryGetAWSCredentials("basic_profile", out awsCredentials)){ // Use awsCredentials to create an AWS service client}
Ejemplos de clases SharedCredentialsFile yawScredentialsFactoryCrear un AmazonS3Client mediante la claseSharedCredentialsFileEn estos ejemplos se muestra cómo encontrar un perfil en la claseAWSarchivo de credenciales,crearAWSdel perfil y, a continuación, utilice las credenciales para crear unAmazons3ClientUn objeto de. Eneste ejemplo se utiliza la claseSharedCredentialsFileLa clase
173
AWS SDK for .NET Developer GuideSoporte de Unity
En este ejemplo también se utiliza el métodoCredentialProfiley la claseAmazon.runtime.awscredentialsLaclase
CredentialProfile basicProfile;AWSCredentials awsCredentials;var sharedFile = new SharedCredentialsFile();if (sharedFile.TryGetProfile("basic_profile", out basicProfile) && AWSCredentialsFactory.TryGetAWSCredentials(basicProfile, sharedFile, out awsCredentials)){ // use awsCredentials to create an Amazon S3 service client using (var client = new AmazonS3Client(awsCredentials, basicProfile.Region)) { var response = await client.ListBucketsAsync(); Console.WriteLine($"Number of buckets: {response.Buckets.Count}"); }}
Note
LaNetSDKCredentialsFilese puede usar exactamente de la misma manera, excepto quese crea una instancia de un nuevo objeto NetSDKCredentialsFile en lugar de un objetoSharedCredentialsFile.
Consideraciones especiales para el soporte deUnity
Cuando se utiliza la herramientaAWS SDK for .NETy.NET Standard 2.0para su aplicación Unity, suaplicación debe hacer referencia a laAWS SDK for .NET(archivos DLL) directamente en lugar de utilizarNuGet. Dado este requisito, las siguientes son acciones importantes que tendrá que realizar.
• Necesita obtener elAWS SDK for .NETy aplicarlos al proyecto. Para obtener información acerca de cómohacerlo, consulteDescargue y extraiga archivos de (p. 171)En el temaObtención de ensamblados deAWSSDK (p. 171).
• Debe incluir las siguientes DLL en su proyecto de Unity junto con las DLL paraAWSSDK.Corey elotroAWSLos servicios que utiliza. A partir de la versión 3.5.109 delAWS SDK for .NET, el archivo ZIPestándar de.NET contiene estos archivos DLL adicionales.• Microsoft.Bcl.AsyncInterfaces.dll• System.Runtime.CompilerServices.Unsafe.dll• System.Threading.Tasks.Extensions.dll
• Si utilizaIL2CPPpara construir su proyecto Unity, debe agregar unlink.xmla la carpeta Asset paraevitar que se elimine el código. Lalink.xmldebe enumerar todos los ensamblados AWSSDK que estáutilizando, y cada uno debe incluir el archivopreserve="all"Atributo. El siguiente fragmento muestraun ejemplo de este archivo.
<linker> <assembly fullname="AWSSDK.Core" preserve="all"/> <assembly fullname="AWSSDK.DynamoDBv2" preserve="all"/> <assembly fullname="AWSSDK.Lambda" preserve="all"/></linker>
174
AWS SDK for .NET Developer GuideXamarin Soporte
Note
Para leer información básica interesante relacionada con este requisito, consulte el artículoenhttp://aws.amazon.com/blogs/developer/referencing-the-aws-sdk-for-net-standard-2-0-from-unity-xamarin-or-uwp/.
Además de estas consideraciones especiales, consulte¿Qué ha cambiado para la versión 3.5 (p. 52)Paraobtener información acerca de cómo migrar su aplicación Unity a la versión 3.5 deAWS SDK for .NET.
Consideraciones especiales para soporte XamarinLos proyectos de Xamarin (nuevos y existentes) deben dirigirse a .NET Standard 2.0. ConsulteCompatibilidad de .NET Standard 2.0 en Xamarin.Forms y Compatibilidad con implementaciones de .NET.
Vea también la información sobreBiblioteca de clases portátil y Xamarin (p. 51).
175
AWS SDK for .NET Developer Guide
Historial de revisiónEn la siguiente tabla se describen los cambios importantes que se han realizado en la desde la últimaversiónAWS SDK for .NETGuía para desarrolladores. Para obtener notificaciones sobre las actualizacionesde esta documentación, puede suscribirse a una fuente RSS.
update-history-change update-history-description update-history-date
Migración desde .NET Standard1.3 (p. 54)
El es compatible con .NETStandard 1.3 en elAWS SDKfor .NETha llegado a su fin devida.
25 de marzo de 2021
AWS Herramienta deimplementación de.NET (vistaprevia) (p. 150)
Se ha añadido información devista previa sobre elAWS.NET,que puede utilizar paraimplementar una aplicacióndesde la CLI de.NET.
15 de marzo de 2021
Versión 3.5 de la AWS SDKfor .NET (p. 51)
Versión 3.5 de laAWS SDKfor .NETSe ha liberado el.
25 de agosto de 2020
Paginadores (p. 40) Se agregaron paginadores amuchos clientes de servicio, loque hace que la paginación delos resultados de API sea másconveniente.
24 de agosto de 2020
Reintentos y tiempos deespera (p. 37)
Se ha añadido información sobrelos modos de reintento.
20 de agosto de 2020
Migración de clientes de cifradoS3 (p. 167)
Se agregó información sobrecómo migrar los clientes decifrado de Amazon S3 de V1 aV2.
7 de agosto de 2020
Uso de claves KMS para elcifrado S3 (p. 121)
Ejemplo actualizado para usar laversión 2 del cliente de cifradoS3.
6 de agosto de 2020
Migración desde .NET Standard1.3 (p. 54)
Se ha agregado informaciónsobre cómo finalizar el soportepara .NET Standard 1.3 a finalesde 2020.
18 de mayo de 2020
Inicio rápido (p. 5) Se ha añadido una sección deinicio rápido con configuraciónbásica y tutoriales para presentaral lector elAWS SDK for .NET.
27 de marzo de 2020
Aplicación de TLS 1.2 (p. 164) Se agregó información acerca decómo aplicar TLS 1.2 en el SDK.
10 de marzo de 2020
176
