AWS::Serverless::Api - AWS Serverless Application Model

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

AWS::Serverless::Api

Crea una colección de recursos y métodos de Amazon API Gateway que se pueden invocar a través de puntos de enlace HTTPS.

UnAWS::Serverless::Apino es necesario agregar explícitamente a un recursoAWSPlantilla de definición de aplicación sin servidor. Un recurso de este tipo se crea implícitamente a partir de la unión de eventos Api definidos enAWS::Serverless::Functionrecursos definidos en la plantilla que no hacen referencia a unAWS::Serverless::Apirecurso.

UnAWS::Serverless::Apidebe utilizarse para definir y documentar la API mediante OpenAPI, lo que proporciona más capacidad para configurar los recursos subyacentes de Amazon API Gateway.

Le recomendamos que utiliceAWS CloudFormationhooks o políticas de IAM para verificar que los recursos de API Gateway tienen autorizadores asociados a ellos para controlar el acceso a ellos.

Para obtener más información acerca del uso deAWS CloudFormationEnlaces, consulteEnlaces de registroen laAWS CloudFormationGuía de usuario de CLIy laautorizador apigw-force- GitHub .

Para obtener más información acerca del uso de políticas de IAM, consulteRequerir que las rutas API tengan autorizaciónen laGuía para desarrolladores API Gateway.

Sintaxis

Para declarar esta entidad en suAWS Serverless Application Model(AWS SAM), utilice la siguiente sintaxis.

Properties

AccessLogSetting

Configura la configuración del registro de acceso para una etapa.

Type: AccessLogSetting

Obligatorio: No

AWS CloudFormationcompatibilidad: Esta propiedad se transfiere directamente alAccessLogSettingpropiedad de unAWS::ApiGateway::Stagerecurso.

Auth

Configure la autorización para controlar el acceso a su API de API Gateway.

Para obtener más información acerca de la configuración del acceso medianteAWS SAMconsulteControlar el acceso a las API de API Gateway.

Type: Apiauth

Obligatorio: No

AWS CloudFormationcompatibilidad: Esta propiedad es específica deAWS SAMy no tieneAWS CloudFormationequivalente.

BinaryMediaTypes

Lista de tipos MIME que su API podría devolver. Utilízalo para habilitar la compatibilidad binaria para las API. Utilice ~1 en lugar de/en los tipos mime.

Type: List

Obligatorio: No

AWS CloudFormationcompatibilidad: Esta propiedad es similar a laBinaryMediaTypespropiedad de unAWS::ApiGateway::RestApirecurso. Lista de BinaryMediaTypes se añade a los dosAWS CloudFormationrecurso y documento de OpenAPI.

CacheClusterEnabled

Indica si el almacenamiento en caché está habilitado para la fase. Para almacenar en caché respuestas, también debe establecerCachingEnabledatruebajoMethodSettings.

Type: Booleano

Obligatorio: No

AWS CloudFormationcompatibilidad: Esta propiedad se transfiere directamente alCacheClusterEnabledpropiedad de unAWS::ApiGateway::Stagerecurso.

CacheClusterSize

El tamaño de clúster de caché de la fase.

Type: Cadena

Obligatorio: No

AWS CloudFormationcompatibilidad: Esta propiedad se transfiere directamente alCacheClusterSizepropiedad de unAWS::ApiGateway::Stagerecurso.

CanarySetting

Configure un ajuste canario en una etapa de una implementación regular.

Type: CanarySetting

Obligatorio: No

AWS CloudFormationcompatibilidad: Esta propiedad se transfiere directamente alCanarySettingpropiedad de unAWS::ApiGateway::Stagerecurso.

Cors

Gestione el uso compartido de recursos entre orígenes (CORS) para todas sus API de API Gateway. Especifique el dominio que se va a permitir como cadena o especifique un diccionario con configuración adicional de Cors. NOTA: El CORS requiereAWS SAMpara modificar la definición de OpenAPI. Por lo tanto, solo funciona si está en línea OpenApi se define con DefinitionBody.

Para obtener más información acerca de CORS, consulteHabilitación de CORS para un recurso de API Gateway REST deen laGuía para desarrolladores API Gateway.

Type: Cadena |CorsConfiguration

Obligatorio: No

AWS CloudFormationcompatibilidad: Esta propiedad es específica deAWS SAMy no tieneAWS CloudFormationequivalente.

DefinitionBody

Especificación de OpenAPI que describe tu API. Si ningunoDefinitionUriniDefinitionBodyse especifican, SAM generará unDefinitionBodypara ti en función de la configuración de tu plantilla.

