AWS::Serverless::Api - AWS Serverless Application Model
SintassiProprietàValori restituitiEsempi

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

AWS::Serverless::Api

Crea una raccolta di risorse e metodi Amazon API Gateway che possono essere richiamati tramite endpoint HTTPS.

Non è necessario aggiungere esplicitamente una AWS::Serverless::Api risorsa a un modello AWS Serverless Application Definition. Una risorsa di questo tipo viene creata implicitamente dall'unione di eventi Api definiti su AWS::Serverless::Function risorse definite nel modello che non fanno riferimento a una risorsa. AWS::Serverless::Api

È necessario utilizzare una AWS::Serverless::Api risorsa per definire e documentare l'utilizzo dell'API OpenApi, che offre una maggiore capacità di configurazione delle risorse Amazon API Gateway sottostanti.

Ti consigliamo di utilizzare CloudFormation hook o policy IAM per verificare che alle risorse API Gateway siano associate autorizzazioni per controllarne l'accesso.

Per ulteriori informazioni sull'uso degli CloudFormation hook, consulta Registrazione degli hook nella guida per l'utente della CloudFormation CLI e nel repository. apigw-enforce-authorizer GitHub

Per ulteriori informazioni sull'utilizzo delle policy IAM, consulta Require che le route API abbiano l'autorizzazione nella API Gateway Developer Guide.

Nota

Quando esegui la distribuzione a AWS CloudFormation, AWS SAM trasforma le tue AWS SAM risorse in CloudFormation risorse. Per ulteriori informazioni, consulta CloudFormation Risorse generate per AWS SAM.

Sintassi

Per dichiarare questa entità nel tuo modello AWS Serverless Application Model (AWS SAM), usa la seguente sintassi.

Proprietà

AccessLogSetting

Configura l'impostazione del registro di accesso per uno stage.

Tipo: AccessLogSetting

Required: No

CloudFormation compatibilità: questa proprietà viene passata direttamente alla AccessLogSetting proprietà di una AWS::ApiGateway::Stage risorsa.

AlwaysDeploy

Implementa sempre l'API, anche quando non sono state rilevate modifiche all'API.

Tipo: Booleano

Required: No

CloudFormation compatibilità: questa proprietà è unica AWS SAM e non ha un CloudFormation equivalente.

ApiKeySourceType

L'origine della chiave API per le richieste di misurazione in base a un piano di utilizzo. I valori validi sono HEADER e AUTHORIZER.

▬Tipo: stringa

Required: No

CloudFormation compatibilità: questa proprietà viene passata direttamente alla ApiKeySourceType proprietà di una AWS::ApiGateway::RestApi risorsa.

Auth

Configura l'autorizzazione per controllare l'accesso alla tua API API Gateway.

Per ulteriori informazioni sulla configurazione dell'accesso tramite, AWS SAM vedereControlla l'accesso alle API con il tuo AWS SAM modello. Per un esempio che mostra come sovrascrivere un autorizzatore globale, vedi. Sostituisci un autorizzatore globale per la tua API REST di Amazon API Gateway

Tipo: ApiAuth

Required: No

CloudFormation compatibilità: questa proprietà è unica AWS SAM e non ha un CloudFormation equivalente.

BinaryMediaTypes

Elenco dei tipi MIME che l'API potrebbe restituire. Usalo per abilitare il supporto binario perAPIs.

Tipo: Elenco

Required: No

CloudFormation compatibilità: questa proprietà è simile alla BinaryMediaTypes proprietà di una AWS::ApiGateway::RestApi risorsa. L'elenco di BinaryMediaTypes viene aggiunto sia alla CloudFormation risorsa che al documento OpenAPI.

CacheClusterEnabled

Indica se la memorizzazione nella cache è abilitata per lo stage. Per memorizzare nella cache le risposte, è inoltre necessario CachingEnabled impostare su true underMethodSettings.

Tipo: Booleano

Required: No

CloudFormation compatibilità: questa proprietà viene passata direttamente alla CacheClusterEnabled proprietà di una AWS::ApiGateway::Stage risorsa.

CacheClusterSize

Le dimensioni del cluster di cache della fase.

▬Tipo: stringa

Required: No

CloudFormation compatibilità: questa proprietà viene passata direttamente alla CacheClusterSize proprietà di una AWS::ApiGateway::Stage risorsa.

CanarySetting

Configura un'impostazione Canary in una fase di distribuzione regolare.

Tipo: CanarySetting

Required: No

CloudFormation compatibilità: questa proprietà viene passata direttamente alla CanarySetting proprietà di una AWS::ApiGateway::Stage risorsa.

