Sintassi Proprietà Valori restituiti Esempi

AWS::Serverless::Api

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

Non è necessario aggiungere esplicitamente unaAWS::Serverless::Api risorsa a un modello di definizione di applicazioneAWS serverless. Una risorsa di questo tipo viene creata implicitamente dall'unione di eventi Api definiti suAWS::Serverless::Function risorse definite nel modello che non fanno riferimento a unaAWS::Serverless::Api risorsa.

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

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

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

Per ulteriori informazioni sull'utilizzo delle policy IAM, consulta Richiedere l'autorizzazione dei percorsi API nella API Gateway Developer Guide.

Sintassi

Per dichiarare questa entità nel modelloAWS Serverless Application Model (AWS SAM), utilizzare la sintassi seguente.

YAML


Type: AWS::Serverless::Api
Properties:
  AccessLogSetting: AccessLogSetting
  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
  MethodSettings: MethodSettings
  MinimumCompressionSize: Integer
  Mode: String
  Models: Map
  Name: String
  OpenApiVersion: String
  StageName: String
  Tags: Map
  TracingEnabled: Boolean
  Variables: Map

Proprietà

AccessLogSetting

Configura le impostazioni del registro degli accessi per una fase.

Tipo: AccessLogSetting

Required: No

AWS CloudFormationcompatibilità: questa proprietà viene passata direttamente allaAccessLogSetting proprietà di unaAWS::ApiGateway::Stage risorsa.

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

AWS CloudFormationcompatibilità: questa proprietà viene passata direttamente allaApiKeySourceType proprietà di unaAWS::ApiGateway::RestApi risorsa.

Auth

Configura l'autorizzazione per controllare l'accesso all'API Gateway API.

Per ulteriori informazioni sulla configurazione dell'accesso utilizzando,AWS SAM vedereControllare l'accesso alle API Gateway API.

Tipo: ApiAuth

Required: No

AWS CloudFormationcompatibilità: questa proprietà è unicaAWS SAM e non ha unAWS CloudFormation equivalente.

BinaryMediaTypes

Elenco dei tipi MIME che l'API potrebbe restituire. Utilizzalo per abilitare il supporto binario per le API. Usa ~1 invece di/nei tipi MIME.

Tipo: Elenco

Required: No

AWS CloudFormationcompatibilità: questa proprietà è simile allaBinaryMediaTypes proprietà di unaAWS::ApiGateway::RestApi risorsa. L'elenco di BinaryMediaTypes viene aggiunto sia allaAWS CloudFormation risorsa che al documento OpenAPI.

CacheClusterEnabled

Indica se la creazione di cache è abilitata per la fase. Per memorizzare nella cache le risposte, è necessarioCachingEnabled impostare anche sutrue underMethodSettings.

Tipo: Booleano

Required: No

AWS CloudFormationcompatibilità: questa proprietà viene passata direttamente allaCacheClusterEnabled proprietà di unaAWS::ApiGateway::Stage risorsa.

CacheClusterSize

Le dimensioni del cluster di cache della fase.

Tipo: stringa

Required: No

AWS CloudFormationcompatibilità: questa proprietà viene passata direttamente allaCacheClusterSize proprietà di unaAWS::ApiGateway::Stage risorsa.

CanarySetting

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

Tipo: CanarySetting

Required: No

AWS CloudFormationcompatibilità: questa proprietà viene passata direttamente allaCanarySetting proprietà di unaAWS::ApiGateway::Stage risorsa.

Cors

Gestire la Cross-Origin Resource Sharing (CORS) per tutte le API API Gateway. Specifica il dominio da consentire come stringa o specifica un dizionario con una configurazione Cors aggiuntiva. NOTA: CORS richiedeAWS SAM di modificare la definizione di OpenAPI. Quindi, funziona solo se inline OpenApi è definito con DefinitionBody.

Per ulteriori informazioni su CORS, vedi Abilitare CORS per una risorsa API REST API Gateway nella API Gateway Developer Guide.

Tipo: String | CorsConfiguration

Required: No

AWS CloudFormationcompatibilità: questa proprietà è unicaAWS SAM e non ha unAWS CloudFormation equivalente.

DefinitionBody

Specifica OpenAPI che descrive la tua API. Se nonDefinitionBody viene specificatoDefinitionUri né l'uno né l'altro, SAM genererà un fileDefinitionBody per te in base alla configurazione del modello.

Type: JSON

Required: No