Type: JSON

Obligatorio: No

AWS CloudFormationcompatibilidad: Esta propiedad es similar a laBodypropiedad de unAWS::ApiGateway::RestApirecurso. Si se proporcionan determinadas propiedades, el contenido puede insertarse o modificarse en el DefinitionBody antes de transferirse a CloudFormation. Las propiedades incluyenAuth,BinaryMediaTypes,Cors,GatewayResponses,Models, y unEventSourcede tipo Api para un correspondienteAWS::Serverless::Function.

DefinitionUri

Uri de Amazon S3, ruta de archivo local u objeto de ubicación del documento de OpenAPI que define la API. El objeto Amazon S3 al que hace referencia esta propiedad debe ser un archivo OpenAPI válido. Si ningunoDefinitionUriniDefinitionBodyse especifican, SAM generará unDefinitionBodypara ti en función de la configuración de tu plantilla.

Si se proporciona una ruta de archivo local, la plantilla debe pasar por el flujo de trabajo que incluye elsam deployosam package, para que la definición se transforme correctamente.

Las funciones intrínsecas no se admiten en externas OpenApi archivos a los que hace referencia aDefinitionUri. En su lugar, utilice elDefinitionBodypropiedad con elIncluir transformaciónpara importar un OpenApi definición en la plantilla.

Type: Cadena |Definición APID

Obligatorio: No

AWS CloudFormationcompatibilidad: Esta propiedad es similar a laBodyS3Locationpropiedad de unAWS::ApiGateway::RestApirecurso. Las propiedades de Amazon S3 anidadas tienen un nombre diferente.

Description

Es una descripción del recurso Api.

Type: Cadena

Obligatorio: No

AWS CloudFormationcompatibilidad: Esta propiedad se transfiere directamente alDescriptionpropiedad de unAWS::ApiGateway::RestApirecurso.

DisableExecuteApiEndpoint

Especifica si los clientes pueden invocar la API mediante el valor predeterminado.execute-apipunto de conexiónhttps://{api_id}.execute-api.{region}.amazonaws.com. De forma predeterminada, los clientes pueden invocar su API con el punto de enlace predeterminado. Para exigir que los clientes utilicen únicamente un nombre de dominio personalizado para invocar su API, desactive el punto de enlace predeterminado.

Type: Booleano

Obligatorio: No

AWS CloudFormationcompatibilidad: Esta propiedad se transfiere directamente alDisableExecuteApiEndpointpropiedad de unAWS::ApiGateway::RestApirecurso.

Domain

Configura un dominio personalizado para esta API de API Gateway.

Type: DomainConfiguration

Obligatorio: No

AWS CloudFormationcompatibilidad: Esta propiedad es específica deAWS SAMy no tieneAWS CloudFormationequivalente.

EndpointConfiguration

El tipo de punto de enlace de una API de REST.

Type: EndpointConfiguration

Obligatorio: No

AWS CloudFormationcompatibilidad: Esta propiedad es similar a laEndpointConfigurationpropiedad de unAWS::ApiGateway::RestApirecurso. Las propiedades de configuración anidadas reciben un nombre diferente.

GatewayResponses

Configura las respuestas de puerta de enlace para una API. Las respuestas de puerta de enlace son respuestas devueltas por API Gateway, ya sea directamente o mediante el uso de autorizadores Lambda. Para obtener más información, consulte la documentación de laAPI Gateway OpenApi extensión para respuestas de gateway.

Type: Mapeo

Obligatorio: No

AWS CloudFormationcompatibilidad: Esta propiedad es específica deAWS SAMy no tieneAWS CloudFormationequivalente.

MethodSettings

Configura todos los ajustes de la etapa de API, incluidos Registro, Métricas, CachetTL y Regulación.

Type: MethodSettings

Obligatorio: No

AWS CloudFormationcompatibilidad: Esta propiedad se transfiere directamente alMethodSettingspropiedad de unAWS::ApiGateway::Stagerecurso.

MinimumCompressionSize

Permitir la compresión de los cuerpos de respuesta en función del encabezado Accept-Encoding del cliente. La compresión se activa cuando el tamaño del cuerpo de la respuesta es superior o igual al umbral configurado. El umbral de tamaño máximo de cuerpo es de 10 MB (10.485.760 bytes). - Se admiten los siguientes tipos de compresión: gzip, deflate e identity.

Type: Entero

Obligatorio: No

