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
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.
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.
YAML
Type: AWS::Serverless::HttpApi Properties: AccessLogSettings:AccessLogSettingsAuth:HttpApiAuthCorsConfiguration:String | HttpApiCorsConfigurationDefaultRouteSettings:RouteSettingsDefinitionBody:JSONDefinitionUri:String | HttpApiDefinitionDescription:StringDisableExecuteApiEndpoint:BooleanDomain:HttpApiDomainConfigurationFailOnWarnings:BooleanName:StringPropagateTags:BooleanRouteSettings:RouteSettingsStageName:StringStageVariables:JsonTags:Map
Properties
-
AccessLogSettings -
Le impostazioni per la registrazione degli accessi in una fase.
Tipo: AccessLogSettings
Obbligatorio: no
CloudFormation compatibilità: Questa proprietà viene passata direttamente al
AccessLogSettingsproprietà di unAWS::ApiGatewayV2::Stagerisorsa. -
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
HttpApiCorsConfigurationoggetto. Nota che CORS richiede AWS SAM per modificare la definizione di OpenAPI, quindi CORS funziona solo seDefinitionBodyla proprietà è specificata.Per ulteriori informazioni, vedere Configurazione di CORS per un'API HTTP nel Guida per sviluppatori di API Gateway.
NotaSe
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 sutrue, 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
RouteSettingsproprietà per determinati percorsi.Tipo: RouteSettings
Obbligatorio: no
CloudFormation compatibilità: Questa proprietà viene passata direttamente al
RouteSettingsproprietà di unAWS::ApiGatewayV2::Stagerisorsa. -
DefinitionBody -
La definizione OpenAPI che descrive la tua API HTTP. Se non specifichi un
DefinitionUrio unDefinitionBody, AWS SAM genera unDefinitionBodyper te in base alla configurazione del tuo modello.Type: JSON
Obbligatorio: no
CloudFormation compatibilità: Questa proprietà è simile alla
Bodyproprietà di unAWS::ApiGatewayV2::Apirisorsa. Se vengono fornite determinate proprietà, AWS SAM può inserire contenuti o modificarliDefinitionBodyprima che venga passato a CloudFormation. Le proprietà includonoAuthe unEventSourcedi tipo HttpApi per un corrispondenteAWS::Serverless::Functionrisorsa. -
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
DefinitionUrio unDefinitionBodysono specificati, AWS SAM genera unDefinitionBodyper 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 deployosam packagecomando 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, usaDefinitionBodyproprietà con Includi trasformazione.Tipo: Stringa | HttpApiDefinition
Obbligatorio: no
CloudFormation compatibilità: Questa proprietà è simile alla
BodyS3Locationproprietà di unAWS::ApiGatewayV2::Apirisorsa. 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 ildescriptioncampo. I seguenti scenari genereranno un errore:-
Il
DefinitionBodyla proprietà è specificata condescriptioncampo impostato nella definizione Open API: ciò comporta un conflitto tradescriptioncampo che AWS SAM non si risolverà. -
Il
DefinitionUrila 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-apiendpointhttps://{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
DefinitionBodyproprietà invece diDefinitionUriproprietà o definirex-amazon-apigateway-endpoint-configurationcondisableExecuteApiEndpointnella tua definizione OpenAPI.Tipo: Booleano
Obbligatorio: no
CloudFormation compatibilità: Questa proprietà è simile alla
DisableExecuteApiEndpointproprietà di unAWS::ApiGatewayV2::Apirisorsa. Viene passato direttamente aldisableExecuteApiEndpointproprietà di unx-amazon-apigateway-endpoint-configurationestensione, che viene aggiunta aBodyproprietà di unAWS::ApiGatewayV2::Apirisorsa. -
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
FailOnWarningsproprietà di unAWS::ApiGatewayV2::Apirisorsa. Name-
Il nome della risorsa API HTTP.
Quando si specifica
Name, AWS SAM modificherà la definizione OpenAPI della risorsa API HTTP impostandotitlecampo. I seguenti scenari genereranno un errore:-
Il
DefinitionBodyla proprietà è specificata contitlecampo impostato nella definizione Open API: ciò comporta un conflitto tratitlecampo che AWS SAM non si risolverà. -
Il
DefinitionUrila 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.
-
-
Indicare se passare o meno i tag dal
Tagsproprietà al tuo AWS::Serverless::HttpApi risorse generate. SpecificareTrueper propagare i tag nelle risorse generate.Tipo: Booleano
Obbligatorio: no
Default:
FalseCloudFormation 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
RouteSettingsproprietà di unAWS::ApiGatewayV2::Stagerisorsa. -
StageName -
Il nome della fase API. Se non viene specificato alcun nome, AWS SAM utilizza
$defaultfase di API Gateway.▬Tipo: stringa
Obbligatorio: no
Predefinito: $predefinito
CloudFormation compatibilità: Questa proprietà viene passata direttamente al
StageNameproprietà di unAWS::ApiGatewayV2::Stagerisorsa. -
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
StageVariablesproprietà di unAWS::ApiGatewayV2::Stagerisorsa. -
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
Tagsla proprietà richiede AWS SAM per modificare la definizione di OpenAPI, quindi i tag vengono aggiunti solo seDefinitionBodyviene specificata la proprietà: non viene aggiunto alcun tag seDefinitionUriviene specificata la proprietà. AWS SAM aggiunge automaticamente unhttpapi:createdBy:SAMetichetta. I tag vengono aggiunti anche alAWS::ApiGatewayV2::Stagerisorsa eAWS::ApiGatewayV2::DomainNamerisorsa (seDomainNameè 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