AWS CloudFormationcompatibilità: questa proprietà è simile allaBody proprietà di unaAWS::ApiGateway::RestApi risorsa. Se vengono fornite determinate proprietà, il contenuto può essere inserito o modificato nel file DefinitionBody prima di essere passato CloudFormation. Le proprietà includonoAuthBinaryMediaTypesCors,GatewayResponses,Models, e un ApiEventSource di tipo corrispondenteAWS::Serverless::Function.

DefinitionUri

Amazon S3 Uri, percorso del file locale o oggetto di posizione del documento OpenAPI che definisce l'API. L'oggetto Amazon S3 a cui questa proprietà fa riferimento deve essere un file OpenAPI valido. Se nonDefinitionBody viene specificatoDefinitionUri né l'uno né l'altro, SAM genererà un fileDefinitionBody 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 ilsam package comandosam deploy or, affinché la definizione venga trasformata correttamente.

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

Tipo: String | ApiDefinition

Required: No

AWS CloudFormationcompatibilità: questa proprietà è simile allaBodyS3Location proprietà di unaAWS::ApiGateway::RestApi risorsa. Le proprietà annidate di Amazon S3 hanno un nome diverso.

Description

Una descrizione della risorsa Api.

Tipo: stringa

Required: No

AWS CloudFormationcompatibilità: questa proprietà viene passata direttamente allaDescription proprietà di unaAWS::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 l'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

AWS CloudFormationcompatibilità: questa proprietà è simile allaDisableExecuteApiEndpoint proprietà di unaAWS::ApiGateway::RestApi risorsa. Viene passato direttamente alla disableExecuteApiEndpointproprietà di un'x-amazon-apigateway-endpoint-configurationestensione, che viene aggiunta allaBody proprietà di unaAWS::ApiGateway::RestApi risorsa.

Domain

Configura un dominio personalizzato per questa API API Gateway.

Tipo: DomainConfiguration

Required: No

AWS CloudFormationcompatibilità: questa proprietà è unicaAWS SAM e non ha unAWS CloudFormation equivalente.

EndpointConfiguration

Il tipo di endpoint di un'API REST.

Tipo: EndpointConfiguration

Required: No

AWS CloudFormationcompatibilità: questa proprietà è simile allaEndpointConfiguration proprietà di unaAWS::ApiGateway::RestApi risorsa. Le proprietà di configurazione annidate hanno un nome diverso.

FailOnWarnings

Specificare se eseguire il rollback della creazione API (true) o meno (false) quando viene rilevato un avviso. Il valore di default è false.

Tipo: Booleano

Required: No

AWS CloudFormationcompatibilità: questa proprietà viene passata direttamente allaFailOnWarnings proprietà di unaAWS::ApiGateway::RestApi risorsa.

GatewayResponses

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

Tipo: Mappa

Required: No

AWS CloudFormationcompatibilità: questa proprietà è unicaAWS SAM e non ha unAWS CloudFormation equivalente.

MethodSettings

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

Tipo: Elenco di MethodSetting

Required: No

AWS CloudFormationcompatibilità: questa proprietà viene passata direttamente allaMethodSettings proprietà di unaAWS::ApiGateway::Stage risorsa.

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 massima di dimensione corporea è 10 MB (10.485.760 byte). - Sono supportati i seguenti tipi di compressione: gzip, deflate e identity.

Tipo: integer

Required: No

AWS CloudFormationcompatibilità: questa proprietà viene passata direttamente allaMinimumCompressionSize proprietà di unaAWS::ApiGateway::RestApi risorsa.

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

AWS CloudFormationcompatibilità: questa proprietà viene passata direttamente allaMode proprietà di unaAWS::ApiGateway::RestApi risorsa.

Models

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

Tipo: Mappa

Required: No

AWS CloudFormationcompatibilità: questa proprietà è unicaAWS SAM e non ha unAWS CloudFormation equivalente.

Name

Un nome per la RestApi risorsa API Gateway

Tipo: stringa

Required: No

AWS CloudFormationcompatibilità: questa proprietà viene passata direttamente allaName proprietà di unaAWS::ApiGateway::RestApi risorsa.

OpenApiVersion

Versione OpenApi da usare. Questo può riguardare2.0 la specifica Swagger o una delle versioni OpenApi 3.0, ad esempio3.0.1. Per ulteriori informazioni su OpenAPI, vedere la specifica OpenAPI.

Nota

AWS SAMcrea uno stage chiamatoStage di default. L'impostazione di questa proprietà su qualsiasi valore valido impedirà la creazione dello stageStage.

Tipo: stringa

Required: No

AWS CloudFormationcompatibilità: questa proprietà è unicaAWS SAM e non ha unAWS CloudFormation equivalente.

