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 di Amazon API Gateway, che consente di creare API RESTful con latenza minore e costi inferiori rispetto alle API REST. Per ulteriori informazioni, consultare Working with HTTP APIs nella Guida per gli sviluppatori di Amazon API Gateway nella Guida per gli sviluppatori di Amazon API Gateway.
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
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::HttpApi Properties: AccessLogSettings:
AccessLogSettings
Auth:HttpApiAuth
CorsConfiguration:String | HttpApiCorsConfiguration
DefaultRouteSettings:RouteSettings
DefinitionBody:JSON
DefinitionUri:String | HttpApiDefinition
Description:String
DisableExecuteApiEndpoint:Boolean
Domain:HttpApiDomainConfiguration
FailOnWarnings:Boolean
Name:String
RouteSettings:RouteSettings
StageName:String
StageVariables:Json
Tags:Map
Proprietà
-
AccessLogSettings
-
Le impostazioni per la creazione di log di accesso in una fase.
Tipo: AccessLogSettings
Required: No
AWS CloudFormationcompatibilità: questa proprietà viene passata direttamente alla
AccessLogSettings
proprietà di unaAWS::ApiGatewayV2::Stage
risorsa. -
Auth
-
Configura l'autorizzazione per controllare l'accesso all'API HTTP di 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
Required: No
AWS CloudFormationcompatibilità: questa proprietà è unicaAWS SAM e non ha unAWS CloudFormation equivalente.
-
CorsConfiguration
-
Gestisce la condivisione di risorse cross-origin (CORS) per tutte le API HTTP di Amazon Gateway. Specifica il dominio da consentire come stringa o specifica un
HttpApiCorsConfiguration
oggetto. Nota che CORS richiedeAWS SAM di modificare la definizione di OpenAPI, quindi CORS funziona solo se viene specificata laDefinitionBody
proprietà.Per ulteriori informazioni, consultare Configurazione CORS per un'API API nella Guida per gli sviluppatori di Amazon API Gateway nella Guida per gli sviluppatori di Amazon API Gateway.
Nota If
CorsConfiguration
è impostato sia in una definizione OpenAPI che a livello di proprietà,AWS SAM unisce entrambe le fonti di configurazione con le proprietà che hanno la precedenza. Se questa proprietà è impostata sutrue
, sono consentite tutte le origini.Tipo: String | HttpApiCorsConfiguration
Required: No
AWS CloudFormationcompatibilità: questa proprietà è unicaAWS SAM e non ha unAWS CloudFormation equivalente.
-
DefaultRouteSettings
-
Le impostazioni di instradamento predefinite per questa API HTTP. Queste impostazioni si applicano a tutti i percorsi a meno che non vengano sostituite dalla
RouteSettings
proprietà per determinati percorsi.Tipo: RouteSettings
Required: No
AWS CloudFormationcompatibilità: questa proprietà viene passata direttamente alla
RouteSettings
proprietà di unaAWS::ApiGatewayV2::Stage
risorsa. -
DefinitionBody
-
La definizione di OpenAPI che descrive la tua API HTTP. Se non specifichi a
DefinitionUri
o aDefinitionBody
,AWS SAM genera automaticamente unDefinitionBody
valore in base alla configurazione del modello.Type: JSON
Required: No
AWS CloudFormationcompatibilità: questa proprietà è simile alla
Body
proprietà di unaAWS::ApiGatewayV2::Api
risorsa. Se vengono fornite determinate proprietà,AWS SAM può inserire o modificare il contenutoDefinitionBody
prima che venga passatoAWS CloudFormation. Le proprietà includonoAuth
un tipoEventSource
HttpApi diAWS::Serverless::Function
risorsa corrispondente. -
DefinitionUri
-
URI di Amazon Simple Storage Service (Amazon S3), percorso del file locale o oggetto di posizione 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 a
DefinitionUri
o aDefinitionBody
sono specificati,AWS SAM genera unDefinitionBody
per te in base alla configurazione del modello.Se si fornisce un percorso di file locale, il modello deve passare attraverso il flusso di lavoro che include il
sam package
comandosam deploy
or affinché la definizione venga trasformata correttamente.Le funzioni intrinseche non sono supportate nei file di OpenApi definizione esterni a cui si fa riferimento
DefinitionUri
. Per importare una OpenApi definizione nel modello, utilizzate laDefinitionBody
proprietà con la trasformazione Includi.Tipo: String | HttpApiDefinition
Required: No
AWS CloudFormationcompatibilità: questa proprietà è simile alla
BodyS3Location
proprietà di unaAWS::ApiGatewayV2::Api
risorsa. Le proprietà annidate di Amazon S3 hanno un nome diverso. -
Description
-
La descrizione della risorsa dell'API HTTP.
Quando si specifica
Description
,AWS SAM modificherà la OpenApi definizione della risorsa API HTTP impostando ildescription
campo. I seguenti scenari genereranno un errore:-
La
DefinitionBody
proprietà è specificata con ildescription
campo impostato nella definizione di Open API: ciò comporta un conflitto deldescription
campo cheAWS SAM non verrà risolto. -
La
DefinitionUri
proprietà è specificata:AWS SAM non modificherà una definizione di API aperta recuperata da Amazon S3.
Tipo: stringa
Required: No
AWS CloudFormationcompatibilità: questa proprietà è unicaAWS SAM e non ha unAWS CloudFormation equivalente.
-
-
DisableExecuteApiEndpoint
-
Specifica se i client possono richiamare l'API HTTP utilizzando l'
execute-api
endpoint predefinitohttps://{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 l'API, disabilitare l'endpoint predefinito.Tipo: Booleano
Required: No
AWS CloudFormationcompatibilità: questa proprietà viene passata direttamente alla
DisableExecuteApiEndpoint
proprietà di unaAWS::ApiGatewayV2::Api
risorsa. -
Domain
-
Configura un dominio personalizzato per questa API API Gateway HTTP.
Tipo: HttpApiDomainConfiguration
Required: No
AWS CloudFormationcompatibilità: questa proprietà è unicaAWS SAM e non ha unAWS CloudFormation equivalente.
-
FailOnWarnings
-
Specifica se ripristinare la creazione dell'API HTTP (
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 alla
FailOnWarnings
proprietà di unaAWS::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 iltitle
campo. I seguenti scenari genereranno un errore:-
La
DefinitionBody
proprietà è specificata con iltitle
campo impostato nella definizione di Open API: ciò comporta un conflitto deltitle
campo cheAWS SAM non verrà risolto. -
La
DefinitionUri
proprietà è specificata:AWS SAM non modificherà una definizione di API aperta recuperata da Amazon S3.
Tipo: stringa
Required: No
AWS CloudFormationcompatibilità: questa proprietà è unicaAWS SAM e non ha unAWS CloudFormation equivalente.
-
-
RouteSettings
-
Le impostazioni del percorso, per percorso, per questa API HTTP. Per ulteriori informazioni, consulta Working with routes for HTTP APIs nella Guida per gli sviluppatori di Amazon API Gateway nella Guida per gli sviluppatori di Amazon API Gateway.
Tipo: RouteSettings
Required: No
AWS CloudFormationcompatibilità: questa proprietà viene passata direttamente alla
RouteSettings
proprietà di unaAWS::ApiGatewayV2::Stage
risorsa. -
StageName
-
Il nome della fase dell'API. Se non viene specificato alcun nome,AWS SAM utilizza lo
$default
stage di API Gateway.Tipo: stringa
Required: No
Predefinito: $default
AWS CloudFormationcompatibilità: questa proprietà viene passata direttamente alla
StageName
proprietà di unaAWS::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-z0-9-._~:/? #&=,] +.
Type: Json
Required: No
AWS CloudFormationcompatibilità: questa proprietà viene passata direttamente alla
StageVariables
proprietà di unaAWS::ApiGatewayV2::Stage
risorsa. -
Tags
-
Una mappa (da stringa a stringa) che specifica i tag da aggiungere a questa fase dell'API Gateway. Le chiavi possono essere composto 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 essere composti da 1 a 256 caratteri Unicode.Tipo: Mappa
Required: No
AWS CloudFormationcompatibilità: questa proprietà è unicaAWS SAM e non ha unAWS CloudFormation equivalente.
Note aggiuntive: la
Tags
proprietà richiede diAWS SAM modificare la definizione di OpenAPI, quindi i tag vengono aggiunti solo se laDefinitionBody
proprietà è specificata, nessun tag viene aggiunto se laDefinitionUri
proprietà è specificata. AWS SAMaggiunge automaticamente unhttpapi:createdBy:SAM
tag. I tag vengono aggiunti anche allaAWS::ApiGatewayV2::Stage
risorsa e allaAWS::ApiGatewayV2::DomainName
risorsa (seDomainName
specificata).
Valori restituiti
Ref
Quando l'ID logico di questa risorsa viene passato allaRef
funzione intrinseca,Ref
restituisce l'ID API dellaAWS::ApiGatewayV2::Api
risorsa sottostante, ad esempioa1bcdef2gh
.
Per ulteriori informazioni sull'utilizzo dellaRef
funzione, consultare Ref
la Guida per l'AWS CloudFormationutente.
Esempi
Semplice HttpApi
L'esempio seguente mostra il minimo necessario per configurare un endpoint API HTTP supportato da una funzione Lambda. Questo esempio utilizza l'API HTTP predefinita cheAWS 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 autenticazione
Nell'esempio seguente viene impostato 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
Nell'esempio seguente viene mostrato come aggiungere una definizione OpenAPI al modello.
Nota cheAWS SAM inserisce tutte le integrazioni Lambda mancanti per HttpApi gli eventi che fanno riferimento a questa API HTTP. AWS SAMaggiunge anche eventuali percorsi mancanti a cui fanno riferimento HttpApi gli 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
Nell'esempio seguente viene mostrato come aggiungere l'API HTTP e le configurazioni di fase 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