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 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 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.

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 allaAccessLogSettings 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 unHttpApiCorsConfiguration 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

IfCorsConfiguration è 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 dallaRouteSettings proprietà per determinati percorsi.

Tipo: RouteSettings

Required: No

AWS CloudFormationcompatibilità: questa proprietà viene passata direttamente allaRouteSettings proprietà di unaAWS::ApiGatewayV2::Stage risorsa.

DefinitionBody

La definizione di OpenAPI che descrive la tua API HTTP. Se non specifichi aDefinitionUri o aDefinitionBody,AWS SAM genera automaticamente unDefinitionBody valore in base alla configurazione del modello.

Type: JSON

Required: No

AWS CloudFormationcompatibilità: questa proprietà è simile allaBody 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 aDefinitionUri 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 ilsam 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 riferimentoDefinitionUri. Per importare una OpenApi definizione nel modello, utilizzate laDefinitionBody proprietà con la trasformazione Includi.

Tipo: String | HttpApiDefinition

Required: No

AWS CloudFormationcompatibilità: questa proprietà è simile allaBodyS3Location 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 specificaDescription,AWS SAM modificherà la OpenApi definizione della risorsa API HTTP impostando ildescription campo. I seguenti scenari genereranno un errore:

  • LaDefinitionBody proprietà è specificata con ildescription campo impostato nella definizione di Open API: ciò comporta un conflitto deldescription campo cheAWS SAM non verrà risolto.

  • LaDefinitionUri 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-apiendpoint 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 allaDisableExecuteApiEndpoint 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 allaFailOnWarnings proprietà di unaAWS::ApiGatewayV2::Api risorsa.

Name

Il nome della risorsa API HTTP.

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

  • LaDefinitionBody proprietà è specificata con iltitle campo impostato nella definizione di Open API: ciò comporta un conflitto deltitle campo cheAWS SAM non verrà risolto.

  • LaDefinitionUri 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 allaRouteSettings 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 allaStageName 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 allaStageVariables 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 prefissoaws:. 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: laTags 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 Refla 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