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-APIs erstellen können. Weitere Informationen finden Sie unter Arbeiten mit HTTP-APIs im API Gateway Developer Guide.
Wir empfehlen, AWS 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 AWS CloudFormation Hooks finden Sie unter Hooks registrieren im AWS CloudFormation CLI-Benutzerhandbuch und im apigw-enforce-authorizer
Weitere Informationen zur Verwendung von IAM-Richtlinien finden Sie unter Erfordern, dass API-Routen autorisiert sind im API Gateway Developer Guide.
Anmerkung
Bei der Bereitstellung auf werden AWS CloudFormation Ihre AWS SAM Ressourcen in Ressourcen umgewandelt AWS CloudFormation . AWS SAM Weitere Informationen finden Sie unter Generierte AWS CloudFormation Ressourcen für AWS SAM.
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:
AccessLogSettings
Auth:HttpApiAuth
CorsConfiguration:String | HttpApiCorsConfiguration
DefaultRouteSettings:RouteSettings
DefinitionBody:JSON
DefinitionUri:String | HttpApiDefinition
Description:String
DisableExecuteApiEndpoint:Boolean
Domain:HttpApiDomainConfiguration
FailOnWarnings:Boolean
Name:String
PropagateTags:Boolean
RouteSettings:RouteSettings
StageName:String
StageVariables:Json
Tags:Map
Eigenschaften
-
AccessLogSettings
-
Die Einstellungen für die Zugriffsprotokollierung in einer Phase.
Typ: AccessLogSettings
Required: No
AWS CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an die
AccessLogSettings
Eigenschaft einerAWS::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 Controlling access to HTTP APIs with JWT authorizers (Zugriffskontrolle auf HTTP-APIs mit JWT-Autorisierern) im Entwicklerhandbuch von API Gateway.
Typ: HttpApiAuth
Required: No
AWS CloudFormation Kompatibilität: Diese Eigenschaft ist einzigartig für AWS SAM und hat kein AWS CloudFormation Äquivalent.
-
CorsConfiguration
-
Verwaltet Cross-Origin Resource Sharing (CORS) für all Ihre API Gateway 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 dieDefinitionBody
Eigenschaft angegeben ist.Weitere Informationen finden Sie unter Konfiguration von CORS für eine HTTP-API im API Gateway Developer Guide.
Anmerkung
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 isttrue
, sind alle Ursprünge zulässig.Typ: Zeichenfolge | HttpApiCorsConfiguration
Required: No
AWS CloudFormation Kompatibilität: Diese Eigenschaft ist einzigartig für AWS SAM und hat kein AWS 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
Required: No
AWS CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an die
RouteSettings
Eigenschaft einerAWS::ApiGatewayV2::Stage
Ressource übergeben. -
DefinitionBody
-
Die OpenAPI-Definition, die Ihre HTTP-API beschreibt. Wenn Sie a
DefinitionUri
oder a nicht angebenDefinitionBody
, AWS SAM generiert es auf der Grundlage Ihrer Vorlagenkonfiguration eineDefinitionBody
für Sie.Type: JSON
Required: No
AWS CloudFormation Kompatibilität: Diese Eigenschaft ähnelt der
Body
Eigenschaft einerAWS::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 AWS CloudFormation werden. Zu den Eigenschaften gehören einEventSource
TypAuth
und ein Typ HttpApi für eine entsprechendeAWS::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 angegebenDefinitionBody
sind, AWS SAM generiert es eineDefinitionBody
für Sie auf der Grundlage Ihrer Vorlagenkonfiguration.Wenn Sie einen lokalen Dateipfad angeben, muss die Vorlage den Workflow durchlaufen, der den
sam package
Befehlsam 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 dieDefinitionBody
Eigenschaft zusammen mit der Include-Transformation.Typ: Zeichenfolge | HttpApiDefinition
Required: No
AWS CloudFormation Kompatibilität: Diese Eigenschaft ähnelt der
BodyS3Location
Eigenschaft einerAWS::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 dasdescription
Feld festgelegt wird. Die folgenden Szenarien führen zu einem Fehler:-
Die
DefinitionBody
Eigenschaft wird mit dem in der Open API-Definition festgelegtendescription
Feld angegeben. Dies führt zu einem Konflikt imdescription
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
AWS CloudFormation Kompatibilität: Diese Eigenschaft ist einzigartig für AWS SAM und hat kein AWS CloudFormation Äquivalent.
-
-
DisableExecuteApiEndpoint
-
Gibt an, ob Clients Ihre HTTP-API mithilfe des
execute-api
Standardendpunktshttps://{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 dieDefinitionBody
DefinitionUri
Eigenschaft anstelle der Eigenschaft angeben oderx-amazon-apigateway-endpoint-configuration
mit definieren.Typ: Boolesch
Required: No
AWS CloudFormation Kompatibilität: Diese Eigenschaft ähnelt der
DisableExecuteApiEndpoint
Eigenschaft einerAWS::ApiGatewayV2::Api
Ressource. Sie wird direkt an diedisableExecuteApiEndpoint
Eigenschaft einerx-amazon-apigateway-endpoint-configuration
Erweiterung übergeben, die derBody
Eigenschaft einerAWS::ApiGatewayV2::Api
Ressource hinzugefügt wird. -
Domain
-
Konfiguriert eine benutzerdefinierte Domain für diese API Gateway Gateway-HTTP-API.
Typ: HttpApiDomainConfiguration
Required: No
AWS CloudFormation Kompatibilität: Diese Eigenschaft ist einzigartig für AWS SAM und hat kein AWS 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 istfalse
.Typ: Boolesch
Required: No
AWS CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an die
FailOnWarnings
Eigenschaft einerAWS::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 dastitle
Feld festgelegt wird. Die folgenden Szenarien führen zu einem Fehler:-
Die
DefinitionBody
Eigenschaft wird mit dem in der Open API-Definition festgelegtentitle
Feld angegeben. Dies führt zu einem Konflikt imtitle
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
AWS CloudFormation Kompatibilität: Diese Eigenschaft ist einzigartig für AWS SAM und hat kein AWS CloudFormation Äquivalent.
-
-
Geben Sie an, ob Tags von der
Tags
Eigenschaft an Ihre AWS::Serverless::HttpApi generierten Ressourcen weitergegeben werden sollen oder nicht. Geben SieTrue
an, dass Tags in Ihren generierten Ressourcen verbreitet werden sollen.Typ: Boolesch
Required: No
Standardwert:
False
AWS CloudFormation Kompatibilität: Diese Eigenschaft ist einzigartig für AWS SAM und hat kein AWS CloudFormation Äquivalent.
-
RouteSettings
-
Die Routeneinstellungen pro Route für diese HTTP-API. Weitere Informationen finden Sie unter Arbeiten mit Routen für HTTP-APIs im API Gateway Developer Guide.
Typ: RouteSettings
Required: No
AWS CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an die
RouteSettings
Eigenschaft einerAWS::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: $default
AWS CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an die
StageName
Eigenschaft einerAWS::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-._~:/? #&=,] +.
Type: Json
Required: No
AWS CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an die
StageVariables
Eigenschaft einerAWS::ApiGatewayV2::Stage
Ressource übergeben. -
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
AWS CloudFormation Kompatibilität: Diese Eigenschaft ist einzigartig für AWS SAM und hat kein AWS CloudFormation Äquivalent.
Zusätzliche Hinweise: Die
Tags
Eigenschaft erfordert eine AWS SAM Änderung Ihrer OpenAPI-Definition, sodass Tags nur hinzugefügt werden, wenn dieDefinitionBody
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
DerAWS::ApiGatewayV2::Stage
Ressource und derAWS::ApiGatewayV2::DomainName
Ressource (fallsDomainName
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 Ref
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"
HttpApimit 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