Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.
# AWS::Serverless::HttpApi
Erstellt eine Amazon API Gateway Gateway-HTTP-API, mit der Sie RESTful APIs mit geringerer Latenz und geringeren Kosten als REST erstellen können APIs. Weitere Informationen finden Sie unter [Working with HTTP APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api.html) im *API Gateway Developer Guide*.
Wir empfehlen, CloudFormation Hooks oder IAM-Richtlinien zu verwenden, um zu überprüfen, ob an API-Gateway-Ressourcen Autorisatoren angehängt sind, um den Zugriff darauf zu kontrollieren.
Weitere Informationen zur Verwendung von CloudFormation Hooks finden Sie unter [Hooks registrieren](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/registering-hook-python.html) im *CloudFormation CLI-Benutzerhandbuch* und im [apigw-enforce-authorizer](https://github.com/aws-cloudformation/aws-cloudformation-samples/tree/main/hooks/python-hooks/apigw-enforce-authorizer/) GitHub Repository.
Weitere Informationen zur Verwendung von IAM-Richtlinien finden Sie unter [Erfordern, dass API-Routen autorisiert sind](https://docs.aws.amazon.com/apigateway/latest/developerguide/security_iam_id-based-policy-examples.html#security_iam_id-based-policy-examples-require-authorization) im *API Gateway Developer Guide*.
**Anmerkung**
Bei der Bereitstellung auf werden AWS CloudFormation Ihre AWS SAM Ressourcen in Ressourcen umgewandelt CloudFormation . AWS SAM Weitere Informationen finden Sie unter [Generierte CloudFormation Ressourcen für AWS SAM](sam-specification-generated-resources.md).
## Syntax
Verwenden Sie die folgende Syntax, um diese Entität in Ihrer Vorlage AWS Serverless Application Model (AWS SAM) zu deklarieren.
### 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
```
## Eigenschaften
`AccessLogSettings`
Die Einstellungen für die Zugriffsprotokollierung in einer Phase.
*Typ:* [AccessLogSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-accesslogsettings)
*Required*: No
*CloudFormation Kompatibilität*: Diese Eigenschaft wird direkt an die `[AccessLogSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-accesslogsettings)` Eigenschaft einer `AWS::ApiGatewayV2::Stage` Ressource übergeben.
`Auth`
Konfiguriert die Autorisierung für die Steuerung des Zugriffs auf Ihre API Gateway Gateway-HTTP-API.
Weitere Informationen finden Sie unter [Steuern des Zugriffs auf HTTP APIs mit JWT-Autorisierern](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-jwt-authorizer.html) im *API Gateway* Developer Guide.
*Typ:* [HttpApiAuth](sam-property-httpapi-httpapiauth.md)
*Required*: No
*CloudFormation Kompatibilität*: Diese Eigenschaft ist einzigartig für AWS SAM und hat kein Äquivalent. CloudFormation
`CorsConfiguration`
Verwaltet Cross-Origin Resource Sharing (CORS) für Ihr gesamtes API-Gateway-HTTP. APIs Geben Sie die Domäne, die zugelassen werden soll, als Zeichenfolge an, oder geben Sie ein Objekt an`HttpApiCorsConfiguration`. Beachten Sie, dass CORS Ihre OpenAPI-Definition ändern muss AWS SAM , sodass CORS nur funktioniert, wenn die `DefinitionBody` Eigenschaft angegeben ist.
Weitere Informationen finden Sie unter [Konfiguration von CORS für eine HTTP-API im API](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-cors.html) *Gateway Developer Guide*.
Wenn sowohl in einer OpenAPI-Definition als auch auf Eigenschaftsebene festgelegt `CorsConfiguration` ist, werden beide Konfigurationsquellen AWS SAM zusammengeführt, wobei die Eigenschaften Vorrang haben. Wenn diese Eigenschaft auf gesetzt ist`true`, sind alle Ursprünge zulässig.
*Typ*: Zeichenfolge \$1 [HttpApiCorsConfiguration](sam-property-httpapi-httpapicorsconfiguration.md)
*Required*: No
*CloudFormation Kompatibilität*: Diese Eigenschaft ist einzigartig für AWS SAM und hat kein CloudFormation Äquivalent.
`DefaultRouteSettings`
Die Standardrouteneinstellungen für diese HTTP-API. Diese Einstellungen gelten für alle Routen, sofern sie nicht durch die `RouteSettings` Eigenschaft für bestimmte Routen außer Kraft gesetzt werden.
*Typ:* [RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)
*Required*: No
*CloudFormation Kompatibilität*: Diese Eigenschaft wird direkt an die `[RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)` Eigenschaft einer `AWS::ApiGatewayV2::Stage` Ressource übergeben.
`DefinitionBody`
Die OpenAPI-Definition, die Ihre HTTP-API beschreibt. Wenn Sie a `DefinitionUri` oder a nicht angeben`DefinitionBody`, AWS SAM generiert es auf der Grundlage Ihrer Vorlagenkonfiguration eine `DefinitionBody` für Sie.
*Type*: JSON
*Required*: No
*CloudFormation Kompatibilität*: Diese Eigenschaft ähnelt der `[Body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-body)` Eigenschaft einer `AWS::ApiGatewayV2::Api` Ressource. Wenn bestimmte Eigenschaften angegeben sind, AWS SAM kann Inhalt in die Datei eingefügt oder geändert werden, `DefinitionBody` bevor sie an sie übergeben CloudFormation werden. Zu den Eigenschaften gehören ein `EventSource` Typ `Auth` und ein Typ HttpApi für eine entsprechende `AWS::Serverless::Function` Ressource.
`DefinitionUri`
Der Amazon Simple Storage Service (Amazon S3) -URI, der lokale Dateipfad oder das Speicherortobjekt der OpenAPI-Definition, die die HTTP-API definiert. Das Amazon S3 S3-Objekt, auf das diese Eigenschaft verweist, muss eine gültige OpenAPI-Definitionsdatei sein. Wenn Sie a nicht angeben `DefinitionUri` oder a angegeben `DefinitionBody` sind, AWS SAM generiert es eine `DefinitionBody` für Sie auf der Grundlage Ihrer Vorlagenkonfiguration.
Wenn Sie einen lokalen Dateipfad angeben, muss die Vorlage den Workflow durchlaufen, der den `sam package` Befehl `sam deploy` oder enthält, damit die Definition ordnungsgemäß transformiert wird.
Systeminterne Funktionen werden in externen OpenApi Definitionsdateien, auf die Sie verweisen, nicht unterstützt. `DefinitionUri` [Um eine OpenApi Definition in die Vorlage zu importieren, verwenden Sie die `DefinitionBody` Eigenschaft zusammen mit der Include-Transformation.](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/create-reusable-transform-function-snippets-and-add-to-your-template-with-aws-include-transform.html)
*Typ*: Zeichenfolge \$1 [HttpApiDefinition](sam-property-httpapi-httpapidefinition.md)
*Required*: No
*CloudFormation Kompatibilität*: Diese Eigenschaft ähnelt der `[BodyS3Location](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-bodys3location)` Eigenschaft einer `AWS::ApiGatewayV2::Api` Ressource. Die verschachtelten Amazon S3 S3-Eigenschaften sind unterschiedlich benannt.
`Description`
Die Beschreibung der HTTP-API-Ressource.
Wenn Sie angeben`Description`, AWS SAM wird die OpenApi Definition der HTTP-API-Ressource geändert, indem das `description` Feld festgelegt wird. Die folgenden Szenarien führen zu einem Fehler:
+ Die `DefinitionBody` Eigenschaft wird mit dem in der Open API-Definition festgelegten `description` Feld angegeben. Dies führt zu einem Konflikt im `description` Feld, der AWS SAM nicht gelöst werden kann.
+ Die `DefinitionUri` Eigenschaft ist angegeben — ändert AWS SAM keine Open-API-Definition, die von Amazon S3 abgerufen wird.
*Typ:* Zeichenfolge
*Required*: No
*CloudFormation Kompatibilität*: Diese Eigenschaft ist einzigartig für AWS SAM und hat kein CloudFormation Äquivalent.
`DisableExecuteApiEndpoint`
Gibt an, ob Clients Ihre HTTP-API mithilfe des `execute-api` Standardendpunkts `https://{api_id}.execute-api.{region}.amazonaws.com` aufrufen können. Standardmäßig können Kunden Ihre API mit dem standardmäßigen -Endpunkt aufrufen. Um zu verlangen, dass Clients nur einen benutzerdefinierten Domainnamen verwenden, um Ihre API aufzurufen, deaktivieren Sie den Standardendpunkt.
Um diese Eigenschaft zu verwenden, müssen Sie `disableExecuteApiEndpoint` in Ihrer OpenAPI-Definition die `DefinitionBody` `DefinitionUri` Eigenschaft anstelle der Eigenschaft angeben oder `x-amazon-apigateway-endpoint-configuration` mit definieren.
*Typ*: Boolesch
*Required*: No
*CloudFormation Kompatibilität*: Diese Eigenschaft ähnelt der `[ DisableExecuteApiEndpoint](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-disableexecuteapiendpoint)` Eigenschaft einer `AWS::ApiGatewayV2::Api` Ressource. Sie wird direkt an die `disableExecuteApiEndpoint` Eigenschaft einer `[ x-amazon-apigateway-endpoint-configuration](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-endpoint-configuration.html)` Erweiterung übergeben, die der ` [ Body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-body)` Eigenschaft einer `AWS::ApiGatewayV2::Api` Ressource hinzugefügt wird.
`Domain`
Konfiguriert eine benutzerdefinierte Domain für diese API Gateway Gateway-HTTP-API.
*Typ:* [HttpApiDomainConfiguration](sam-property-httpapi-httpapidomainconfiguration.md)
*Required*: No
*CloudFormation Kompatibilität*: Diese Eigenschaft ist einzigartig für AWS SAM und hat kein CloudFormation Äquivalent.
`FailOnWarnings`
Gibt an, ob die HTTP-API-Erstellung rückgängig gemacht werden soll (`true`) oder nicht (`false`), wenn eine Warnung auftritt. Der Standardwert ist `false`.
*Typ*: Boolesch
*Required*: No
*CloudFormation Kompatibilität*: Diese Eigenschaft wird direkt an die `[FailOnWarnings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-failonwarnings)` Eigenschaft einer `AWS::ApiGatewayV2::Api` Ressource übergeben.
`Name`
Der Name der HTTP-API-Ressource.
Wenn Sie angeben`Name`, AWS SAM wird die OpenAPI-Definition der HTTP-API-Ressource geändert, indem das `title` Feld festgelegt wird. Die folgenden Szenarien führen zu einem Fehler:
+ Die `DefinitionBody` Eigenschaft wird mit dem in der Open API-Definition festgelegten `title` Feld angegeben. Dies führt zu einem Konflikt im `title` Feld, der AWS SAM nicht gelöst werden kann.
+ Die `DefinitionUri` Eigenschaft ist angegeben — ändert AWS SAM keine Open-API-Definition, die von Amazon S3 abgerufen wird.
*Typ:* Zeichenfolge
*Required*: No
*CloudFormation Kompatibilität*: Diese Eigenschaft ist einzigartig für AWS SAM und hat kein CloudFormation Äquivalent.
`PropagateTags`
Geben Sie an, ob Tags von der `Tags` Eigenschaft an Ihre [AWS::Serverless::HttpApi](sam-specification-generated-resources-httpapi.md) generierten Ressourcen weitergegeben werden sollen oder nicht. Geben Sie `True` an, dass Tags in Ihren generierten Ressourcen verbreitet werden sollen.
*Typ*: Boolesch
*Required*: No
*Standardwert*: `False`
*CloudFormation Kompatibilität*: Diese Eigenschaft ist einzigartig für AWS SAM und hat kein CloudFormation Äquivalent.
`RouteSettings`
Die Routeneinstellungen pro Route für diese HTTP-API. Weitere Informationen finden Sie unter [Working with routes for HTTP APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-routes.html) im *API Gateway Developer Guide*.
*Typ:* [RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)
*Required*: No
*CloudFormation Kompatibilität*: Diese Eigenschaft wird direkt an die `[RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)` Eigenschaft einer `AWS::ApiGatewayV2::Stage` Ressource übergeben.
`StageName`
Der Name der API-Stufe. Wenn kein Name angegeben ist, wird der `$default` Stagingbereich von API Gateway AWS SAM verwendet.
*Typ:* Zeichenfolge
*Required*: No
*Standard*: \$1default
*CloudFormation Kompatibilität*: Diese Eigenschaft wird direkt an die `[StageName](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-stagename)` Eigenschaft einer `AWS::ApiGatewayV2::Stage` Ressource übergeben.
`StageVariables`
Eine Zuweisung, welche die Stufenvariablen definiert. Variablennamen können alphanumerische Zeichen und Unterstriche enthalten. Die Werte müssen mit [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)
*Required*: No
*CloudFormation Kompatibilität*: Diese Eigenschaft wird direkt an die `[StageVariables](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-stagevariables)` Eigenschaft einer `AWS::ApiGatewayV2::Stage` Ressource übergeben.
`Tags`
Eine Zuordnung (Zeichenfolge zu Zeichenfolge), die die Tags angibt, die zu diesem API-Gateway-Schritt hinzugefügt werden sollen. Schlüssel können 1 bis 128 Unicode-Zeichen lang sein und dürfen das Präfix nicht enthalten`aws:`. Sie können eines der folgenden Zeichen verwenden: Unicode-Zeichen, Ziffern, Leerraum, `_`, `.`, `/`, `=`, `+` und `-`. Werte können 1 bis 256 Unicode-Zeichen lang sein.
*Typ*: Karte
*Required*: No
*CloudFormation Kompatibilität*: Diese Eigenschaft ist einzigartig für AWS SAM und hat kein CloudFormation Äquivalent.
*Zusätzliche Hinweise*: Die `Tags` Eigenschaft erfordert eine AWS SAM Änderung Ihrer OpenAPI-Definition, sodass Tags nur hinzugefügt werden, wenn die `DefinitionBody` Eigenschaft angegeben ist — es werden keine Tags hinzugefügt, wenn die Eigenschaft angegeben ist. `DefinitionUri` AWS SAM fügt automatisch ein Tag hinzu. `httpapi:createdBy:SAM` Der `AWS::ApiGatewayV2::Stage` Ressource und der `AWS::ApiGatewayV2::DomainName` Ressource (falls `DomainName` angegeben) werden auch Tags hinzugefügt.
## Rückgabewerte
### Punkt
Wenn Sie die logische ID dieser Ressource an die systeminterne `Ref` Funktion übergeben, wird die API-ID der zugrunde liegenden `AWS::ApiGatewayV2::Api` Ressource `Ref` zurückgegeben, zum Beispiel. `a1bcdef2gh`
Weitere Informationen zur Verwendung der `Ref` Funktion finden Sie [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)im *AWS CloudFormation Benutzerhandbuch*.
## Beispiele
### Einfach HttpApi
Das folgende Beispiel zeigt das Minimum, das für die Einrichtung eines HTTP-API-Endpunkts erforderlich ist, der von einer Lambda-Funktion unterstützt wird. In diesem Beispiel wird die standardmäßige HTTP-API verwendet, die AWS SAM erstellt.
#### 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 mit Auth
Das folgende Beispiel zeigt, wie die Autorisierung auf HTTP-API-Endpunkten eingerichtet wird.
#### 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 mit OpenAPI-Definition
Das folgende Beispiel zeigt, wie Sie der Vorlage eine OpenAPI-Definition hinzufügen.
Beachten Sie, dass alle fehlenden Lambda-Integrationen für HttpApi Ereignisse, die auf diese HTTP-API verweisen, AWS SAM ausgefüllt werden. AWS SAM fügt auch alle fehlenden Pfade hinzu, auf die HttpApi Ereignisse verweisen.
#### 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 mit Konfigurationseinstellungen
Das folgende Beispiel zeigt, wie HTTP-API- und Staging-Konfigurationen zur Vorlage hinzugefügt werden.
#### 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
```