AWS CloudFormationcompatibilidad: Esta propiedad se transfiere directamente alMinimumCompressionSizepropiedad de unAWS::ApiGateway::RestApirecurso.

Mode

Esta propiedad solo se aplica cuando se utiliza OpenAPI para definir su API REST. El Mode determina cómo API Gateway maneja las actualizaciones de recursos. Para obtener más información, consulteModapropiedad delAWS::ApiGateway::RestApiTipo de recurso de .

Valores válidos: overwrite o merge

Type: Cadena

Obligatorio: No

AWS CloudFormationcompatibilidad: Esta propiedad se transfiere directamente alModepropiedad de unAWS::ApiGateway::RestApirecurso.

Models

Los esquemas que utilizarán los métodos API. Estos esquemas se pueden describir mediante JSON o YAML. Consulte la sección Ejemplos en la parte inferior de esta página para ver modelos de ejemplo.

Type: Mapeo

Obligatorio: No

AWS CloudFormationcompatibilidad: Esta propiedad es específica deAWS SAMy no tieneAWS CloudFormationequivalente.

Name

Un nombre para API Gateway RestApi recurso

Type: Cadena

Obligatorio: No

AWS CloudFormationcompatibilidad: Esta propiedad se transfiere directamente alNamepropiedad de unAWS::ApiGateway::RestApirecurso.

OpenApiVersion

Versión de OpenApi para usar. Puede ser2.0para la especificación Swagger, o una de las OpenApi versiones 3.0, como3.0.1. Para obtener más información acerca de OpenAPI, consulte laEspecificación de OpenAPI.

Nota: Si se establece esta propiedad en cualquier valor válido, también se eliminará el escenarioStageque SAM crea.

Type: Cadena

Obligatorio: No

AWS CloudFormationcompatibilidad: Esta propiedad es específica deAWS SAMy no tieneAWS CloudFormationequivalente.

StageName

El nombre de la fase, que API Gateway utiliza como el primer segmento de la ruta en la invocación del Identificador uniforme de recursos (URI).

Para hacer referencia al recurso de etapa, utilice<api-logical-id>.Stage. Para obtener más información acerca de la referencia a recursos generados cuando unaAWS::Serverless::Apise ha especificado el recurso, consulteAWS CloudFormationrecursos generados cuando se especifica AWS። Serverless። Api. Para obtener información general acerca de generadoAWS CloudFormationrecursos, consulteGeneradoAWS CloudFormationrecursos.

Type: Cadena

Obligatorio: Sí

AWS CloudFormationcompatibilidad: Esta propiedad es similar a laStageNamepropiedad de unAWS::ApiGateway::Stagerecurso. Es obligatorio en SAM, pero no en API Gateway

Notas adicionales: La API implícita tiene un nombre artístico de «Prod».

Tags

Una asignación (cadena a cadena) que especifica las etiquetas que se agregarán a esta fase de API Gateway. Para obtener más información sobre las claves y los valores válidos para las etiquetas, consulteEtiqueta de recursoen laAWS CloudFormationGuía del usuario de.

Type: Mapeo

Obligatorio: No

AWS CloudFormationcompatibilidad: Esta propiedad es similar a laTagspropiedad de unAWS::ApiGateway::Stagerecurso. La propiedad Tags de SAM consta de pares Key:Value; en CloudFormation consiste en una lista de objetos Tag.

TracingEnabled

Indica si el rastreo activo con X-Ray está habilitado para la fase. Para obtener más información acerca de X-Ray, consulteRastreo de solicitudes de usuario a API de REST mediante X-Rayen laGuía para desarrolladores API Gateway.

Type: Booleano

Obligatorio: No

AWS CloudFormationcompatibilidad: Esta propiedad se transfiere directamente alTracingEnabledpropiedad de unAWS::ApiGateway::Stagerecurso.

Variables

