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 invocarse a través de puntos de conexión HTTPS.
No es necesario añadir un AWS::Serverless::Api recurso de forma explícita a una plantilla de definición de aplicaciones AWS sin servidor. Un recurso de este tipo se crea implícitamente a partir de la unión de eventos de API definidos en los recursos AWS::Serverless::Function definidos en la plantilla que no hacen referencia a un recurso AWS::Serverless::Api.
Se debe utilizar un AWS::Serverless::Api recurso para definir y documentar la API que se utiliza OpenApi, lo que proporciona más capacidad para configurar los recursos subyacentes de Amazon API Gateway.
Te recomendamos que utilices AWS CloudFormation enlaces o políticas de IAM para comprobar que los recursos de API Gateway tienen autorizadores adjuntos para controlar el acceso a ellos.
Para obtener más información sobre el uso de AWS CloudFormation ganchos, consulte Registrar ganchos en la guía del usuario de la AWS CloudFormation CLI y en el apigw-enforce-authorizer
Para obtener más información sobre el uso de las políticas de IAM, consulta Exigir que las rutas de API tengan autorización en la Guía para desarrolladores de API Gateway.
nota
Al realizar la implementación en AWS CloudFormation, AWS SAM transforma AWS SAM los recursos en AWS CloudFormation recursos. Para obtener más información, consulte Recursos AWS CloudFormation de AWS SAM generados.
Sintaxis
Para declarar esta entidad en tu plantilla AWS Serverless Application Model (AWS SAM), usa la siguiente sintaxis.
YAML
Type: AWS::Serverless::Api Properties: AccessLogSetting:
AccessLogSetting
AlwaysDeploy:Boolean
ApiKeySourceType:String
Auth:ApiAuth
BinaryMediaTypes:List
CacheClusterEnabled:Boolean
CacheClusterSize:String
CanarySetting:CanarySetting
Cors:String | CorsConfiguration
DefinitionBody:JSON
DefinitionUri:String | ApiDefinition
Description:String
DisableExecuteApiEndpoint:Boolean
Domain:DomainConfiguration
EndpointConfiguration:EndpointConfiguration
FailOnWarnings:Boolean
GatewayResponses:Map
MergeDefinitions:Boolean
MethodSettings:MethodSettings
MinimumCompressionSize:Integer
Mode:String
Models:Map
Name:String
OpenApiVersion:String
PropagateTags:Boolean
StageName:String
Tags:Map
TracingEnabled:Boolean
Variables:Map
Propiedades
-
AccessLogSetting
-
Configuración de registros de acceso para una etapa.
Tipo: AccessLogSetting
Obligatorio: no
AWS CloudFormation compatibilidad: esta propiedad se pasa directamente a la
AccessLogSetting
propiedad de unAWS::ApiGateway::Stage
recurso. -
AlwaysDeploy
-
Siempre implementas la API, incluso cuando no se han detectado cambios en la API.
Tipo: Booleano
Obligatorio: no
AWS CloudFormation compatibilidad: esta propiedad es exclusiva AWS SAM y no tiene un AWS CloudFormation equivalente.
-
ApiKeySourceType
-
Origen de la clave de API para medir las solicitudes de acuerdo con un plan de uso. Los valores válidos son
HEADER
yAUTHORIZER
.Tipo: cadena
Obligatorio: no
AWS CloudFormation compatibilidad: esta propiedad se pasa directamente a la
ApiKeySourceType
propiedad de unAWS::ApiGateway::RestApi
recurso. -
Auth
-
Configura la autorización para controlar el acceso a su API de API Gateway.
Para obtener más información sobre cómo configurar el acceso mediante, AWS SAM consulteControla el acceso a la API con tu AWS SAM plantilla. Para ver un ejemplo que muestra cómo anular un autorizador global, consulte. Anule un autorizador global para su API de REST de Amazon API Gateway
Tipo: ApiAuth
Obligatorio: no
AWS CloudFormation compatibilidad: esta propiedad es exclusiva de AWS SAM y no tiene un AWS CloudFormation equivalente.
-
BinaryMediaTypes
-
Lista de tipos MIME que su API puede devolver. Use esta opción para habilitar el soporte binario paraAPIs. Utilice ~1 en lugar de/en los tipos MIME.
Tipo: lista
Obligatorio: no
AWS CloudFormation compatibilidad: esta propiedad es similar a la
BinaryMediaTypes
propiedad de unAWS::ApiGateway::RestApi
recurso. La lista de BinaryMediaTypes se añade tanto al AWS CloudFormation recurso como al documento de OpenAPI. -
CacheClusterEnabled
-
Indica si el almacenado en caché está habilitado para la etapa. Para almacenar en caché las respuestas, también debe configurar
CachingEnabled
paratrue
bajoMethodSettings
.Tipo: Booleano
Obligatorio: no
AWS CloudFormation compatibilidad: esta propiedad se pasa directamente a la
CacheClusterEnabled
propiedad de unAWS::ApiGateway::Stage
recurso. -
CacheClusterSize
-
El tamaño del clúster de caché de la etapa.
Tipo: cadena
Obligatorio: no
AWS CloudFormation compatibilidad: esta propiedad se pasa directamente a la
CacheClusterSize
propiedad de unAWS::ApiGateway::Stage
recurso. -
CanarySetting
-
Configure una prueba canario como una etapa de una implementación normal.
Tipo: CanarySetting
Obligatorio: no
AWS CloudFormation compatibilidad: esta propiedad se pasa directamente a la
CanarySetting
propiedad de unAWS::ApiGateway::Stage
recurso. -
Cors
-
Gestione el intercambio de recursos entre orígenes (CORS) para todas sus API Gateway. APIs Especifica el dominio que quieres permitir como cadena o especifica un diccionario con una configuración de Cors adicional.
nota
CORS requiere modificar AWS SAM la definición de OpenAPI. Cree una definición de OpenAPI en línea en
DefinitionBody
para activar CORS.Para obtener más información sobre CORS, consulta Habilitar CORS para un recurso de la API de REST de API Gateway en la Guía para desarrolladores de API Gateway.
Tipo: Cadena | CorsConfiguration
Obligatorio: no
AWS CloudFormation compatibilidad: esta propiedad es exclusiva AWS SAM y no tiene un AWS CloudFormation equivalente.
-
DefinitionBody
-
Especificación de OpenAPI que describe su API. Si no se especifica ni
DefinitionUri
niDefinitionBody
, SAM generaráDefinitionBody
para usted en función de la configuración de la plantilla.Para hacer referencia a un local OpenAPI usa la
AWS::Include
transformación en el archivo que define tu API. Para obtener más información, consulte ¿Cómo se AWS SAM cargan los archivos locales.Tipo: JSON
Obligatorio: no
AWS CloudFormation compatibilidad: esta propiedad es similar a la
Body
propiedad de unAWS::ApiGateway::RestApi
recurso. Si se proporcionan determinadas propiedades, el contenido se puede insertar o modificar en ellas DefinitionBody antes de pasarlo a ellas CloudFormation. Las propiedades incluyenAuth
,BinaryMediaTypes
,Cors
,GatewayResponses
,Models
y unaEventSource
del tipo Api para unaAWS::Serverless::Function
correspondiente. -
DefinitionUri
-
Amazon S3 Uri, la ruta de archivo local o el 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 no se especifica ni
DefinitionUri
niDefinitionBody
, SAM generaráDefinitionBody
para usted en función de la configuración de la plantilla.Si se proporciona una ruta de archivo local, la plantilla debe seguir el flujo de trabajo que incluye el comando
sam deploy
osam package
para que la definición se transforme correctamente.Las funciones intrínsecas no se admiten en OpenApi los archivos externos a los que hace referencia
DefinitionUri
. En su lugar, utilice laDefinitionBody
propiedad con la transformación Include para importar una OpenApi definición a la plantilla.Tipo: Cadena | ApiDefinition
Obligatorio: no
AWS CloudFormation compatibilidad: esta propiedad es similar a la
BodyS3Location
propiedad de unAWS::ApiGateway::RestApi
recurso. Las propiedades anidadas de Amazon S3 tienen un nombre diferente. -
Description
-
Una descripción del recurso de la Api.
Tipo: cadena
Obligatorio: no
AWS CloudFormation compatibilidad: esta propiedad se pasa directamente a la
Description
propiedad de unAWS::ApiGateway::RestApi
recurso. -
DisableExecuteApiEndpoint
-
Especifica si los clientes pueden invocar la API mediante el punto de conexión
execute-api
predeterminado. De forma predeterminada, los clientes pueden invocar su API con elhttps://{api_id}.execute-api.{region}.amazonaws.com
predeterminado. Para exigir que los clientes utilicen un nombre de dominio personalizado para invocar su API, especificaTrue
.Tipo: Booleano
Obligatorio: no
AWS CloudFormation compatibilidad: esta propiedad es similar a la
DisableExecuteApiEndpoint
propiedad de unAWS::ApiGateway::RestApi
recurso. Se pasa directamente a la propiedaddisableExecuteApiEndpoint
de una extensiónx-amazon-apigateway-endpoint-configuration
, que se agrega a la propiedadBody
de un recursoAWS::ApiGateway::RestApi
. -
Domain
-
Configura un dominio personalizado para esta API de API Gateway.
Tipo: DomainConfiguration
Obligatorio: no
AWS CloudFormation compatibilidad: esta propiedad es exclusiva AWS SAM y no tiene un AWS CloudFormation equivalente.
-
EndpointConfiguration
-
El tipo de punto de conexión de una API de REST.
Tipo: EndpointConfiguration
Obligatorio: no
AWS CloudFormation compatibilidad: esta propiedad es similar a la
EndpointConfiguration
propiedad de unAWS::ApiGateway::RestApi
recurso. Las propiedades anidadas de configuración tienen un nombre diferente. -
FailOnWarnings
-
Especifica si se va a restaurar la creación de API (
true
) o no (false
) cuando se encuentra una advertencia. El valor predeterminado esfalse
.Tipo: Booleano
Obligatorio: no
AWS CloudFormation compatibilidad: esta propiedad se pasa directamente a la
FailOnWarnings
propiedad de unAWS::ApiGateway::RestApi
recurso. -
GatewayResponses
-
Configura las respuestas de Gateway para una API. Las respuestas de Gateway 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 la OpenApi extensión Api Gateway para Gateway Responses.
Tipo: mapa
Obligatorio: no
AWS CloudFormation compatibilidad: esta propiedad es exclusiva de AWS SAM y no tiene un AWS CloudFormation equivalente.
-
MergeDefinitions
-
AWS SAM genera un OpenAPI especificación a partir de la fuente de eventos de su API.
true
Especifica que AWS SAM se combine esto con la línea OpenAPI especificación definida en suAWS::Serverless::Api
recurso. Especifica quefalse
no se fusione.MergeDefinitions
requiere que la propiedad deDefinitionBody
paraAWS::Serverless::Api
se defina.MergeDefinitions
no es compatible con la propiedad deDefinitionUri
paraAWS::Serverless::Api
.Valor predeterminado:
false
Tipo: Booleano
Obligatorio: no
AWS CloudFormation compatibilidad: esta propiedad es exclusiva AWS SAM y no tiene un AWS CloudFormation equivalente.
-
MethodSettings
-
Configura todos los ajustes de la etapa de la API, incluidos los de registro, métricas, cachetTL y la limitación controlada.
Tipo: lista de MethodSetting
Obligatorio: no
AWS CloudFormation compatibilidad: esta propiedad se pasa directamente a la
MethodSettings
propiedad de unAWS::ApiGateway::Stage
recurso. -
MinimumCompressionSize
-
Permita la compresión de los cuerpos de respuesta en función del encabezado Accept-Encoding del cliente. La compresión se desencadena cuando el tamaño del cuerpo de respuesta es superior o igual al umbral configurado. El umbral de tamaño máximo del cuerpo es de 10 MB (10.485.760 bytes). - Se admiten los siguientes tipos de compresión: gzip, deflate e identidad.
Tipo: entero
Obligatorio: no
AWS CloudFormation compatibilidad: esta propiedad se pasa directamente a la
MinimumCompressionSize
propiedad de unAWS::ApiGateway::RestApi
recurso. -
Mode
-
Esta propiedad solo se aplica cuando se utiliza OpenAPI para definir su API de REST. El
Mode
determina cómo API Gateway maneja las actualizaciones de recursos. Para obtener más información, consulte la propiedad Mode del AWS::ApiGateway::RestApiTipo de recurso de .Valores válidos:
overwrite
omerge
Tipo: cadena
Obligatorio: no
AWS CloudFormation compatibilidad: esta propiedad se pasa directamente a la
Mode
propiedad de unAWS::ApiGateway::RestApi
recurso. -
Models
-
Los esquemas que deben utilizar sus métodos API. Estos esquemas se pueden describir mediante JSON o YAML. Consulte la sección de ejemplos al final de esta página para ver ejemplos de modelos.
Tipo: mapa
Obligatorio: no
AWS CloudFormation compatibilidad: esta propiedad es exclusiva AWS SAM y no tiene un AWS CloudFormation equivalente.
-
Name
-
Un nombre para el RestApi recurso API Gateway
Tipo: cadena
Obligatorio: no
AWS CloudFormation compatibilidad: esta propiedad se pasa directamente a la
Name
propiedad de unAWS::ApiGateway::RestApi
recurso. -
OpenApiVersion
-
Versión de OpenApi a utilizar. Puede ser
2.0
para la especificación Swagger o para una de las versiones OpenApi 3.0, por ejemplo.3.0.1
Para más información sobre OpenAPI, consulta la Especificación de OpenAPI.nota
AWS SAM crea un escenario llamado
Stage
por defecto. Si se establece esta propiedad en cualquier valor válido, se impedirá la creación de la etapaStage
.Tipo: cadena
Obligatorio: no
AWS CloudFormation compatibilidad: esta propiedad es exclusiva AWS SAM y no tiene un AWS CloudFormation equivalente.
-
Indique si quiere pasar o no las etiquetas de la propiedad
Tags
a los recursos generados AWS::Serverless::Api. EspecificaTrue
para propagar las etiquetas en los recursos generados.Tipo: Booleano
Obligatorio: no
Valor predeterminado:
False
AWS CloudFormation compatibilidad: esta propiedad es exclusiva de AWS SAM y no tiene un AWS CloudFormation equivalente.
-
StageName
-
El nombre de la etapa, que API Gateway utiliza como el primer segmento de la ruta en el Identificador uniforme de recursos (URI) invocado.
Para hacer referencia al recurso de la etapa, utilice
. Para obtener más información sobre cómo hacer referencia a los recursos generados cuando se especifica un recurso AWS::Serverless::Api, consulta Recursos de AWS CloudFormation generados cuando se especifica AWS::Serverless::Api. Para obtener información general sobre AWS CloudFormation los recursos generados, consulteRecursos AWS CloudFormation de AWS SAM generados.<api-logical-id>
.StageTipo: cadena
Obligatorio: sí
AWS CloudFormation compatibilidad: esta propiedad es similar a la
StageName
propiedad de unAWS::ApiGateway::Stage
recurso. Es obligatorio en SAM, pero no en API GatewayNotas adicionales: la API implícita tiene el nombre de etapa de “Prod”.
-
Un mapa (cadena a cadena) que especifica las etiquetas que deben añadirse a esta etapa de la API Gateway. Para obtener más información sobre las claves y los valores válidos de las etiquetas, consulta la etiqueta de recursos en la Guía del usuario de AWS CloudFormation .
Tipo: mapa
Obligatorio: no
AWS CloudFormation compatibilidad: esta propiedad es similar a la
Tags
propiedad de unAWS::ApiGateway::Stage
recurso. La propiedad Tags de SAM consta de pares clave-valor; en CloudFormation ella, consiste en una lista de objetos Tag. -
TracingEnabled
-
Indica si se ha habilitado el rastreo activo con X-Ray para la fase. Para obtener más información sobre X-Ray, consulte Rastreo de las solicitudes de los usuarios a REST APIs mediante X-Ray en la Guía para desarrolladores de API Gateway.
Tipo: Booleano
Obligatorio: no
AWS CloudFormation compatibilidad: esta propiedad se transfiere directamente a la
TracingEnabled
propiedad de unAWS::ApiGateway::Stage
recurso. -
Variables
-
Un mapa (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._~:/?#&=,-]+
.Tipo: mapa
Obligatorio: no
AWS CloudFormation compatibilidad: esta propiedad se pasa directamente a la
Variables
propiedad de unAWS::ApiGateway::Stage
recurso.
valores devueltos
Ref.
Cuando se proporciona el ID lógico de este recurso a la función intrínseca Ref
, devuelve el ID del API de API Gateway subyacente.
Para obtener más información sobre el uso de la función Ref
, consulta Ref
en la Guía del usuario de AWS CloudFormation .
Ventilador: GetAtt
Fn::GetAtt
devuelve un valor para un atributo especificado de este tipo. A continuación se indican los atributos disponibles y los valores devueltos de muestra.
Para obtener más información acerca de cómo usar Fn::GetAtt
, consulta Fn::GetAtt
en la Guía del usuario de AWS CloudFormation .
RootResourceId
-
El ID del recurso raíz de un recurso
RestApi
, como por ejemploa0bc123d4e
.
Ejemplos
SimpleApiExample
Un archivo de AWS SAM plantilla de Hello World que contiene una función Lambda con un punto final de API. Se trata de un archivo de AWS SAM plantilla completo para una aplicación sin servidor que funcione.
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 method at the root resource via an Api event Type: AWS::Serverless::Function Properties: Events: ApiEvent: Type: Api Properties: Path: / Method: get RestApiId: Ref: ApiGatewayApi Runtime: python3.10 Handler: index.handler InlineCode: | def handler(event, context): return {'body': 'Hello World!', 'statusCode': 200}
ApiCorsExample
Un fragmento AWS SAM de plantilla con una API definida en un archivo Swagger externo junto con integraciones de Lambda y configuraciones de CORS. Esto es solo una parte de un archivo de plantilla que muestra una definición. AWS SAM AWS::Serverless::Api
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
ApiCognitoAuthExample
Un fragmento AWS SAM de plantilla con una API que utiliza Amazon Cognito para autorizar las solicitudes contra la API. Es solo una parte de un archivo de AWS SAM plantilla que muestra una definición. AWS::Serverless::Api
YAML
Resources: ApiGatewayApi: Type: AWS::Serverless::Api Properties: StageName: Prod Cors: "'*'" Auth: DefaultAuthorizer: MyCognitoAuthorizer Authorizers: MyCognitoAuthorizer: UserPoolArn: Fn::GetAtt: [MyCognitoUserPool, Arn]
ApiModelsExample
Un fragmento AWS SAM de plantilla con una API que incluye un esquema de modelos. Esto es solo una parte de un archivo de AWS SAM plantilla, que muestra una AWS::Serverless::Api definició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 archivo de AWS SAM plantilla de Hello World que contiene una función Lambda con un punto final 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é, consulta Habilitar el almacenamiento en caché de la API para mejorar la capacidad de respuesta en la Guía para desarrolladores de API Gateway.
YAML
AWSTemplateFormatVersion: '2010-09-09' Transform: AWS::Serverless-2016-10-31 Description: AWS SAM template with a simple API definition with caching turned on Resources: ApiGatewayApi: Type: AWS::Serverless::Api Properties: StageName: prod CacheClusterEnabled: true CacheClusterSize: '0.5' MethodSettings: - ResourcePath: / HttpMethod: GET CachingEnabled: true CacheTtlInSeconds: 300 Tags: CacheMethods: All ApiFunction: # Adds a GET method at the root resource via an Api event Type: AWS::Serverless::Function Properties: Events: ApiEvent: Type: Api Properties: Path: / Method: get RestApiId: Ref: ApiGatewayApi Runtime: python3.10 Handler: index.handler InlineCode: | def handler(event, context): return {'body': 'Hello World!', 'statusCode': 200}