View a markdown version of this page

AWS::Serverless::Api - AWS Serverless Application Model

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.

Un AWS::Serverless::Api la risorsa non deve essere aggiunta esplicitamente a a AWS Modello di definizione dell'applicazione serverless. Una risorsa di questo tipo viene creata implicitamente dall'unione di eventi Api definiti su AWS::Serverless::Funzione risorse definite nel modello che non fanno riferimento a un AWS::Serverless::Api risorsa.

Un AWS::Serverless::Api la risorsa deve essere utilizzata per definire e documentare l'API utilizzando OpenApi, che offre una maggiore capacità di configurare le 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'utilizzo CloudFormation ganci, vedi Registrazione di ganci nel CloudFormation guida per l'utente della CLI e il apigw-enforce-authorizer GitHub archivio.

Per ulteriori informazioni sull'utilizzo delle policy IAM, consulta Richiedi che le route API siano autorizzate nel Guida per sviluppatori di API Gateway.

Questa risorsa supporta anche Connectors risorsa Attribute. Per ulteriori informazioni, consulta Gestione delle autorizzazioni delle risorse con AWS SAM connettori.

Nota

Quando esegui il deployment su AWS CloudFormation, AWS SAM trasforma il tuo AWS SAM risorse in CloudFormation risorse. Per ulteriori informazioni, consulta Generato CloudFormation risorse per AWS SAM.

Sintassi

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

Properties

AccessLogSetting

Configura le impostazioni del registro degli accessi per una fase.

Tipo: AccessLogSetting

Obbligatorio: no

CloudFormation compatibilità: Questa proprietà viene passata direttamente al AccessLogSetting proprietà di un AWS::ApiGateway::Stage risorsa.

AlwaysDeploy

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

Tipo: Booleano

Obbligatorio: no

CloudFormation compatibilità: Questa proprietà è unica per 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

Obbligatorio: no

CloudFormation compatibilità: Questa proprietà viene passata direttamente al ApiKeySourceType proprietà di un AWS::ApiGateway::RestApi risorsa.

Auth

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

Per ulteriori informazioni sulla configurazione dell'accesso utilizzando AWS SAM vedere Controlla 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

Obbligatorio: no

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

BinaryMediaTypes

Elenco dei tipi MIME che la tua API potrebbe restituire. Usalo per abilitare il supporto binario per le API.

Tipo: elenco

Obbligatorio: no

CloudFormation compatibilità: Questa proprietà è simile alla BinaryMediaTypes proprietà di un AWS::ApiGateway::RestApi risorsa. L'elenco di BinaryMediaTypes viene aggiunto a entrambi CloudFormation risorsa e documento OpenAPI.

CacheClusterEnabled

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

Tipo: Booleano

Obbligatorio: no

CloudFormation compatibilità: Questa proprietà viene passata direttamente al CacheClusterEnabled proprietà di un AWS::ApiGateway::Stage risorsa.

CacheClusterSize

Le dimensioni del cluster di cache della fase.

▬Tipo: stringa

Obbligatorio: no

CloudFormation compatibilità: Questa proprietà viene passata direttamente al CacheClusterSize proprietà di un AWS::ApiGateway::Stage risorsa.

CanarySetting

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

Tipo: CanarySetting

Obbligatorio: no

CloudFormation compatibilità: Questa proprietà viene passata direttamente al CanarySetting proprietà di un AWS::ApiGateway::Stage risorsa.

Cors

Gestisci Cross-origin condivisione delle risorse (CORS) per tutte le tue API API Gateway. Specifica il dominio da consentire come stringa o specifica un dizionario con una configurazione Cors aggiuntiva.

Nota

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

Per ulteriori informazioni su CORS, vedere Abilita CORS per una risorsa API REST API Gateway nel Guida per sviluppatori di API Gateway.

Tipo: Stringa | CorsConfiguration

Obbligatorio: no

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

DefinitionBody

specifica OpenAPI che descrive la tua API. Se nessuno dei due DefinitionUri né DefinitionBody sono specificati, SAM genererà un DefinitionBody per te in base alla configurazione del modello.

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

Type: JSON

Obbligatorio: no

