View a markdown version of this page

AWS::Serverless::HttpApi - 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::HttpApi

Crea un'API HTTP di Amazon API Gateway, che consente di creare API RESTful con latenza e costi inferiori rispetto alle API REST. Per ulteriori informazioni, consulta Lavorare con le API HTTP nel Guida per sviluppatori di API Gateway.

Ti consigliamo di usare 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

AccessLogSettings

Le impostazioni per la registrazione degli accessi in una fase.

Tipo: AccessLogSettings

Obbligatorio: no

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

Auth

Configura l'autorizzazione per il controllo dell'accesso all'API HTTP API Gateway.

Per ulteriori informazioni consulta la sezione Controlling access to HTTP APIs with JWT authorizers (Controllo dell'accesso alle API HTTP con le autorizzazioni JWT) nella Guida per gli sviluppatori dell’API Gateway.

Tipo: HttpApiAuth

Obbligatorio: no

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

CorsConfiguration

Gestisce la condivisione delle risorse tra origini (CORS) per tutte le API HTTP di API Gateway. Specifica il dominio da consentire come stringa o specifica un HttpApiCorsConfiguration oggetto. Nota che CORS richiede AWS SAM per modificare la definizione di OpenAPI, quindi CORS funziona solo se DefinitionBody la proprietà è specificata.

Per ulteriori informazioni, vedere Configurazione di CORS per un'API HTTP nel Guida per sviluppatori di API Gateway.

Nota

Se CorsConfiguration è impostato sia in una definizione OpenAPI che a livello di proprietà, allora AWS SAM unisce entrambe le fonti di configurazione con le proprietà che hanno la precedenza. Se questa proprietà è impostata su true, allora sono consentite tutte le origini.

Tipo: Stringa | HttpApiCorsConfiguration

Obbligatorio: no

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

DefaultRouteSettings

Le impostazioni di route predefinite per questa API HTTP. Queste impostazioni si applicano a tutte le rotte a meno che non vengano sovrascritte da RouteSettings proprietà per determinati percorsi.

Tipo: RouteSettings

Obbligatorio: no

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

DefinitionBody

La definizione OpenAPI che descrive la tua API HTTP. Se non specifichi un DefinitionUri o un DefinitionBody, AWS SAM genera un DefinitionBody per te in base alla configurazione del tuo modello.

Type: JSON

Obbligatorio: no

CloudFormation compatibilità: Questa proprietà è simile alla Body proprietà di un AWS::ApiGatewayV2::Api risorsa. Se vengono fornite determinate proprietà, AWS SAM può inserire contenuti o modificarli DefinitionBody prima che venga passato a CloudFormation. Le proprietà includono Auth e un EventSource di tipo HttpApi per un corrispondente AWS::Serverless::Function risorsa.

DefinitionUri

L'URI, il percorso del file locale o l'oggetto di posizione di Amazon Simple Storage Service (Amazon S3) della definizione OpenAPI che definisce l'API HTTP. L'oggetto Amazon S3 a cui fa riferimento questa proprietà deve essere un file di definizione OpenAPI valido. Se non specifichi un DefinitionUri o un DefinitionBody sono specificati, AWS SAM genera un DefinitionBody per te in base alla configurazione del tuo modello.

Se fornisci un percorso di file locale, il modello deve passare attraverso il flusso di lavoro che include sam deploy o sam package comando per trasformare correttamente la definizione.

Le funzioni intrinseche non sono supportate in ambienti esterni OpenApi file di definizione a cui si fa riferimento DefinitionUri. Per importare un OpenApi definizione nel modello, usa DefinitionBody proprietà con Includi trasformazione.

Tipo: Stringa | HttpApiDefinition

Obbligatorio: no

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

Description

La descrizione della risorsa API HTTP.

Quando si specifica Description, AWS SAM modificherà le risorse dell'API HTTP OpenApi definizione impostando il description campo. I seguenti scenari genereranno un errore:

  • Il DefinitionBody la proprietà è specificata con description campo impostato nella definizione Open API: ciò comporta un conflitto tra description campo che AWS SAM non si risolverà.

  • Il DefinitionUri la proprietà è specificata — AWS SAM non modificherà una definizione di API aperta recuperata da Amazon S3.

▬Tipo: stringa

Obbligatorio: no

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

DisableExecuteApiEndpoint

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

Per utilizzare questa proprietà, è necessario specificare DefinitionBody proprietà invece di DefinitionUri proprietà o definire x-amazon-apigateway-endpoint-configuration con disableExecuteApiEndpoint nella tua definizione OpenAPI.

Tipo: Booleano

Obbligatorio: no

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

Domain

Configura un dominio personalizzato per questa API HTTP API Gateway.

Tipo: HttpApiDomainConfiguration

Obbligatorio: no

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

FailOnWarnings

Specifica se ripristinare la creazione dell'API HTTP (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::ApiGatewayV2::Api risorsa.

Name

Il nome della risorsa API HTTP.

Quando si specifica Name, AWS SAM modificherà la definizione OpenAPI della risorsa API HTTP impostando title campo. I seguenti scenari genereranno un errore:

  • Il DefinitionBody la proprietà è specificata con title campo impostato nella definizione Open API: ciò comporta un conflitto tra title campo che AWS SAM non si risolverà.

  • Il DefinitionUri la proprietà è specificata — AWS SAM non modificherà una definizione di API aperta recuperata da Amazon S3.

▬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::HttpApi 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.

RouteSettings

Le impostazioni del percorso, per percorso, per questa API HTTP. Per ulteriori informazioni, consulta Utilizzo di route per le API HTTP nel Guida per sviluppatori di API Gateway.

Tipo: RouteSettings

Obbligatorio: no

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

StageName

Il nome della fase API. Se non viene specificato alcun nome, AWS SAM utilizza $default fase di API Gateway.

▬Tipo: stringa

Obbligatorio: no

Predefinito: $predefinito

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

StageVariables

Mappa che definisce le variabili delle fasi. I nomi delle variabili possono avere caratteri alfanumerici e caratteri di sottolineatura. I valori devono corrispondere a [A-Za-z0-9-._~:/? #&=,] +.

Type: Json

Obbligatorio: no

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

Tags

Una mappa (da stringa a stringa) che specifica i tag da aggiungere a questa fase di API Gateway. Le chiavi possono contenere da 1 a 128 caratteri Unicode e non possono includere il prefisso aws:. Puoi utilizzare uno qualsiasi dei seguenti caratteri: l'insieme delle lettere Unicode, cifre, spazi, _, ., /, =, + e -. I valori possono avere una lunghezza compresa tra 1 e 256 caratteri Unicode.

Digitare: Mappa

Obbligatorio: no

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

Note aggiuntive: Il Tags la proprietà richiede AWS SAM per modificare la definizione di OpenAPI, quindi i tag vengono aggiunti solo se DefinitionBody viene specificata la proprietà: non viene aggiunto alcun tag se DefinitionUri viene specificata la proprietà. AWS SAM aggiunge automaticamente un httpapi:createdBy:SAM etichetta. I tag vengono aggiunti anche al AWS::ApiGatewayV2::Stage risorsa e AWS::ApiGatewayV2::DomainName risorsa (se DomainName è specificato).

Valori restituiti

Ref

Quando si passa l'ID logico di questa risorsa all'intrinseco Ref funzione, Ref restituisce l'ID API del sottostante AWS::ApiGatewayV2::Api risorsa, ad esempio a1bcdef2gh.

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

Esempi

Semplice HttpApi

L'esempio seguente mostra il minimo necessario per configurare un endpoint API HTTP supportato da una Lambda Event Function. Questo esempio utilizza l'API HTTP predefinita che AWS SAM crea.

YAML

AWSTemplateFormatVersion: '2010-09-09' Description: AWS SAM template with a simple API definition Resources: ApiFunction: Type: AWS::Serverless::Function Properties: Events: ApiEvent: Type: HttpApi Handler: index.handler InlineCode: | def handler(event, context): return {'body': 'Hello World!', 'statusCode': 200} Runtime: python3.7 Transform: AWS::Serverless-2016-10-31

HttpApi con Auth

L'esempio seguente mostra come impostare l'autorizzazione sugli endpoint dell'API HTTP.

YAML

Properties: FailOnWarnings: true Auth: DefaultAuthorizer: OAuth2 Authorizers: OAuth2: AuthorizationScopes: - scope4 JwtConfiguration: issuer: "https://www.example.com/v1/connect/oauth2" audience: - MyApi IdentitySource: "$request.querystring.param"

HttpApi con definizione OpenAPI

L'esempio seguente mostra come aggiungere una definizione OpenAPI al modello.

Nota che AWS SAM compila tutte le integrazioni Lambda mancanti per HttpApi eventi che fanno riferimento a questa API HTTP. AWS SAM aggiunge anche eventuali percorsi mancanti che HttpApi riferimento agli eventi.

YAML

Properties: FailOnWarnings: true DefinitionBody: info: version: '1.0' title: Ref: AWS::StackName paths: "/": get: security: - OpenIdAuth: - scope1 - scope2 responses: {} openapi: 3.0.1 securitySchemes: OpenIdAuth: type: openIdConnect x-amazon-apigateway-authorizer: identitySource: "$request.querystring.param" type: jwt jwtConfiguration: audience: - MyApi issuer: https://www.example.com/v1/connect/oidc openIdConnectUrl: https://www.example.com/v1/connect/oidc/.well-known/openid-configuration

HttpApi con impostazioni di configurazione

L'esempio seguente mostra come aggiungere l'API HTTP e le configurazioni degli stage al modello.

YAML

AWSTemplateFormatVersion: '2010-09-09' Transform: AWS::Serverless-2016-10-31 Parameters: StageName: Type: String Default: Prod Resources: HttpApiFunction: Type: AWS::Serverless::Function Properties: InlineCode: | def handler(event, context): import json return { "statusCode": 200, "body": json.dumps(event), } Handler: index.handler Runtime: python3.7 Events: ExplicitApi: # warning: creates a public endpoint Type: HttpApi Properties: ApiId: !Ref HttpApi Method: GET Path: /path TimeoutInMillis: 15000 PayloadFormatVersion: "2.0" RouteSettings: ThrottlingBurstLimit: 600 HttpApi: Type: AWS::Serverless::HttpApi Properties: StageName: !Ref StageName Tags: Tag: Value AccessLogSettings: DestinationArn: !GetAtt AccessLogs.Arn Format: $context.requestId DefaultRouteSettings: ThrottlingBurstLimit: 200 RouteSettings: "GET /path": ThrottlingBurstLimit: 500 # overridden in HttpApi Event StageVariables: StageVar: Value FailOnWarnings: true AccessLogs: Type: AWS::Logs::LogGroup Outputs: HttpApiUrl: Description: URL of your API endpoint Value: Fn::Sub: 'https://${HttpApi}.execute-api.${AWS::Region}.${AWS::URLSuffix}/${StageName}/' HttpApiId: Description: Api id of HttpApi Value: Ref: HttpApi