Cors

Gestisci la condivisione delle risorse tra le origini (CORS) per tutti i tuoi API Gateway. APIs Specificate il dominio da consentire come stringa o specificate un dizionario con una configurazione Cors aggiuntiva.

Nota

CORS richiede AWS SAM di modificare la definizione OpenAPI. Crea una definizione OpenAPI in linea per attivare DefinitionBody CORS.

Per ulteriori informazioni su CORS, consulta Enable CORS for an API Gateway REST API Resource nella API Gateway Developer Guide.

Tipo: Stringa | CorsConfiguration

Required: No

CloudFormation compatibilità: Questa proprietà è unica AWS SAM e non ha un CloudFormation equivalente.

DefinitionBody

Specificazione OpenAPI che descrive la tua API. Se DefinitionUri nessuna delle due DefinitionBody viene specificata, SAM genererà una DefinitionBody per te in base alla configurazione del modello.

Per fare riferimento a un OpenAPI file locale che definisce la tua API, usa la AWS::Include trasformazione. Per ulteriori informazioni, consulta Come AWS SAM carica i file locali.

Type: JSON

Required: No

CloudFormation compatibilità: questa proprietà è simile alla Body proprietà di una AWS::ApiGateway::RestApi risorsa. Se vengono fornite determinate proprietà, il contenuto può essere inserito o modificato nella DefinitionBody prima di essere passato a CloudFormation. Le proprietà includono AuthBinaryMediaTypes,Cors,GatewayResponses,Models, e una EventSource di tipo Api per una corrispondenteAWS::Serverless::Function.

DefinitionUri

Uri Amazon S3, percorso del file locale o oggetto posizione del documento OpenAPI che definisce l'API. L'oggetto Amazon S3 a cui fa riferimento questa proprietà deve essere un file OpenAPI valido. Se non viene specificato DefinitionUri nessuno DefinitionBody dei due, SAM genererà un file DefinitionBody per te in base alla configurazione del modello.

Se viene fornito un percorso di file locale, il modello deve passare attraverso il flusso di lavoro che include il sam package comando sam deploy o, affinché la definizione venga trasformata correttamente.

Le funzioni intrinseche non sono supportate nei OpenApi file esterni a cui fa riferimento. DefinitionUri Utilizzate invece la DefinitionBody proprietà con Include Transform per importare una OpenApi definizione nel modello.

Tipo: String | ApiDefinition

Required: No

CloudFormation compatibilità: Questa proprietà è simile alla BodyS3Location proprietà di una AWS::ApiGateway::RestApi risorsa. Le proprietà annidate di Amazon S3 sono denominate in modo diverso.

Description

Una descrizione della risorsa Api.

▬Tipo: stringa

Required: No

CloudFormation compatibilità: questa proprietà viene passata direttamente alla Description proprietà di una AWS::ApiGateway::RestApi risorsa.

DisableExecuteApiEndpoint

Specifica se i client possono richiamare l'API utilizzando l'endpoint execute-api predefinito. Per impostazione predefinita, i client possono richiamare la tua API con l'impostazione predefinitahttps://{api_id}.execute-api.{region}.amazonaws.com. Per richiedere che i client utilizzino un nome di dominio personalizzato per richiamare l'API, specifica True.

Tipo: Booleano

Required: No

CloudFormation compatibilità: questa proprietà è simile alla DisableExecuteApiEndpoint proprietà di una AWS::ApiGateway::RestApi risorsa. Viene passato direttamente alla disableExecuteApiEndpoint proprietà di un' x-amazon-apigateway-endpoint-configurationestensione, che viene aggiunta alla Body proprietà di una AWS::ApiGateway::RestApi risorsa.

Domain

Configura un dominio personalizzato per questa API API Gateway.

Tipo: DomainConfiguration

Required: No

CloudFormation compatibilità: questa proprietà è unica AWS SAM e non ha un CloudFormation equivalente.

EndpointConfiguration

Il tipo di endpoint di un'API REST.

Tipo: EndpointConfiguration

Required: No

CloudFormation compatibilità: questa proprietà è simile alla EndpointConfiguration proprietà di una AWS::ApiGateway::RestApi risorsa. Le proprietà di configurazione annidate sono denominate in modo diverso.

FailOnWarnings

Speciifica se ripristinare la creazione dell'API (true) o meno (false) quando viene rilevato un avviso. Il valore predefinito è false.

Tipo: Booleano

Required: No

CloudFormation compatibilità: questa proprietà viene passata direttamente alla FailOnWarnings proprietà di una AWS::ApiGateway::RestApi risorsa.

