View a markdown version of this page

AWS::Serverless::HttpApi - AWS Serverless Application Model

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-HTTP-API, mit der Sie RESTful-APIs mit geringerer Latenz und niedrigeren Kosten als REST-APIs erstellen können. Weitere Informationen finden Sie unter Arbeiten mit HTTP-APIs in der API Gateway-Entwicklerhandbuch.

Wir empfehlen, dass Sie verwenden CloudFormation Hooks oder IAM-Richtlinien, um zu überprüfen, ob den API-Gateway-Ressourcen Autorisierer zugeordnet sind, die den Zugriff auf sie kontrollieren.

Für weitere Informationen zur Verwendung CloudFormation Haken, siehe Hooks registrieren in der CloudFormation CLI-Benutzerhandbuch und das apigw-enforce-authorizer GitHub Repositorium.

Weitere Informationen zur Verwendung von IAM-Richtlinien finden Sie unter Erfordern Sie, dass API-Routen autorisiert sind in der API Gateway-Entwicklerhandbuch.

Diese Ressource unterstützt auch die Connectors Ressource Attribute. Weitere Informationen finden Sie unter Verwaltung von Ressourcenberechtigungen mit AWS SAM Steckverbinder.

Anmerkung

Wenn Sie bereitstellen AWS CloudFormation, AWS SAM transformiert deine AWS SAM Ressourcen in CloudFormation Ressourcen. Weitere Informationen finden Sie unter Generiert CloudFormation Ressourcen für AWS SAM.

Syntax

Um diese Entität in Ihrem zu deklarieren AWS Serverless Application Model (AWS SAM) Vorlage, verwenden Sie die folgende Syntax.

Eigenschaften

AccessLogSettings

Die Einstellungen für die Zugriffsprotokollierung in einer Phase.

Typ: AccessLogSettings

Required: No

CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an den übergeben AccessLogSettings Eigentum eines AWS::ApiGatewayV2::Stage Ressource.

Auth

Konfiguriert die Autorisierung für die Steuerung des Zugriffs auf Ihre API 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

CloudFormation Kompatibilität: Diese Eigenschaft ist einzigartig für AWS SAM und hat keine CloudFormation gleichwertig.

CorsConfiguration

Verwaltet Cross-Origin Resource Sharing (CORS) für alle Ihre API-Gateway-HTTP-APIs. Geben Sie die Domain, die zugelassen werden soll, als Zeichenfolge an, oder geben Sie eine HttpApiCorsConfiguration Objekt. Beachten Sie, dass CORS Folgendes benötigt AWS SAM um Ihre OpenAPI-Definition zu ändern, sodass CORS nur funktioniert, wenn DefinitionBody Die Eigenschaft ist angegeben.

Weitere Informationen finden Sie unter CORS für eine HTTP-API konfigurieren in der API Gateway-Entwicklerhandbuch.

Anmerkung

Wenn CorsConfiguration ist sowohl in einer OpenAPI-Definition als auch auf Eigenschaftsebene festgelegt, dann AWS SAM führt beide Konfigurationsquellen zusammen, wobei die Eigenschaften Vorrang haben. Wenn diese Eigenschaft auf gesetzt ist true, dann sind alle Ursprünge zulässig.

Typ: Zeichenfolge | HttpApiCorsConfiguration

Required: No

CloudFormation Kompatibilität: Diese Eigenschaft ist einzigartig für AWS SAM und hat keine CloudFormation gleichwertig.

DefaultRouteSettings

Die Standard-Routeneinstellungen für diese HTTP-API. Diese Einstellungen gelten für alle Routen, sofern sie nicht durch den überschrieben werden RouteSettings Eigenschaft für bestimmte Routen.

Typ: RouteSettings

Required: No

CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an den übergeben RouteSettings Eigentum eines AWS::ApiGatewayV2::Stage Ressource.

DefinitionBody

Die OpenAPI-Definition, die Ihre HTTP-API beschreibt. Wenn Sie keine angeben DefinitionUri oder ein DefinitionBody, AWS SAM generiert eine DefinitionBody für Sie basierend auf Ihrer Vorlagenkonfiguration.

Type: JSON

Required: No

