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 explícitamente un recurso de AWS::Serverless::Api a una plantilla de definición de aplicación sin servidor de AWS. 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 usar un recurso AWS::Serverless::Api para definir y documentar la API mediante OpenAPI, que proporciona más capacidad para configurar los recursos subyacentes de Amazon API Gateway.

Te recomendamos que utilices enlaces de CloudFormation 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 enlaces CloudFormation, consulta Registrar enlaces en la Guía del usuario de CLI de CloudFormation y en el repositorio de GitHub apigw-enforce-autorizarr.

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 sus recursos de AWS SAM en recursos de CloudFormation. Para obtener más información, consulta Recursos de CloudFormation generados para AWS SAM.

Sintaxis

Para declarar esta entidad en su plantilla de 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

Compatibilidad con CloudFormation: esta propiedad se transfiere directamente a la propiedad AccessLogSetting de un recurso AWS::ApiGateway::Stage.

AlwaysDeploy

Siempre implementas la API, incluso cuando no se han detectado cambios en la API.

Tipo: Booleano

Obligatorio: no

Compatibilidad con CloudFormation: esta propiedad es exclusiva de AWS SAM y no tiene un equivalente CloudFormation.

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

Compatibilidad con CloudFormation: esta propiedad se transfiere directamente a la propiedad ApiKeySourceType de un recurso AWS::ApiGateway::RestApi.

Auth

Configure 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, consulta Control del acceso a la API con la plantilla de AWS SAM. 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

Compatibilidad con CloudFormation: esta propiedad es exclusiva de AWS SAM y no tiene un equivalente CloudFormation.

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

Compatibilidad con CloudFormation: esta propiedad es similar a la propiedad BinaryMediaTypes de un recurso AWS::ApiGateway::RestApi. La lista de BinaryMediatypes se añade tanto al recurso de CloudFormation como al documento 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

Compatibilidad con CloudFormation: esta propiedad se transfiere directamente a la propiedad CacheClusterEnabled de un recurso AWS::ApiGateway::Stage.

CacheClusterSize

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

Tipo: cadena

Obligatorio: no

Compatibilidad con CloudFormation: esta propiedad se transfiere directamente a la propiedad CacheClusterSize de un recurso AWS::ApiGateway::Stage.

CanarySetting

Configure una prueba canario como una etapa de una implementación normal.

Type: CanarySetting

Obligatorio: no

Compatibilidad con CloudFormation: esta propiedad se transfiere directamente a la propiedad CanarySetting de un recurso AWS::ApiGateway::Stage.

Cors