GatewayResponses

Configura Gateway Responses per un'API. Le risposte Gateway sono risposte restituite da API Gateway, direttamente o tramite l'uso di Lambda Authorizers. Per ulteriori informazioni, consulta la documentazione dell' OpenApi estensione Api Gateway per Gateway Responses.

Tipo: Mappa

Required: No

CloudFormation compatibilità: questa proprietà è unica AWS SAM e non ha un CloudFormation equivalente.

MergeDefinitions

AWS SAM genera una OpenAPI specifica dalla fonte dell'evento API. trueSpecificate di AWS SAM unirlo alla OpenAPI specifica in linea definita nella vostra AWS::Serverless::Api risorsa. falseSpecificare di non unire.

MergeDefinitionsrichiede la definizione della DefinitionBody proprietà AWS::Serverless::Api per. MergeDefinitionsnon è compatibile con la DefinitionUri proprietà diAWS::Serverless::Api.

Valore predefinito: false

Tipo: Booleano

Required: No

CloudFormation compatibilità: questa proprietà è unica AWS SAM e non ha un CloudFormation equivalente.

MethodSettings

Configura tutte le impostazioni per API Stage, tra cui Logging, Metrics, CacheTTL, Throttling.

Tipo: elenco di MethodSetting

Required: No

CloudFormation compatibilità: questa proprietà viene passata direttamente alla proprietà di una risorsa. MethodSettings AWS::ApiGateway::Stage

MinimumCompressionSize

Consenti la compressione dei corpi di risposta in base all'intestazione Accept-Encoding del client. La compressione viene attivata quando la dimensione del corpo di risposta è maggiore o uguale alla soglia configurata. La soglia di dimensione corporea massima è 10 MB (10.485.760 byte). - Sono supportati i seguenti tipi di compressione: gzip, deflate e identity.

Tipo: integer

Required: No

CloudFormation compatibilità: questa proprietà viene passata direttamente alla MinimumCompressionSize proprietà di una risorsa. AWS::ApiGateway::RestApi

Mode

Questa proprietà si applica solo quando si utilizza OpenAPI per definire l'API REST. Mode determina il modo in cui Gateway API gestisce gli aggiornamenti delle risorse. Per ulteriori informazioni, vedere la proprietà Mode del tipo di AWS::ApiGateway::RestApirisorsa.

Valori validi: overwrite o merge

▬Tipo: stringa

Required: No

CloudFormation compatibilità: questa proprietà viene passata direttamente alla Mode proprietà di una AWS::ApiGateway::RestApi risorsa.

Models

Gli schemi che devono essere utilizzati dai metodi API. Questi schemi possono essere descritti utilizzando JSON o YAML. Vedi la sezione Esempi in fondo a questa pagina per esempi di modelli.

Tipo: Mappa

Required: No

CloudFormation compatibilità: questa proprietà è unica AWS SAM e non ha un CloudFormation equivalente.

Name

Un nome per la RestApi risorsa API Gateway

▬Tipo: stringa

Required: No

CloudFormation compatibilità: questa proprietà viene passata direttamente alla Name proprietà di una AWS::ApiGateway::RestApi risorsa.

OpenApiVersion

Versione di OpenApi da usare. Questo può riguardare 2.0 la specifica Swagger o una delle versioni OpenApi 3.0, ad esempio. 3.0.1 Per ulteriori informazioni su OpenAPI, vedere la specifica OpenAPI.

Nota

AWS SAM crea una fase chiamata di Stage default. L'impostazione di questa proprietà su qualsiasi valore valido impedirà la creazione dello stageStage.

▬Tipo: stringa

Required: No

CloudFormation compatibilità: questa proprietà è unica AWS SAM e non ha un CloudFormation equivalente.

PropagateTags

Indica se passare o meno i tag dalla Tags proprietà alle risorse AWS::Serverless::Api generate. TrueSpecificate di propagare i tag nelle risorse generate.

Tipo: Booleano

Required: No

Default: False

CloudFormation compatibilità: questa proprietà è unica AWS SAM e non ha un CloudFormation equivalente.

Policy

Un documento di policy che contiene le autorizzazioni per l'API. Per impostare l'ARN per la policy, utilizza la funzione intrinseca !Join con "" come delimitatore e valori di "execute-api:/" e "*".

Type: JSON

Required: No

CloudFormation compatibilità: questa proprietà viene passata direttamente alla proprietà Policy di una AWS::ApiGateway::RestApi risorsa.

StageName