StageName

Il nome della fase usata da API Gateway come primo segmento del percorso nell'URI (Uniform Resource Identifier) richiamato.

Per fare riferimento alla risorsa dello stage, usa<api-logical-id>.Stage. Per ulteriori informazioni sulla referenziazione delle risorse generate quando viene specificata unaAWS::Serverless::Api risorsa, vedereAWS CloudFormationrisorse generate quando viene specificato AWS። Serverless። Api. Per informazioni generali sulleAWS CloudFormation risorse generate, vedereAWS CloudFormationRisorse generate.

Tipo: stringa

Required: Yes

AWS CloudFormationcompatibilità: questa proprietà è simile allaStageName proprietà di unaAWS::ApiGateway::Stage risorsa. È richiesto in SAM, ma non in API Gateway

Note aggiuntive: l'API implicita ha il nome di fase «Prod».

Tags

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

Tipo: Mappa

Required: No

AWS CloudFormationcompatibilità: questa proprietà è simile allaTags proprietà di unaAWS::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 la traccia attiva con X-Ray è abilitata per la fase. Per ulteriori informazioni su X-Ray, vedere Tracciare le richieste degli utenti verso API REST utilizzando X-Ray nella API Gateway Developer Guide.

Tipo: Booleano

Required: No

AWS CloudFormationcompatibilità: questa proprietà viene passata direttamente allaTracingEnabled proprietà di unaAWS::ApiGateway::Stage risorsa.

Variables

Una mappa (stringa a stringa) che definisce le variabili della fase, 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

AWS CloudFormationcompatibilità: questa proprietà viene passata direttamente allaVariables proprietà di unaAWS::ApiGateway::Stage risorsa.

Valori restituiti

Ref

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

Per ulteriori informazioni sull'utilizzo dellaRef funzione, consultare Refla Guida per l'AWS CloudFormationutente.

Ventilatore::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, consultare Fn::GetAttla Guida per l'AWS CloudFormationutente.

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

Esempi

SimpleApiExample

Un fileAWS SAM modello Hello World che contiene una funzione Lambda con un endpoint API. Si tratta di un fileAWS 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 api endpoint at "/" to the ApiGatewayApi via an Api event
    Type: AWS::Serverless::Function
    Properties:
      Events:
        ApiEvent:
          Type: Api
          Properties:
            Path: /
            Method: get
            RestApiId:
              Ref: ApiGatewayApi
      Runtime: python3.7
      Handler: index.handler
      InlineCode: |
        def handler(event, context):
            return {'body': 'Hello World!', 'statusCode': 200}

ApiCorsExample

Un frammento diAWS SAM modello con un'API definita in un file Swagger esterno insieme a integrazioni Lambda e configurazioni CORS. Questa è solo una parte di un fileAWS SAM modello che mostra unaAWS::Serverless::Api definizione.

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 diAWS SAM modello con un'API che utilizza Amazon Cognito per autorizzare le richieste relative all'API. Questa è solo una parte di un fileAWS SAM modello che mostra unaAWS::Serverless::Api definizione.

YAML


Resources:
  ApiGatewayApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: Prod
      Cors: "'*'"
      Auth:
        DefaultAuthorizer: MyCognitoAuthorizer
        Authorizers:
          MyCognitoAuthorizer:
            UserPoolArn:
              Fn::GetAtt: [MyCognitoUserPool, Arn]

ApiModelsExample

Un frammento diAWS SAM modello con un'API che include uno schema Models. Questa è solo una parte di un fileAWS SAM modello, che mostra unaAWS::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 memorizzazione nella cache

Un fileAWS 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 Abilitare la memorizzazione nella cache delle API per migliorare la reattività 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
Resources:
  ApiGatewayApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: prod
      CacheClusterEnabled: true
      CacheClusterSize: '0.5'
      MethodSettings:
        - ResourcePath: /
          HttpMethod: GET
          CachingEnabled: true
          CacheTtlInSeconds: 300

  ApiFunction: # Adds a GET api endpoint at "/" to the ApiGatewayApi via an Api event
    Type: AWS::Serverless::Function
    Properties:
      Events:
        ApiEvent:
          Type: Api
          Properties:
            Path: /
            Method: get
            RestApiId:
              Ref: ApiGatewayApi
      Runtime: python3.7
      Handler: index.handler
      InlineCode: |
        def handler(event, context):
            return {'body': 'Hello World!', 'statusCode': 200}

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Informazioni di riferimento su proprietà e risorse

ApiAuth