AWS::Serverless::Api - AWS Serverless Application Model
SintaxisPropiedadesValores devueltosEjemplos

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 GitHub repositorio.

Para obtener más información sobre el uso de las políticas de IAM, consulte 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 AWS CloudFormation Recursos generados.

Sintaxis

Para declarar esta entidad en tu plantilla AWS Serverless Application Model (AWS SAM), usa la siguiente sintaxis.

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 un AWS::ApiGateway::Stage recurso.

AlwaysDeploy

Siempre implementa 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 y AUTHORIZER.

Tipo: cadena

Obligatorio: no

AWS CloudFormation compatibilidad: esta propiedad se pasa directamente a la ApiKeySourceType propiedad de un AWS::ApiGateway::RestApi recurso.

Auth

Configure 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.

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. Utilice esto para habilitar la compatibilidad con datos binarios para las API. 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 un AWS::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 para true bajo MethodSettings.

Tipo: Booleano

Obligatorio: no

AWS CloudFormation compatibilidad: esta propiedad se pasa directamente a la CacheClusterEnabled propiedad de un AWS::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 un AWS::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 un AWS::ApiGateway::Stage recurso.

Cors

Gestione el uso compartido de recursos entre orígenes (CORS) para todas sus API de API Gateway. Especifique el dominio que desea permitir como cadena o especifique 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 el para activar CORS.

Para obtener más información sobre CORS, consulte 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 ni DefinitionBody, SAM generará DefinitionBody para usted en función de la configuración de la plantilla.

Para hacer referencia a un archivo local de OpenAPI que defina su API, use la transformación AWS::Include. Para obtener más información, consulte Cargue archivos locales en el momento de la implementación.

Tipo: JSON

Obligatorio: no

AWS CloudFormation compatibilidad: esta propiedad es similar a la Body propiedad de un AWS::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 una EventSource del tipo Api para una AWS::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 ni DefinitionBody, 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 o sam 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 referenciaDefinitionUri. En su lugar, utilice la DefinitionBody 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 un AWS::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 un AWS::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 el https://{api_id}.execute-api.{region}.amazonaws.com predeterminado. Para exigir que los clientes utilicen un nombre de dominio personalizado para invocar su API, especifique True.

Tipo: Booleano

Obligatorio: no

AWS CloudFormation compatibilidad: esta propiedad es similar a la DisableExecuteApiEndpoint propiedad de un AWS::ApiGateway::RestApi recurso. Se pasa directamente a la propiedad disableExecuteApiEndpoint de una extensión x-amazon-apigateway-endpoint-configuration, que se agrega a la propiedad Body de un recurso AWS::ApiGateway::RestApi.

Domain

Configura un dominio personalizado para esta API de API Gateway.

Tipo: DomainConfiguration

Obligatorio: no

AWS CloudFormation compatibilidad: esta propiedad es exclusiva de 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 un AWS::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 es false.

Tipo: Booleano

Obligatorio: no

AWS CloudFormation compatibilidad: esta propiedad se pasa directamente a la FailOnWarnings propiedad de un AWS::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 una OpenAPI especificación a partir de la fuente de eventos de la API. Especifique true si desea AWS SAM fusionarla con la OpenAPI especificación en línea definida en su AWS::Serverless::Api recurso. Especifique que false no se fusione.

MergeDefinitions requiere que la propiedad de DefinitionBody para AWS::Serverless::Api se defina. MergeDefinitions no es compatible con la propiedad de DefinitionUri para AWS::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 un AWS::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 identity.

Tipo: entero

Obligatorio: no

AWS CloudFormation compatibilidad: esta propiedad se pasa directamente a la MinimumCompressionSize propiedad de un AWS::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 Modo en el tipo de recurso AWS::ApiGateway::RestApi.

Valores válidos: overwrite o merge

Tipo: cadena

Obligatorio: no

AWS CloudFormation compatibilidad: esta propiedad se pasa directamente a la Mode propiedad de un AWS::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 un AWS::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, consulte 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 etapa Stage.

Tipo: cadena

Obligatorio: no

AWS CloudFormation compatibilidad: esta propiedad es exclusiva AWS SAM y no tiene un AWS CloudFormation equivalente.

PropagateTags

Indique si quiere pasar o no las etiquetas de la propiedad Tags a los recursos generados AWS::Serverless::Api. Especifique True 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 <api-logical-id>.Stage. Para obtener más información sobre cómo hacer referencia a los recursos generados cuando se especifica un recurso AWS::Serverless::Api, consulte AWS CloudFormation recursos generados cuando AWS::Serverless::Api se especifica. Para obtener información general sobre AWS CloudFormation los recursos generados, consulteAWS CloudFormation Recursos generados.

Tipo: cadena

Obligatorio: sí

AWS CloudFormation compatibilidad: esta propiedad es similar a la StageName propiedad de un AWS::ApiGateway::Stage recurso. Es obligatorio en SAM, pero no en API Gateway

Notas adicionales: la API implícita tiene el nombre de etapa de “Prod”.

Tags

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, consulte 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 un AWS::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 más información acerca de X-Ray, consulte Rastreo de solicitudes de usuario a API de REST 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 un AWS::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 un AWS::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, consulte 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, consulte Fn::GetAtt en la Guía del usuario de AWS CloudFormation .

RootResourceId

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

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é, consulte 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}