Il nome della fase, che API Gateway utilizza come primo segmento di percorso nell'URI (Uniform Resource Identifier) di invoke.

Per fare riferimento alla risorsa dello stage, usa. <api-logical-id>.Stage Per ulteriori informazioni sul riferimento alle risorse generate quando viene specificata una AWS::Serverless::Api risorsa, vedereCloudFormation risorse generate quando AWS::Serverless::Api è specificato. Per informazioni generali sulle CloudFormation risorse generate, vedereCloudFormation Risorse generate per AWS SAM.

▬Tipo: stringa

Campo obbligatorio: sì

CloudFormation compatibilità: questa proprietà è simile alla StageName proprietà di una AWS::ApiGateway::Stage risorsa. È richiesto in SAM, ma non richiesto in API Gateway

Note aggiuntive: L'API Implicit ha il nome d'arte «Prod».

Tags

Una mappa (da stringa a stringa) che specifica i tag da aggiungere a questa fase di API Gateway. Per informazioni dettagliate sulle chiavi e i valori validi per i tag, consulta Resource tag nella Guida per l'AWS CloudFormation utente.

Tipo: Mappa

Required: No

CloudFormation compatibilità: questa proprietà è simile alla Tags proprietà di una AWS::ApiGateway::Stage risorsa. La proprietà Tags in SAM è costituita da coppie Key:Value; in CloudFormation essa è costituita da un elenco di oggetti Tag.

TracingEnabled

Indica se il tracciamento attivo con X-Ray è abilitato per lo stage. Per ulteriori informazioni su X-Ray, consulta Tracciare le richieste degli utenti su REST usando APIs X-Ray nella API Gateway Developer Guide.

Tipo: Booleano

Required: No

CloudFormation compatibilità: questa proprietà viene passata direttamente alla TracingEnabled proprietà di una risorsa. AWS::ApiGateway::Stage

Variables

Una mappa (da stringa a stringa) che definisce le variabili dello stage, dove il nome della variabile è la chiave e il valore della variabile è il valore. I nomi della variabile sono limitati ai caratteri alfanumerici. I valori devono corrispondere alla seguente espressione regolare: [A-Za-z0-9._~:/?#&=,-]+.

Tipo: Mappa

Required: No

CloudFormation compatibilità: questa proprietà viene passata direttamente alla Variables proprietà di una AWS::ApiGateway::Stage risorsa.

Valori restituiti

Ref

Quando l'ID logico di questa risorsa viene fornito alla funzione Ref intrinseca, restituisce l'ID dell'API Gateway API sottostante.

Per ulteriori informazioni sull'utilizzo della Ref funzione, consulta Refla Guida per l'AWS CloudFormation utente.

Fn:: GetAtt

Fn::GetAtt restituisce un valore per un attributo specificato di questo tipo. Di seguito sono riportati gli attributi disponibili e i valori restituiti di esempio.

Per ulteriori informazioni sull'utilizzoFn::GetAtt, consulta Fn::GetAttla Guida per l'AWS CloudFormation utente.

RootResourceId

L'ID della risorsa root per una risorsa RestApi, ad esempio a0bc123d4e.

Esempi

SimpleApiExample

Un file AWS SAM modello Hello World che contiene una funzione Lambda con un endpoint API. Si tratta di un file AWS SAM modello completo per un'applicazione serverless funzionante.

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 frammento di AWS SAM modello con un'API definita in un file Swagger esterno insieme a integrazioni Lambda e configurazioni CORS. Questa è solo una parte di un file modello che mostra una definizione. 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 frammento di AWS SAM modello con un'API che utilizza Amazon Cognito per autorizzare le richieste contro l'API. Questa è solo una parte di un file AWS SAM modello che mostra una definizione. 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 frammento di AWS SAM modello con un'API che include uno schema Models. Questa è solo una parte di un file AWS SAM modello, che mostra una AWS::Serverless::Api definizione con due schemi di modello.

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

Esempio di caching

Un file AWS SAM modello Hello World che contiene una funzione Lambda con un endpoint API. L'API ha la memorizzazione nella cache abilitata per una risorsa e un metodo. Per ulteriori informazioni sulla memorizzazione nella cache, consulta Enabling API caching to enhance responsiveness nella API Gateway Developer Guide.

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}

Dominio personalizzato con un esempio di API privata

Un file AWS SAM modello Hello World che contiene una funzione Lambda con un endpoint API mappato su un dominio privato. Il modello crea un'associazione di accesso al dominio tra un endpoint VPC e il dominio privato. Per ulteriori informazioni, consulta Nomi di dominio personalizzati per uso privato APIs in 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