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
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.
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.
YAML
Type: AWS::Serverless::HttpApi Properties: AccessLogSettings:AccessLogSettingsAuth:HttpApiAuthCorsConfiguration:String | HttpApiCorsConfigurationDefaultRouteSettings:RouteSettingsDefinitionBody:JSONDefinitionUri:String | HttpApiDefinitionDescription:StringDisableExecuteApiEndpoint:BooleanDomain:HttpApiDomainConfigurationFailOnWarnings:BooleanName:StringPropagateTags:BooleanRouteSettings:RouteSettingsStageName:StringStageVariables:JsonTags:Map
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
AccessLogSettingsEigentum einesAWS::ApiGatewayV2::StageRessource. -
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
HttpApiCorsConfigurationObjekt. Beachten Sie, dass CORS Folgendes benötigt AWS SAM um Ihre OpenAPI-Definition zu ändern, sodass CORS nur funktioniert, wennDefinitionBodyDie Eigenschaft ist angegeben.Weitere Informationen finden Sie unter CORS für eine HTTP-API konfigurieren in der API Gateway-Entwicklerhandbuch.
AnmerkungWenn
CorsConfigurationist 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 isttrue, 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
RouteSettingsEigenschaft für bestimmte Routen.Typ: RouteSettings
Required: No
CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an den übergeben
RouteSettingsEigentum einesAWS::ApiGatewayV2::StageRessource. -
DefinitionBody -
Die OpenAPI-Definition, die Ihre HTTP-API beschreibt. Wenn Sie keine angeben
DefinitionUrioder einDefinitionBody, AWS SAM generiert eineDefinitionBodyfür Sie basierend auf Ihrer Vorlagenkonfiguration.Type: JSON
Required: No
CloudFormation Kompatibilität: Diese Eigenschaft ähnelt der
BodyEigentum einesAWS::ApiGatewayV2::ApiRessource. Wenn bestimmte Eigenschaften bereitgestellt werden, AWS SAM kann Inhalte in das einfügen oder ändernDefinitionBodybevor es weitergegeben wird an CloudFormation. Zu den Eigenschaften gehörenAuthund einEventSourcevom Typ HttpApi für ein entsprechendesAWS::Serverless::FunctionRessource. -
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
DefinitionUrioder einDefinitionBodysind spezifiziert, AWS SAM generiert eineDefinitionBodyfür Sie basierend auf Ihrer Vorlagenkonfiguration.Wenn Sie einen lokalen Dateipfad angeben, muss die Vorlage den Workflow durchlaufen, der Folgendes beinhaltet
sam deployodersam packageBefehl, 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 SieDefinitionBodyEigentum mit dem Transformation einbeziehen.Typ: Zeichenfolge | HttpApiDefinition
Required: No
CloudFormation Kompatibilität: Diese Eigenschaft ähnelt der
BodyS3LocationEigentum einesAWS::ApiGatewayV2::ApiRessource. 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 derdescriptionFeld. Die folgenden Szenarien führen zu einem Fehler:-
Das
DefinitionBodyDie Eigenschaft wird mit dem angegebendescriptionin der Open-API-Definition festgelegtes Feld — Dies führt zu einem Konflikt zwischendescriptionFeld, das AWS SAM wird sich nicht lösen. -
Das
DefinitionUriDie 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-apiEndpunkthttps://{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
DefinitionBodyEigenschaft stattDefinitionUriEigenschaft oder Definitionx-amazon-apigateway-endpoint-configurationmitdisableExecuteApiEndpointin Ihrer OpenAPI-Definition.Typ: Boolesch
Required: No
CloudFormation Kompatibilität: Diese Eigenschaft ähnelt der
DisableExecuteApiEndpointEigentum einesAWS::ApiGatewayV2::ApiRessource. Es wird direkt an die weitergegebendisableExecuteApiEndpointEigentum einesx-amazon-apigateway-endpoint-configurationErweiterung, die dem hinzugefügt wirdBodyEigentum einesAWS::ApiGatewayV2::ApiRessource. -
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 istfalse.Typ: Boolesch
Required: No
CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an den übergeben
FailOnWarningsEigentum einesAWS::ApiGatewayV2::ApiRessource. Name-
Der Name der HTTP-API-Ressource.
Wenn Sie angeben
Name, AWS SAM ändert die OpenAPI-Definition der HTTP-API-Ressource, indem er das setzttitleFeld. Die folgenden Szenarien führen zu einem Fehler:-
Das
DefinitionBodyDie Eigenschaft wird mit dem angegebentitlein der Open-API-Definition festgelegtes Feld — Dies führt zu einem Konflikt zwischentitleFeld, das AWS SAM wird sich nicht lösen. -
Das
DefinitionUriDie 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.
-
-
Geben Sie an, ob Tags aus dem übergeben werden sollen
TagsEigentum zu Ihrem AWS::Serverless::HttpApi generierte Ressourcen. SpezifizierenTrueum Tags in Ihren generierten Ressourcen zu verbreiten.Typ: Boolesch
Required: No
Standardwert:
FalseCloudFormation 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
RouteSettingsEigentum einesAWS::ApiGatewayV2::StageRessource. -
StageName -
Der Name der API-Stufe. Wenn kein Name angegeben ist, AWS SAM verwendet den
$defaultStage von API Gateway.Typ: Zeichenfolge
Required: No
Standard: $ default
CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an den übergeben
StageNameEigentum einesAWS::ApiGatewayV2::StageRessource. -
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
StageVariablesEigentum einesAWS::ApiGatewayV2::StageRessource. -
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
TagsEigentum erfordert AWS SAM um Ihre OpenAPI-Definition zu ändern, sodass Tags nur hinzugefügt werden, wennDefinitionBodyDie Eigenschaft ist angegeben — es werden keine Tags hinzugefügt, wennDefinitionUriDie Eigenschaft ist angegeben. AWS SAM fügt automatisch eine hinzuhttpapi:createdBy:SAMTag. Schlagworte werden auch dem hinzugefügtAWS::ApiGatewayV2::StageRessource und dieAWS::ApiGatewayV2::DomainNameRessource (wennDomainNameist 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