CloudFormation Kompatibilität: Diese Eigenschaft ähnelt der Body Eigentum eines AWS::ApiGatewayV2::Api Ressource. Wenn bestimmte Eigenschaften bereitgestellt werden, AWS SAM kann Inhalte in das einfügen oder ändern DefinitionBody bevor es weitergegeben wird an CloudFormation. Zu den Eigenschaften gehören Auth und ein EventSource vom Typ HttpApi für ein entsprechendes AWS::Serverless::Function Ressource.

DefinitionUri

Die Amazon Simple Storage Service (Amazon S3) -URI, der lokale Dateipfad oder das Standortobjekt der OpenAPI-Definition, die die HTTP-API definiert. Das Amazon S3-Objekt, auf das diese Eigenschaft verweist, muss eine gültige OpenAPI-Definitionsdatei sein. Wenn Sie keinen angeben DefinitionUri oder ein DefinitionBody sind spezifiziert, AWS SAM generiert eine DefinitionBody für Sie basierend auf Ihrer Vorlagenkonfiguration.

Wenn Sie einen lokalen Dateipfad angeben, muss die Vorlage den Workflow durchlaufen, der Folgendes beinhaltet sam deploy oder sam package Befehl, damit die Definition richtig transformiert wird.

Intrinsische Funktionen werden in externen Versionen nicht unterstützt OpenApi Definitionsdateien, mit denen Sie referenzieren DefinitionUri. Um eine zu importieren OpenApi Definition in die Vorlage verwenden Sie DefinitionBody Eigentum mit dem Transformation einbeziehen.

Typ: Zeichenfolge | HttpApiDefinition

Required: No

CloudFormation Kompatibilität: Diese Eigenschaft ähnelt der BodyS3Location Eigentum eines AWS::ApiGatewayV2::Api Ressource. Die verschachtelten Amazon S3-Eigenschaften sind unterschiedlich benannt.

Description

Die Beschreibung der HTTP-API-Ressource.

Wenn Sie angeben Description, AWS SAM wird die HTTP-API-Ressource ändern OpenApi Definition durch Setzen der description Feld. Die folgenden Szenarien führen zu einem Fehler:

  • Das DefinitionBody Die Eigenschaft wird mit dem angegeben description in der Open-API-Definition festgelegtes Feld — Dies führt zu einem Konflikt zwischen description Feld, das AWS SAM wird sich nicht lösen.

  • Das DefinitionUri Die Immobilie ist spezifiziert — AWS SAM ändert 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 keine CloudFormation gleichwertig.

DisableExecuteApiEndpoint

Gibt an, ob Clients Ihre HTTP-API aufrufen können, indem sie die Standardeinstellung verwenden execute-api Endpunkt https://{api_id}.execute-api.{region}.amazonaws.com. Standardmäßig können Kunden Ihre API mit dem standardmäßigen -Endpunkt aufrufen. Um zu verlangen, dass Kunden nur einen benutzerdefinierten Domainnamen verwenden, um Ihre API aufzurufen, deaktivieren Sie den Standard-Endpunkt.

Um diese Eigenschaft zu verwenden, müssen Sie Folgendes angeben DefinitionBody Eigenschaft statt DefinitionUri Eigenschaft oder Definition x-amazon-apigateway-endpoint-configuration mit disableExecuteApiEndpoint in Ihrer OpenAPI-Definition.

Typ: Boolesch

Required: No

CloudFormation Kompatibilität: Diese Eigenschaft ähnelt der DisableExecuteApiEndpoint Eigentum eines AWS::ApiGatewayV2::Api Ressource. Es wird direkt an die weitergegeben disableExecuteApiEndpoint Eigentum eines x-amazon-apigateway-endpoint-configuration Erweiterung, die dem hinzugefügt wird Body Eigentum eines AWS::ApiGatewayV2::Api Ressource.

Domain

Konfiguriert eine benutzerdefinierte Domain für diese API Gateway-HTTP-API.

Typ: HttpApiDomainConfiguration

Required: No

CloudFormation Kompatibilität: Diese Eigenschaft ist einzigartig für AWS SAM und hat keine CloudFormation gleichwertig.

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 den übergeben FailOnWarnings Eigentum eines AWS::ApiGatewayV2::Api Ressource.