Gestione el uso compartido de recursos entre orígenes (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.

nota

CORS obliga a AWS SAM a modificar su 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

Compatibilidad con CloudFormation: esta propiedad es exclusiva de AWS SAM y no tiene un equivalente CloudFormation.

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, usa la transformación AWS::Include. Para obtener más información, consulta Cómo AWS SAM carga archivos locales.

Tipo: JSON

Obligatorio: no

Compatibilidad con CloudFormation: esta propiedad es similar a la propiedad Body de un recurso AWS::ApiGateway::RestApi. Si se proporcionan determinadas propiedades, el contenido se puede insertar o modificar en el DefinitionBody antes de pasarlo a 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 son compatibles con los archivos OpenAPI externos a los que hace referencia DefinitionUri. En su lugar, utilice la propiedad DefinitionBody con la transformación Include para importar una definición de OpenAPI a la plantilla.

Tipo: cadena | ApiDefinition

Obligatorio: no

Compatibilidad con CloudFormation: esta propiedad es similar a la propiedad BodyS3Location de un recurso AWS::ApiGateway::RestApi. Las propiedades anidadas de Amazon S3 tienen un nombre diferente.

Description

Una descripción del recurso de la Api.

Tipo: cadena

Obligatorio: no

Compatibilidad con CloudFormation: esta propiedad se transfiere directamente a la propiedad Description de un recurso AWS::ApiGateway::RestApi.

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, especifica True.

Tipo: Booleano

Obligatorio: no

Compatibilidad con CloudFormation: esta propiedad es similar a la propiedad DisableExecuteApiEndpoint de un recurso AWS::ApiGateway::RestApi. 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

Compatibilidad con CloudFormation: esta propiedad es exclusiva de AWS SAM y no tiene un equivalente CloudFormation.

EndpointConfiguration

El tipo de punto de conexión de una API de REST.

Tipo: EndpointConfiguration

Obligatorio: no

Compatibilidad con CloudFormation: esta propiedad es similar a la propiedad EndpointConfiguration de un recurso AWS::ApiGateway::RestApi. 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

Compatibilidad con CloudFormation: esta propiedad se transfiere directamente a la propiedad FailOnWarnings de un recurso AWS::ApiGateway::RestApi.

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 más información, consulta la documentación de la extensión OpenAPI de Api Gateway para Respuestas de Gateway.

Tipo: Mapa

Obligatorio: no

Compatibilidad con CloudFormation: esta propiedad es exclusiva de AWS SAM y no tiene un equivalente CloudFormation.

MergeDefinitions

AWS SAM genera una especificación de OpenAPI a partir del origen de eventos de la API. Especifica true si quieres fusionar AWS SAM con la especificación OpenAPI inline definida en su recurso de AWS::Serverless::Api. Especifica 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

Compatibilidad con CloudFormation: esta propiedad es exclusiva de AWS SAM y no tiene un equivalente CloudFormation.

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

Compatibilidad con CloudFormation: esta propiedad se transfiere directamente a la propiedad MethodSettings de un recurso AWS::ApiGateway::Stage.

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

Compatibilidad con CloudFormation: esta propiedad se transfiere directamente a la propiedad MinimumCompressionSize de un recurso AWS::ApiGateway::RestApi.

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, consulta la propiedad Modo en el tipo de recurso AWS::ApiGateway::RestApi.

Valores válidos: overwrite o merge

Tipo: cadena

Obligatorio: no

Compatibilidad con CloudFormation: esta propiedad se transfiere directamente a la propiedad Mode de un recurso AWS::ApiGateway::RestApi.

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

Compatibilidad con CloudFormation: esta propiedad es exclusiva de AWS SAM y no tiene un equivalente CloudFormation.

Name

Un nombre para el recurso RestAPI de API Gateway

Tipo: cadena

Obligatorio: no

Compatibilidad con CloudFormation: esta propiedad se transfiere directamente a la propiedad Name de un recurso AWS::ApiGateway::RestApi.

OpenApiVersion

La versión de OpenApi que se va a usar. Esto puede ser 2.0 para la especificación Swagger o para una de las versiones de 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 una etapa llamada 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

Compatibilidad con CloudFormation: esta propiedad es exclusiva de AWS SAM y no tiene un equivalente CloudFormation.

PropagateTags

Indique si quiere pasar o no las etiquetas de la propiedad Tags a los recursos generados AWS::Serverless::Api. Especifica True para propagar las etiquetas en los recursos generados.

Tipo: Booleano

Obligatorio: no

Valor predeterminado: False

Compatibilidad con CloudFormation: esta propiedad es exclusiva de AWS SAM y no tiene un equivalente CloudFormation.

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 !Join con "" como delimitador y los valores "execute-api:/" y "*".

Tipo: JSON

Obligatorio: no

Compatibilidad con CloudFormation: esta propiedad se transfiere directamente a la propiedad de la política de un recurso de AWS::ApiGateway::RestApi.

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, consulta Recursos de CloudFormation generados cuando se especifica AWS::Serverless::Api. Para obtener información general sobre los recursos generados de CloudFormation, consulta Recursos de CloudFormation generados para AWS SAM.

Tipo: cadena

Obligatorio: sí

Compatibilidad con CloudFormation: esta propiedad es similar a la propiedad StageName de un recurso AWS::ApiGateway::Stage. 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, consulta la etiqueta de recursos en la Guía del usuario de AWS CloudFormation.

Tipo: mapa

Obligatorio: no

Compatibilidad con CloudFormation: esta propiedad es similar a la propiedad Tags de un recurso AWS::ApiGateway::Stage. La propiedad de etiquetas en SAM consta de pares Clave:Valor; en CloudFormation, consta de una lista de objetos de etiquetas.

TracingEnabled

Indica si se ha habilitado el rastreo activo con X-Ray para la fase. Para más información acerca de X-Ray, consulta 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

Compatibilidad con CloudFormation: esta propiedad se transfiere directamente a la propiedad TracingEnabled de un recurso AWS::ApiGateway::Stage.

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

Compatibilidad con CloudFormation: esta propiedad se transfiere directamente a la propiedad Variables de un recurso AWS::ApiGateway::Stage.

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.

Fn::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 ejemplo a0bc123d4e.

Ejemplos

SimpleApiExample

Un archivo de plantillas Hello World de AWS SAM que contiene una función de Lambda con un punto de conexión de API. Se trata de un archivo de plantillas de AWS SAM completo 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 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 de plantilla de AWS SAM con una API definida en un archivo Swagger externo junto con integraciones de Lambda y configuraciones de CORS. Esta es solo una parte de un archivo de plantilla de AWS SAM que muestra una definición 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 de plantilla de AWS SAM con una API que utiliza Amazon Cognito para autorizar las solicitudes frente a la API. Esta es solo una parte de un archivo de plantilla de AWS SAM 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 de plantilla de AWS SAM con una API que incluye un esquema de Modelos. Esta es solo una parte de un archivo de plantilla de AWS SAM que muestra una definición AWS::Serverless::Api 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 archivo de plantillas Hello World de AWS SAM que contiene una función de Lambda con un punto de conexión 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 archivo de plantillas Hello World de AWS SAM que contiene una función de Lambda con un punto de conexión 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