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.
Un AWS::Serverless::Api no es necesario agregar explícitamente un recurso a AWS Plantilla de definición de aplicaciones 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::Función definidos en la plantilla que no hacen referencia a un recurso AWS::Serverless::Api.
Una AWS::Serverless::Api el recurso debe usarse para definir y documentar la API usando OpenApi, lo que proporciona más capacidad para configurar los recursos subyacentes de Amazon API Gateway.
Le recomendamos que utilice CloudFormation ganchos o políticas de IAM para verificar que los recursos de API Gateway tengan autorizadores adjuntos para controlar el acceso a ellos.
Para obtener más información sobre el uso CloudFormation ganchos, consulte Registrar ganchos en el CloudFormation Guía del usuario de la CLI y 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.
Este recurso también es compatible con Connectors recurso Attribute. Para obtener más información, consulte Administrar los permisos de recursos con AWS SAM conectores.
Cuando se implementa en AWS CloudFormation, AWS SAM transforma tu AWS SAM recursos en CloudFormation recursos. Para obtener más información, consulte Generado CloudFormation recursos para AWS SAM.
Sintaxis
Para declarar esta entidad en su AWS Serverless Application Model (AWS SAM), utilice la siguiente sintaxis.
YAML
Type: AWS::Serverless::Api Properties: AccessLogSetting:AccessLogSettingAlwaysDeploy:BooleanApiKeySourceType:StringAuth:ApiAuthBinaryMediaTypes:ListCacheClusterEnabled:BooleanCacheClusterSize:StringCanarySetting:CanarySettingCors:String | CorsConfigurationDefinitionBody:JSONDefinitionUri:String | ApiDefinitionDescription:StringDisableExecuteApiEndpoint:BooleanDomain:DomainConfigurationEndpointAccessMode:StringEndpointConfiguration:EndpointConfigurationFailOnWarnings:BooleanGatewayResponses:MapMergeDefinitions:BooleanMethodSettings:MethodSettingsMinimumCompressionSize:IntegerMode:StringModels:MapName:StringOpenApiVersion:StringPropagateTags:BooleanPolicy:JSONSecurityPolicy:StringStageName:StringTags:MapTracingEnabled:BooleanVariables:Map
Propiedades
-
AccessLogSetting -
Configuración de registros de acceso para una etapa.
Tipo: AccessLogSetting
Obligatorio: no
CloudFormation compatibilidad: Esta propiedad se pasa directamente al
AccessLogSettingpropiedad de unAWS::ApiGateway::Stagerecurso. -
AlwaysDeploy -
Siempre implementas la API, incluso cuando no se han detectado cambios en la API.
Tipo: Booleano
Obligatorio: no
CloudFormation compatibilidad: Esta propiedad es exclusiva de AWS SAM y no tiene un 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
HEADERyAUTHORIZER.Tipo: cadena
Obligatorio: no
CloudFormation compatibilidad: Esta propiedad se pasa directamente al
ApiKeySourceTypepropiedad de unAWS::ApiGateway::RestApirecurso. -
Auth -
Configura la autorización para controlar el acceso a su API de API Gateway.
Para obtener más información sobre la configuración del acceso mediante AWS SAM ver Controle el acceso a la API con su 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
CloudFormation compatibilidad: Esta propiedad es exclusiva de AWS SAM y no tiene un CloudFormation equivalente.
-
BinaryMediaTypes -
Lista de tipos MIME que su API puede devolver. Utilice esto para habilitar la compatibilidad con datos binarios para las API.
Tipo: lista
Obligatorio: no
CloudFormation compatibilidad: Esta propiedad es similar a
BinaryMediaTypespropiedad de unAWS::ApiGateway::RestApirecurso. La lista de BinaryMediaTypes se añade tanto a CloudFormation recurso y el documento OpenAPI. -
CacheClusterEnabled -
Indica si el almacenado en caché está habilitado para la etapa. Para almacenar en caché las respuestas, también debe configurar
CachingEnabledparatruebajoMethodSettings.Tipo: Booleano
Obligatorio: no
CloudFormation compatibilidad: Esta propiedad se pasa directamente al
CacheClusterEnabledpropiedad de unAWS::ApiGateway::Stagerecurso. -
CacheClusterSize -
El tamaño del clúster de caché de la etapa.
Tipo: cadena
Obligatorio: no
CloudFormation compatibilidad: Esta propiedad se pasa directamente al
CacheClusterSizepropiedad de unAWS::ApiGateway::Stagerecurso. -
CanarySetting -
Configure una prueba canario como una etapa de una implementación normal.
Tipo: CanarySetting
Obligatorio: no
CloudFormation compatibilidad: Esta propiedad se pasa directamente al
CanarySettingpropiedad de unAWS::ApiGateway::Stagerecurso. -
Cors -
Administrar Cross-origin uso compartido de recursos (CORS) para todas sus API de API Gateway. Especifica el dominio que quieres permitir como cadena o especifica un diccionario con una configuración de Cors adicional.
notaCORS requiere AWS SAM para modificar su definición de OpenAPI. Cree una definición de OpenAPI en línea en
DefinitionBodypara 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.
Escriba: Cadena | CorsConfiguration
Obligatorio: no
CloudFormation compatibilidad: Esta propiedad es exclusiva de AWS SAM y no tiene un CloudFormation equivalente.
-
DefinitionBody -
Especificación de OpenAPI que describe su API. Si no se especifica ni
DefinitionUriniDefinitionBody, SAM generaráDefinitionBodypara usted en función de la configuración de la plantilla.Para hacer referencia a un archivo local de OpenAPI que defina su API, usa la transformación
AWS::Include. Para obtener más información, consulta ¿Cómo AWS SAM carga los archivos locales.Tipo: JSON
Obligatorio: no
CloudFormation compatibilidad: Esta propiedad es similar a
Bodypropiedad de unAWS::ApiGateway::RestApirecurso. Si se proporcionan ciertas propiedades, el contenido puede insertarse o modificarse en el DefinitionBody antes de pasarlo a CloudFormation. Las propiedades incluyenAuth,BinaryMediaTypes,Cors,GatewayResponses,Modelsy unaEventSourcedel tipo Api para unaAWS::Serverless::Functioncorrespondiente. -
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
DefinitionUriniDefinitionBody, SAM generaráDefinitionBodypara 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 deployosam packagepara que la definición se transforme correctamente.Las funciones intrínsecas no son compatibles con las externas OpenApi archivos a los que hace referencia
DefinitionUri. Utilice en su lugar elDefinitionBodypropiedad con Incluir Transform para importar un OpenApi definición en la plantilla.Escriba: Cadena | ApiDefinition
Obligatorio: no
CloudFormation compatibilidad: Esta propiedad es similar a
BodyS3Locationpropiedad de unAWS::ApiGateway::RestApirecurso. Las propiedades anidadas de Amazon S3 tienen un nombre diferente. -
Description -
Una descripción del recurso de la Api.
Tipo: cadena
Obligatorio: no
CloudFormation compatibilidad: Esta propiedad se pasa directamente al
Descriptionpropiedad de unAWS::ApiGateway::RestApirecurso. -
DisableExecuteApiEndpoint -
Especifica si los clientes pueden invocar la API mediante el punto de conexión
execute-apipredeterminado. De forma predeterminada, los clientes pueden invocar su API con elhttps://{api_id}.execute-api.{region}.amazonaws.compredeterminado. Para exigir que los clientes utilicen un nombre de dominio personalizado para invocar su API, especificaTrue.Tipo: Booleano
Obligatorio: no
CloudFormation compatibilidad: Esta propiedad es similar a
DisableExecuteApiEndpointpropiedad de unAWS::ApiGateway::RestApirecurso. Se pasa directamente a la propiedaddisableExecuteApiEndpointde una extensiónx-amazon-apigateway-endpoint-configuration, que se agrega a la propiedadBodyde un recursoAWS::ApiGateway::RestApi. -
Domain -
Configura un dominio personalizado para esta API de API Gateway.
Tipo: DomainConfiguration
Obligatorio: no
CloudFormation compatibilidad: Esta propiedad es exclusiva de AWS SAM y no tiene un CloudFormation equivalente.
-
EndpointConfiguration -
El tipo de punto de conexión de una API de REST.
Tipo: EndpointConfiguration
Obligatorio: no
CloudFormation compatibilidad: Esta propiedad es similar a
EndpointConfigurationpropiedad de unAWS::ApiGateway::RestApirecurso. Las propiedades anidadas de configuración tienen un nombre diferente. -
EndpointAccessMode -
El modo de acceso al punto final de la API REST. Obligatorio cuando se utilizan políticas de seguridad mejoradas (aquellas con el prefijo:
SecurityPolicy_).Valores válidos:
STRICToBASICTipo: cadena
Obligatorio: no
CloudFormation compatibilidad: Esta propiedad se pasa directamente al
EndpointAccessModepropiedad de unAWS::ApiGateway::RestApirecurso. -
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
CloudFormation compatibilidad: Esta propiedad se pasa directamente al
FailOnWarningspropiedad de unAWS::ApiGateway::RestApirecurso. -
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 del Api Gateway OpenApi extensión para Gateway Responses.
Tipo: mapa
Obligatorio: no
CloudFormation compatibilidad: Esta propiedad es exclusiva de AWS SAM y no tiene un CloudFormation equivalente.
-
MergeDefinitions -
AWS SAM genera un OpenAPI especificación de la fuente de eventos de su API. Especifique
truetener AWS SAM combina esto en línea OpenAPI especificación definida en suAWS::Serverless::Apirecurso. Especifica quefalseno se fusione.MergeDefinitionsrequiere que la propiedad deDefinitionBodyparaAWS::Serverless::Apise defina.MergeDefinitionsno es compatible con la propiedad deDefinitionUriparaAWS::Serverless::Api.Valor predeterminado:
falseTipo: Booleano
Obligatorio: no
CloudFormation compatibilidad: Esta propiedad es exclusiva de AWS SAM y no tiene un 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
CloudFormation compatibilidad: Esta propiedad se pasa directamente al
MethodSettingspropiedad de unAWS::ApiGateway::Stagerecurso. -
MinimumCompressionSize -
Permita la compresión de los cuerpos de respuesta en función de los del cliente Accept-Encoding encabezado. 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
CloudFormation compatibilidad: Esta propiedad se pasa directamente al
MinimumCompressionSizepropiedad de unAWS::ApiGateway::RestApirecurso. -
Mode -
Esta propiedad solo se aplica cuando se utiliza OpenAPI para definir su API de REST. El
Modedetermina cómo API Gateway maneja las actualizaciones de recursos. Para obtener más información, consulta la propiedad Modo en el tipo de recurso AWS::ApiGateway::RestApi.Valores válidos:
overwriteomergeTipo: cadena
Obligatorio: no
CloudFormation compatibilidad: Esta propiedad se pasa directamente al
Modepropiedad de unAWS::ApiGateway::RestApirecurso. -
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
CloudFormation compatibilidad: Esta propiedad es exclusiva de AWS SAM y no tiene un CloudFormation equivalente.
-
Name -
Un nombre para la puerta de enlace de API RestApi recurso
Tipo: cadena
Obligatorio: no
CloudFormation compatibilidad: Esta propiedad se pasa directamente al
Namepropiedad de unAWS::ApiGateway::RestApirecurso. -
OpenApiVersion -
Versión de OpenApi para usar. Esto puede ser
2.0para la especificación Swagger, o una de las OpenApi versiones 3.0, como3.0.1. Para más información sobre OpenAPI, consulta la Especificación de OpenAPI.notaAWS SAM crea un escenario llamado
Stagede forma predeterminada. Si se establece esta propiedad en cualquier valor válido, se impedirá la creación de la etapaStage.Tipo: cadena
Obligatorio: no
CloudFormation compatibilidad: Esta propiedad es exclusiva de AWS SAM y no tiene un CloudFormation equivalente.
-
Indique si quiere pasar o no las etiquetas de la propiedad
Tagsa los recursos generados AWS::Serverless::Api. EspecificaTruepara propagar las etiquetas en los recursos generados.Tipo: Booleano
Obligatorio: no
Valor predeterminado:
FalseCloudFormation compatibilidad: Esta propiedad es exclusiva de AWS SAM y no tiene un CloudFormation equivalente.
Policy-
Documento de la política que contiene los permisos para la API. Para establecer el ARN de la política, utilice la función intrínseca
!Joincon""como delimitador y los valores"execute-api:/"y"*".Tipo: JSON
Obligatorio: no
CloudFormation compatibilidad: Esta propiedad se pasa directamente al Política propiedad de un
AWS::ApiGateway::RestApirecurso. -
SecurityPolicy -
La versión TLS más el conjunto de cifrado para la API REST. Cuando se utilizan políticas de seguridad mejoradas (aquellas con el prefijo:
SecurityPolicy>), también debe establecer elEndpointAccessMode.Tipo: cadena
Obligatorio: no
CloudFormation compatibilidad: Esta propiedad se pasa directamente al
SecurityPolicypropiedad de unAWS::ApiGateway::RestApirecurso. -
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 CloudFormation recursos generados cuando AWS::Serverless::Api se especifica. Para obtener información general sobre lo generado CloudFormation recursos, consulte Generado CloudFormation recursos para AWS SAM.<api-logical-id>.StageTipo: cadena
Obligatorio: sí
CloudFormation compatibilidad: Esta propiedad es similar a
StageNamepropiedad de unAWS::ApiGateway::Stagerecurso. 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
CloudFormation compatibilidad: Esta propiedad es similar a
Tagspropiedad de unAWS::ApiGateway::Stagerecurso. La propiedad Tags en SAM consiste en Key:Value pares; en CloudFormation consiste en una lista de objetos de etiqueta. -
TracingEnabled -
Indica si el rastreo está activo con X-Ray está activado para el escenario. Para obtener más información sobre X-Ray, consulte Rastrear las solicitudes de los usuarios a las API REST mediante X-Ray en el Guía para desarrolladores de API Gateway.
Tipo: Booleano
Obligatorio: no
CloudFormation compatibilidad: Esta propiedad se pasa directamente al
TracingEnabledpropiedad de unAWS::ApiGateway::Stagerecurso. -
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
CloudFormation compatibilidad: Esta propiedad se pasa directamente al
Variablespropiedad de unAWS::ApiGateway::Stagerecurso.
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 .
Diversión::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 Hola Mundo AWS SAM archivo de plantilla que contiene una función de eventos de Lambda con un punto final de API. Este es un archivo completo AWS SAM archivo de plantilla 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 AWS SAM fragmento 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 AWS SAM archivo de plantilla que muestra un AWS::Serverless::Api definició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
ApiCognitoAuthExample
Un AWS SAM fragmento de plantilla con una API que usa Amazon Cognito para autorizar solicitudes contra la API. Esto es solo una parte de un AWS SAM archivo de plantilla que muestra un AWS::Serverless::Api definición.
YAML
Resources: ApiGatewayApi: Type: AWS::Serverless::Api Properties: StageName: Prod Cors: "'*'" Auth: DefaultAuthorizer: MyCognitoAuthorizer Authorizers: MyCognitoAuthorizer: UserPoolArn: Fn::GetAtt: [MyCognitoUserPool, Arn]
ApiModelsExample
Un AWS SAM fragmento de plantilla con una API que incluye un esquema de modelos. Esto es solo una parte de un AWS SAM archivo de plantilla, que muestra un AWS::Serverless::Api definición con dos esquemas 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 Hola Mundo AWS SAM archivo de plantilla 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}
Ejemplo de dominio personalizado con una API privada
Un Hola Mundo AWS SAM archivo de plantilla que contiene una función Lambda con un punto final de API asignado a un dominio privado. La plantilla crea una asociación de acceso a un dominio entre un punto de conexión de VPC y un dominio privado. Para obtener más información, consulte Nombres de dominio personalizados para API privadas en API Gateway.
YAML
AWSTemplateFormatVersion: '2010-09-09' Transform: AWS::Serverless-2016-10-31 Description: AWS SAM template configured with a custom domain using a private API Parameters: DomainName: Type: String Default: mydomain.example.com CertificateArn: Type: String HostedZoneId: Type: String VpcEndpointId: Type: String VpcEndpointDomainName: Type: String VpcEndpointHostedZoneId: Type: String Resources: MyFunction: Type: AWS::Serverless::Function Properties: InlineCode: | def handler(event, context): return {'body': 'Hello World!', 'statusCode': 200} Handler: index.handler Runtime: python3.13 Events: Fetch: Type: Api Properties: RestApiId: Ref: MyApi Method: Get Path: /get MyApi: Type: AWS::Serverless::Api Properties: StageName: Prod EndpointConfiguration: Type: PRIVATE VPCEndpointIds: - !Ref VpcEndpointId Policy: Version: '2012-10-17' Statement: - Effect: Allow Principal: '*' Action: execute-api:Invoke Resource: execute-api:/* - Effect: Deny Principal: '*' Action: execute-api:Invoke Resource: execute-api:/* Condition: StringNotEquals: aws:SourceVpce: !Ref VpcEndpointId Domain: DomainName: !Ref DomainName CertificateArn: !Ref CertificateArn EndpointConfiguration: PRIVATE BasePath: - / Route53: HostedZoneId: !Ref HostedZoneId VpcEndpointDomainName: !Ref VpcEndpointDomainName VpcEndpointHostedZoneId: !Ref VpcEndpointHostedZoneId AccessAssociation: VpcEndpointId: !Ref VpcEndpointId Policy: Version: '2012-10-17' Statement: - Effect: Allow Principal: '*' Action: execute-api:Invoke Resource: execute-api:/* - Effect: Deny Principal: '*' Action: execute-api:Invoke Resource: execute-api:/* Condition: StringNotEquals: aws:SourceVpce: !Ref VpcEndpointId