CloudFormation compatibilità: Questa proprietà è simile alla Body proprietà di un AWS::ApiGateway::RestApi risorsa. Se vengono fornite determinate proprietà, il contenuto può essere inserito o modificato nel DefinitionBody prima di essere passato a CloudFormation. Le proprietà includono Auth, BinaryMediaTypes, Cors, GatewayResponses, Models, e un EventSource di tipo Api per un corrispondente AWS::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 fa riferimento questa proprietà deve essere un file OpenAPI valido. Se nessuno dei due DefinitionUri né DefinitionBody sono specificati, SAM genererà un 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 sam deploy o sam package comando, affinché la definizione venga trasformata correttamente.

Le funzioni intrinseche non sono supportate in ambienti esterni OpenApi file a cui fa riferimento DefinitionUri. Usa invece il DefinitionBody proprietà con Includi trasformazione per importare un OpenApi definizione nel modello.

Digitare: Stringa | ApiDefinition

Obbligatorio: no

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

Description

Una descrizione della risorsa Api.

▬Tipo: stringa

Obbligatorio: no

CloudFormation compatibilità: Questa proprietà viene passata direttamente al Description proprietà di un 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 predefinita https://{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

Obbligatorio: no

CloudFormation compatibilità: Questa proprietà è simile alla DisableExecuteApiEndpoint proprietà di un AWS::ApiGateway::RestApi risorsa. Viene passato direttamente al disableExecuteApiEndpoint proprietà di un x-amazon-apigateway-endpoint-configuration estensione, che viene aggiunta a Body proprietà di un AWS::ApiGateway::RestApi risorsa.

Domain

Configura un dominio personalizzato per questa API API Gateway.

Tipo: DomainConfiguration

Obbligatorio: no

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

EndpointConfiguration

Il tipo di endpoint di un'API REST.

Tipo: EndpointConfiguration

Obbligatorio: no

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

EndpointAccessMode

La modalità di accesso per l'endpoint dell'API REST. Obbligatoria quando si utilizzano politiche di sicurezza avanzate (quelle precedute da SecurityPolicy_).

Valori validi: STRICT o BASIC

▬Tipo: stringa

Obbligatorio: no

CloudFormation compatibilità: Questa proprietà viene passata direttamente al EndpointAccessMode proprietà di un AWS::ApiGateway::RestApi risorsa.

FailOnWarnings

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

Tipo: Booleano

Obbligatorio: no

CloudFormation compatibilità: Questa proprietà viene passata direttamente al FailOnWarnings proprietà di un 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 per Api Gateway OpenApi estensione per Gateway Responses.

Tipo: Mappa

Obbligatorio: no

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

MergeDefinitions

AWS SAM genera un OpenAPI specifica dalla tua fonte di eventi API. Specifica true avere AWS SAM unisci questo nell'inline OpenAPI specifica definita nel tuo AWS::Serverless::Api risorsa. Specificare false per non unire.

MergeDefinitions richiede il DefinitionBody proprietà per AWS::Serverless::Api da definire. MergeDefinitions non è compatibile con DefinitionUri proprietà per AWS::Serverless::Api.

Valore predefinito: false

Tipo: Booleano

Obbligatorio: no

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

MethodSettings

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

Tipo: elenco di MethodSetting

Obbligatorio: no

CloudFormation compatibilità: Questa proprietà viene passata direttamente al MethodSettings proprietà di un AWS::ApiGateway::Stage risorsa.

MinimumCompressionSize

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

Tipo: integer

Obbligatorio: no

CloudFormation compatibilità: Questa proprietà viene passata direttamente al MinimumCompressionSize proprietà di un AWS::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 Modo proprietà del AWS::ApiGateway::RestApi tipo di risorsa.

Valori validi: overwrite o merge

▬Tipo: stringa

Obbligatorio: no

CloudFormation compatibilità: Questa proprietà viene passata direttamente al Mode proprietà di un AWS::ApiGateway::RestApi risorsa.

Models

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

Digitare: Mappa

Obbligatorio: no

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

Name

Un nome per l'API Gateway RestApi risorsa

▬Tipo: stringa

Obbligatorio: no

CloudFormation compatibilità: Questa proprietà viene passata direttamente al Name proprietà di un AWS::ApiGateway::RestApi risorsa.

OpenApiVersion