Name

Der Name der HTTP-API-Ressource.

Wenn Sie angeben Name, AWS SAM ändert die OpenAPI-Definition der HTTP-API-Ressource, indem er das setzt title Feld. Die folgenden Szenarien führen zu einem Fehler:

  • Das DefinitionBody Die Eigenschaft wird mit dem angegeben title in der Open-API-Definition festgelegtes Feld — Dies führt zu einem Konflikt zwischen title Feld, das AWS SAM wird sich nicht lösen.

  • Das DefinitionUri Die Immobilie ist spezifiziert — AWS SAM ändert 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 keine CloudFormation gleichwertig.

PropagateTags

Geben Sie an, ob Tags aus dem übergeben werden sollen Tags Eigentum zu Ihrem AWS::Serverless::HttpApi generierte Ressourcen. Spezifizieren True um Tags in Ihren generierten Ressourcen zu verbreiten.

Typ: Boolesch

Required: No

Standardwert: False

CloudFormation Kompatibilität: Diese Eigenschaft ist einzigartig für AWS SAM und hat keine CloudFormation gleichwertig.

RouteSettings

Die Routeneinstellungen pro Route für diese HTTP-API. Weitere Informationen finden Sie unter Arbeiten mit Routen für HTTP-APIs in der API Gateway-Entwicklerhandbuch.

Typ: RouteSettings

Required: No

CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an den übergeben RouteSettings Eigentum eines AWS::ApiGatewayV2::Stage Ressource.

StageName

Der Name der API-Stufe. Wenn kein Name angegeben ist, AWS SAM verwendet den $default Stage von API Gateway.

Typ: Zeichenfolge

Required: No

Standard: $ default

CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an den übergeben StageName Eigentum eines AWS::ApiGatewayV2::Stage Ressource.

StageVariables

Eine Zuweisung, welche die Stufenvariablen definiert. Variablennamen können alphanumerische Zeichen und Unterstriche enthalten. Die Werte müssen mit [übereinstimmenA-Za-z0-9-._~:/? #&=,] +.

Type: Json

Required: No

CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an den übergeben StageVariables Eigentum eines AWS::ApiGatewayV2::Stage Ressource.

Tags

Eine Map (von 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: Landkarte

Required: No

CloudFormation Kompatibilität: Diese Eigenschaft ist einzigartig für AWS SAM und hat keine CloudFormation gleichwertig.

Zusätzliche Hinweise: Die Tags Eigentum erfordert AWS SAM um Ihre OpenAPI-Definition zu ändern, sodass Tags nur hinzugefügt werden, wenn DefinitionBody Die Eigenschaft ist angegeben — es werden keine Tags hinzugefügt, wenn DefinitionUri Die Eigenschaft ist angegeben. AWS SAM fügt automatisch eine hinzu httpapi:createdBy:SAM Tag. Schlagworte werden auch dem hinzugefügt AWS::ApiGatewayV2::Stage Ressource und die AWS::ApiGatewayV2::DomainName Ressource (wenn DomainName ist angegeben).

Rückgabewerte

Punkt

Wenn Sie die logische ID dieser Ressource an die intrinsische übergeben Ref Funktion, Ref gibt die API-ID des Basiswerts zurück AWS::ApiGatewayV2::Api Ressource, zum Beispiel a1bcdef2gh.

Für weitere Informationen zur Verwendung der Ref Funktion, siehe Ref in der AWS CloudFormation Benutzerleitfaden.

Beispiele

Einfach HttpApi

Das folgende Beispiel zeigt das Minimum, das für die Einrichtung eines HTTP-API-Endpunkts erforderlich ist, der von einer Lambda-Ereignisfunktion unterstützt wird. In diesem Beispiel wird die Standard-HTTP-API verwendet 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 für HTTP-API-Endpunkte 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 das AWS SAM füllt alle fehlenden Lambda-Integrationen aus für HttpApi Ereignisse, die auf diese HTTP-API verweisen. AWS SAM fügt auch alle fehlenden Pfade hinzu HttpApi Referenz für Ereignisse.

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