Una asignación (cadena a cadena) que define las variables de la fase, donde el nombre de la variable es la clave y el valor de la variable es el valor. Los nombres de variables están limitados a caracteres alfanuméricos. Los valores deben coincidir con las siguientes expresiones regulares: [A-Za-z0-9._~:/?#&=,-]+.

Type: Mapeo

Obligatorio: No

AWS CloudFormationcompatibilidad: Esta propiedad se transfiere directamente alVariablespropiedad de unAWS::ApiGateway::Stagerecurso.

Valores devueltos

Ref.

Cuando se proporciona el ID lógico de este recurso a laReffunción intrínseca, devuelve el ID de la API de API Gateway subyacente.

Para obtener más información acerca del uso de laRef, consulteRefen laAWS CloudFormationGuía del usuario de.

Fn::GetAtt

Fn::GetAtt devuelve un valor para un atributo especificado de este tipo. Los valores siguientes son los atributos disponibles y los valores devueltos de ejemplo.

Para obtener más información acerca del uso deFn::GetAtt, consulteFn::GetAtten laAWS CloudFormationGuía del usuario de.

RootResourceId

El ID del recurso raíz de un recurso RestApi, como por ejemplo a0bc123d4e.

Ejemplos

Ejemplo de API simple

Un Hello WorldAWS SAMarchivo de plantilla que contiene una función Lambda con un extremo de API. Esto es un completoAWS SAMarchivo de plantilla para una aplicación sin servidor en funcionamiento.

YAML

AWSTemplateFormatVersion: '2010-09-09' Transform: AWS::Serverless-2016-10-31 Description: AWS SAM template with a simple API definition Resources: ApiGatewayApi: Type: AWS::Serverless::Api Properties: StageName: prod ApiFunction: # Adds a GET api endpoint at "/" to the ApiGatewayApi via an Api event Type: AWS::Serverless::Function Properties: Events: ApiEvent: Type: Api Properties: Path: / Method: get RestApiId: Ref: ApiGatewayApi Runtime: python3.7 Handler: index.handler InlineCode: | def handler(event, context): return {'body': 'Hello World!', 'statusCode': 200}

Ejemplo de APIC

UnAWS SAMfragmento de plantilla con una API definida en un archivo Swagger externo junto con integraciones Lambda y configuraciones CORS. Esto es solo un fragmento de unAWS SAMarchivo de plantilla que muestra unAWS::Serverless::Apidefinición.

YAML

Resources: ApiGatewayApi: Type: AWS::Serverless::Api Properties: StageName: Prod # Allows www.example.com to call these APIs # SAM will automatically add AllowMethods with a list of methods for this API Cors: "'www.example.com'" DefinitionBody: # Pull in an OpenApi definition from S3 'Fn::Transform': Name: 'AWS::Include' # Replace "bucket" with your bucket name Parameters: Location: s3://bucket/swagger.yaml

Ejemplo de Apicognito Auth

UnAWS SAMfragmento de plantilla con una API que utiliza Amazon Cognito para autorizar solicitudes contra la API. Esto es solo un fragmento de unAWS SAMarchivo de plantilla que muestra unAWS::Serverless::Apidefinición.

YAML

Resources: ApiGatewayApi: Type: AWS::Serverless::Api Properties: StageName: Prod Cors: "'*'" Auth: DefaultAuthorizer: MyCognitoAuthorizer Authorizers: MyCognitoAuthorizer: UserPoolArn: Fn::GetAtt: [MyCognitoUserPool, Arn]

Ejemplo de modelos API

UnAWS SAMfragmento de plantilla con una API que incluye un esquema Models. Esto es solo un fragmento de unAWS SAMarchivo de plantilla, que muestra unAWS::Serverless::Apidefinición con dos esquemas de modelo.

YAML

Resources: ApiGatewayApi: Type: AWS::Serverless::Api Properties: StageName: Prod Models: User: type: object required: - username - employee_id properties: username: type: string employee_id: type: integer department: type: string Item: type: object properties: count: type: integer category: type: string price: type: integer

Ejemplo de almacenamiento en caché

Un Hello WorldAWS SAMarchivo de plantilla que contiene una función Lambda con un extremo de API. La API tiene habilitado el almacenamiento en caché para un recurso y un método. Para obtener más información acerca del almacenamiento en caché, consulteHabilitación del almacenamiento en caché de la API para mejorar la capacidad de respuestaen laGuía para desarrolladores API Gateway.

YAML

AWSTemplateFormatVersion: '2010-09-09' Transform: AWS::Serverless-2016-10-31 Description: AWS SAM template with a simple API definition Resources: ApiGatewayApi: Type: AWS::Serverless::Api Properties: StageName: prod CacheClusterEnabled: true CacheClusterSize: '0.5' MethodSettings: - ResourcePath: / HttpMethod: GET CachingEnabled: true CacheTtlInSeconds: 300 ApiFunction: # Adds a GET api endpoint at "/" to the ApiGatewayApi via an Api event Type: AWS::Serverless::Function Properties: Events: ApiEvent: Type: Api Properties: Path: / Method: get RestApiId: Ref: ApiGatewayApi Runtime: python3.7 Handler: index.handler InlineCode: | def handler(event, context): return {'body': 'Hello World!', 'statusCode': 200}