Versione di OpenApi da usare. Questo può essere 2.0 per la specifica Swagger, o una delle OpenApi versioni 3.0, come 3.0.1. Per ulteriori informazioni su OpenAPI, consulta la Specifica OpenAPI.

Nota

AWS SAM crea una fase chiamata Stage per impostazione predefinita. L'impostazione di questa proprietà su un valore valido impedirà la creazione dello stage Stage.

▬Tipo: stringa

Obbligatorio: no

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

PropagateTags

Indicare se passare o meno i tag dal Tags proprietà al tuo AWS::Serverless::Api risorse generate. Specificare True per propagare i tag nelle risorse generate.

Tipo: Booleano

Obbligatorio: no

Default: False

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

Policy

Un documento politico 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

Obbligatorio: no

CloudFormation compatibilità: Questa proprietà viene passata direttamente al Politica proprietà di un AWS::ApiGateway::RestApi risorsa.

SecurityPolicy

La versione TLS più la suite di crittografia per l'API REST. Quando si utilizzano politiche di sicurezza avanzate (quelle precedute da SecurityPolicy>), è inoltre necessario impostareEndpointAccessMode.

▬Tipo: stringa

Obbligatorio: no

CloudFormation compatibilità: Questa proprietà viene passata direttamente al SecurityPolicy proprietà di un 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 sulla referenziazione delle risorse generate quando un AWS::Serverless::Api la risorsa è specificata, vedere CloudFormation risorse generate quando AWS::Serverless::Api è specificato. Per informazioni generali sui generati CloudFormation risorse, vedi Generato CloudFormation risorse per AWS SAM.

Tipo: stringa

Obbligatorio: sì

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

Note aggiuntive: L'API implicita 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 sui valori validi per i tag, vedi Tag di risorsa nel AWS CloudFormation Guida per l'utente.

Tipo: Mappa

Obbligatorio: no

CloudFormation compatibilità: Questa proprietà è simile alla Tags proprietà di un AWS::ApiGateway::Stage risorsa. La proprietà Tags in SAM è composta da Key:Value coppie; in CloudFormation è costituito da un elenco di oggetti Tag.

TracingEnabled

Indica se la traccia è attiva con X-Ray è abilitato per lo stage. Per ulteriori informazioni su X-Ray, vedi Tracciamento delle richieste degli utenti alle API REST utilizzando X-Ray nel Guida per sviluppatori di API Gateway.

Tipo: Booleano

Obbligatorio: no

CloudFormation compatibilità: Questa proprietà viene passata direttamente al TracingEnabled proprietà di un AWS::ApiGateway::Stage risorsa.

Variables

Una mappa (da stringa a stringa) che definisce le variabili di fase, in cui 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._~:/?#&=,-]+.

Digitare: Mappa

Obbligatorio: no

CloudFormation compatibilità: Questa proprietà viene passata direttamente al Variables proprietà di un AWS::ApiGateway::Stage risorsa.

Valori restituiti

Ref

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

Per ulteriori informazioni sull'utilizzo di Ref funzione, vedere Ref nel AWS CloudFormation Guida per l'utente.

Ventola::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'uso Fn::GetAtt, vedi Fn::GetAtt nel AWS CloudFormation Guida per l'utente.

RootResourceId

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

Esempi

SimpleApiExample

Un Hello World AWS SAM file modello che contiene una Lambda Event Function con un endpoint API. Questo è un file completo AWS SAM file modello 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 AWS SAM frammento di modello con un'API definita in un file Swagger esterno insieme alle integrazioni Lambda e alle configurazioni CORS. Questa è solo una parte di un AWS SAM file modello che mostra un AWS::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 AWS SAM frammento di modello con un'API che utilizza Amazon Cognito per autorizzare le richieste relative all'API. Questa è solo una parte di un AWS SAM file modello che mostra un AWS::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 AWS SAM frammento di modello con un'API che include uno schema Models. Questa è solo una parte di un AWS SAM file modello, che mostra un 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 Hello World AWS SAM file modello 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, vedere Abilitare la memorizzazione nella cache delle API per migliorare la reattività nel Guida per sviluppatori di 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}

Dominio personalizzato con un esempio di API privata

Un Hello World AWS SAM file modello 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 le API private 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