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 Amazon API Gateway, che ti consente di creare RESTful APIs con una latenza inferiore e costi inferiori rispetto a REST APIs. Per ulteriori informazioni, consulta [Working with HTTP APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api.html) nella *API Gateway Developer Guide*.
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'uso degli CloudFormation hook, consulta [Registrazione degli hook](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/registering-hook-python.html) nella guida per l'*utente della CloudFormation CLI* e nel repository. [apigw-enforce-authorizer](https://github.com/aws-cloudformation/aws-cloudformation-samples/tree/main/hooks/python-hooks/apigw-enforce-authorizer/) GitHub
Per ulteriori informazioni sull'utilizzo delle policy IAM, consulta [Require che le route API abbiano l'autorizzazione](https://docs.aws.amazon.com/apigateway/latest/developerguide/security_iam_id-based-policy-examples.html#security_iam_id-based-policy-examples-require-authorization) nella *API Gateway Developer Guide*.
**Nota**
Quando esegui la distribuzione a AWS CloudFormation, AWS SAM trasforma le tue AWS SAM risorse in CloudFormation risorse. Per ulteriori informazioni, consulta [CloudFormation Risorse generate per AWS SAM](sam-specification-generated-resources.md).
## Sintassi
Per dichiarare questa entità nel tuo modello AWS Serverless Application Model (AWS SAM), usa la seguente sintassi.
### YAML
```
Type: AWS::Serverless::HttpApi
Properties:
[AccessLogSettings](#sam-httpapi-accesslogsettings): [AccessLogSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-accesslogsettings)
[Auth](#sam-httpapi-auth): HttpApiAuth
[CorsConfiguration](#sam-httpapi-corsconfiguration): String | HttpApiCorsConfiguration
[DefaultRouteSettings](#sam-httpapi-defaultroutesettings): [RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)
[DefinitionBody](#sam-httpapi-definitionbody): JSON
[DefinitionUri](#sam-httpapi-definitionuri): String | HttpApiDefinition
[Description](#sam-httpapi-description): String
[DisableExecuteApiEndpoint](#sam-httpapi-disableexecuteapiendpoint): Boolean
[Domain](#sam-httpapi-domain): HttpApiDomainConfiguration
[FailOnWarnings](#sam-httpapi-failonwarnings): Boolean
Name: String
PropagateTags: Boolean
[RouteSettings](#sam-httpapi-routesettings): [RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)
[StageName](#sam-httpapi-stagename): String
[StageVariables](#sam-httpapi-stagevariables): [Json](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-stagevariables)
[Tags](#sam-httpapi-tags): Map
```
## Properties
`AccessLogSettings`
Le impostazioni per la registrazione degli accessi in una fase.
*Tipo:* [AccessLogSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-accesslogsettings)
*Obbligatorio:* no
*CloudFormation compatibilità*: questa proprietà viene passata direttamente alla `[AccessLogSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-accesslogsettings)` proprietà di una `AWS::ApiGatewayV2::Stage` risorsa.
`Auth`
Configura l'autorizzazione per il controllo dell'accesso all'API HTTP API Gateway.
Per ulteriori informazioni, consulta [Controllare l'accesso a HTTP APIs con gli autorizzatori JWT](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-jwt-authorizer.html) nella *API Gateway Developer Guide*.
*Tipo:* [HttpApiAuth](sam-property-httpapi-httpapiauth.md)
*Obbligatorio:* no
*CloudFormation compatibilità*: questa proprietà è unica AWS SAM e non ha un CloudFormation equivalente.
`CorsConfiguration`
Gestisce la condivisione delle risorse tra le origini (CORS) per tutti i tuoi API Gateway HTTP. APIs Specificate il dominio da consentire come stringa o specificate un `HttpApiCorsConfiguration` oggetto. Nota che CORS richiede AWS SAM di modificare la definizione OpenAPI, quindi CORS funziona solo se `DefinitionBody` la proprietà è specificata.
Per ulteriori informazioni, consulta [Configurazione di CORS per un'API HTTP](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-cors.html) nella Guida per *sviluppatori di API Gateway*.
Se `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 su`true`, tutte le origini sono consentite.
*Tipo*: String \$1 [HttpApiCorsConfiguration](sam-property-httpapi-httpapicorsconfiguration.md)
*Obbligatorio:* no
*CloudFormation compatibilità*: Questa proprietà è unica AWS SAM e non ha un CloudFormation equivalente.
`DefaultRouteSettings`
Le impostazioni di routing predefinite per questa API HTTP. Queste impostazioni si applicano a tutti i percorsi a meno che non vengano sovrascritte dalla `RouteSettings` proprietà per determinati percorsi.
*Tipo:* [RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)
*Obbligatorio:* no
*CloudFormation compatibilità*: questa proprietà viene passata direttamente alla `[RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)` proprietà di una `AWS::ApiGatewayV2::Stage` risorsa.
`DefinitionBody`
La definizione OpenAPI che descrive la tua API HTTP. Se non specifichi a `DefinitionUri` o a`DefinitionBody`, AWS SAM genera una `DefinitionBody` per te in base alla configurazione del modello.
*Type*: JSON
*Obbligatorio:* no
*CloudFormation compatibilità*: questa proprietà è simile alla `[Body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-body)` proprietà di una `AWS::ApiGatewayV2::Api` risorsa. Se vengono fornite determinate proprietà, AWS SAM può inserire o modificare il contenuto `DefinitionBody` prima che venga passato a CloudFormation. Le proprietà includono `Auth` e un `EventSource` tipo HttpApi per una `AWS::Serverless::Function` risorsa corrispondente.
`DefinitionUri`
L'URI, il percorso del file locale o l'oggetto location di Amazon Simple Storage Service (Amazon S3) Simple Storage Service (Amazon S3) Simple Storage Service (Amazon S3) 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 a are `DefinitionBody` sono specificati, AWS SAM genera un messaggio `DefinitionBody` in base alla configurazione del modello.
Se fornite un percorso di file locale, il modello deve passare attraverso il flusso di lavoro che include il `sam package` comando `sam deploy` o 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 la `DefinitionBody` proprietà con la trasformazione [Include](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/create-reusable-transform-function-snippets-and-add-to-your-template-with-aws-include-transform.html).
*Tipo*: String \$1 [HttpApiDefinition](sam-property-httpapi-httpapidefinition.md)
*Obbligatorio:* no
*CloudFormation compatibilità*: Questa proprietà è simile alla `[BodyS3Location](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-bodys3location)` proprietà di una `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à la OpenApi definizione della risorsa API HTTP impostando il `description` campo. I seguenti scenari genereranno un errore:
+ La `DefinitionBody` proprietà viene specificata con il `description` campo impostato nella definizione di Open API: ciò genera un conflitto del `description` campo che AWS SAM non verrà risolto.
+ La `DefinitionUri` proprietà è specificata: AWS SAM non modificherà una definizione di Open API recuperata da Amazon S3.
▬*Tipo:* stringa
*Obbligatorio:* no
*CloudFormation compatibilità*: questa proprietà è unica AWS SAM e non ha un CloudFormation equivalente.
`DisableExecuteApiEndpoint`
Speciifica se i client possono richiamare l'API HTTP utilizzando l'endpoint predefinito`execute-api`. `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 l'API, disabilita l'endpoint predefinito.
Per utilizzare questa proprietà, è necessario specificare la `DefinitionBody` proprietà anziché la `DefinitionUri` proprietà o definire `x-amazon-apigateway-endpoint-configuration` con `disableExecuteApiEndpoint` nella definizione OpenAPI.
*Tipo*: Booleano
*Obbligatorio:* no
*CloudFormation compatibilità*: Questa proprietà è simile alla `[ DisableExecuteApiEndpoint](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-disableexecuteapiendpoint)` proprietà di una `AWS::ApiGatewayV2::Api` risorsa. Viene passato direttamente alla `disableExecuteApiEndpoint` proprietà di un'`[ x-amazon-apigateway-endpoint-configuration](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-endpoint-configuration.html)`estensione, che viene aggiunta alla ` [ Body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-body)` proprietà di una `AWS::ApiGatewayV2::Api` risorsa.
`Domain`
Configura un dominio personalizzato per questa API HTTP API Gateway.
*Tipo:* [HttpApiDomainConfiguration](sam-property-httpapi-httpapidomainconfiguration.md)
*Obbligatorio:* no
*CloudFormation compatibilità*: questa proprietà è unica AWS SAM e non ha un CloudFormation equivalente.
`FailOnWarnings`
Speciifica se ripristinare la creazione dell'API HTTP (`true`) o meno (`false`) quando viene rilevato un avviso. Il valore predefinito è `false`.
*Tipo*: Booleano
*Obbligatorio:* no
*CloudFormation compatibilità*: questa proprietà viene passata direttamente alla `[FailOnWarnings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-failonwarnings)` proprietà di una `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 il `title` campo. I seguenti scenari genereranno un errore:
+ La `DefinitionBody` proprietà viene specificata con il `title` campo impostato nella definizione di Open API: ciò genera un conflitto del `title` campo che AWS SAM non verrà risolto.
+ La `DefinitionUri` proprietà è specificata: AWS SAM non modificherà una definizione di Open API recuperata da Amazon S3.
▬*Tipo:* stringa
*Obbligatorio:* no
*CloudFormation compatibilità*: questa proprietà è unica AWS SAM e non ha un CloudFormation equivalente.
`PropagateTags`
Indica se passare o meno i tag dalla `Tags` proprietà alle risorse [AWS::Serverless::HttpApi](sam-specification-generated-resources-httpapi.md) generate. `True`Specificate di propagare i tag nelle risorse generate.
*Tipo*: Booleano
*Obbligatorio:* no
*Default*: `False`
*CloudFormation compatibilità*: questa proprietà è unica AWS SAM e non ha un CloudFormation equivalente.
`RouteSettings`
Le impostazioni del percorso, per percorso, per questa API HTTP. Per ulteriori informazioni, consulta [Working with routes for HTTP APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-routes.html) nella *API Gateway Developer Guide*.
*Tipo:* [RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)
*Obbligatorio:* no
*CloudFormation compatibilità*: questa proprietà viene passata direttamente alla `[RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)` proprietà di una `AWS::ApiGatewayV2::Stage` risorsa.
`StageName`
Il nome della fase API. Se non viene specificato alcun nome, AWS SAM utilizza lo `$default` stage di API Gateway.
▬*Tipo:* stringa
*Obbligatorio:* no
*Predefinito*: \$1default
*CloudFormation compatibilità*: questa proprietà viene passata direttamente alla `[StageName](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-stagename)` proprietà di una `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-.\$1\$1:/? \$1&=,] \$1.
*Type*: [Json](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-stagevariables)
*Obbligatorio:* no
*CloudFormation compatibilità*: questa proprietà viene passata direttamente alla `[StageVariables](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-stagevariables)` proprietà di una `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.
*Tipo*: Mappa
*Obbligatorio:* no
*CloudFormation compatibilità*: questa proprietà è unica AWS SAM e non ha un CloudFormation equivalente.
*Note aggiuntive*: La `Tags` proprietà richiede di AWS SAM modificare la definizione di OpenAPI, quindi i tag vengono aggiunti solo se la `DefinitionBody` proprietà è specificata, non viene aggiunto alcun tag se la proprietà è specificata. `DefinitionUri` AWS SAM aggiunge automaticamente un tag. `httpapi:createdBy:SAM` I tag vengono aggiunti anche alla `AWS::ApiGatewayV2::Stage` risorsa e alla `AWS::ApiGatewayV2::DomainName` risorsa (se `DomainName` specificato).
## Valori restituiti
### Ref
Quando si passa l'ID logico di questa risorsa alla `Ref` funzione intrinseca, `Ref` restituisce l'ID API della `AWS::ApiGatewayV2::Api` risorsa sottostante, ad esempio. `a1bcdef2gh`
Per ulteriori informazioni sull'uso della `Ref` funzione, consulta [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html)la Guida per l'*AWS CloudFormation utente*.
## 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 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.
Tieni presente che AWS SAM compila tutte le integrazioni Lambda mancanti HttpApi per gli eventi che fanno riferimento a questa API HTTP. AWS SAM aggiunge anche eventuali percorsi mancanti a cui fanno riferimento gli HttpApi 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 API HTTP e configurazioni di 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
```