Syntax Eigenschaften Rückgabewerte Beispiele

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 GitHub Repository.

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 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 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 anHttpApiCorsConfiguration. 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 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 einer AWS::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 eine DefinitionBody für Sie.

Type: JSON

Required: No

AWS CloudFormation Kompatibilität: Diese Eigenschaft ähnelt der 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 AWS 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.

Typ: Zeichenfolge | HttpApiDefinition

Required: No

AWS CloudFormation Kompatibilität: Diese Eigenschaft ähnelt der 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 angebenDescription, 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

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 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

AWS CloudFormation Kompatibilität: Diese Eigenschaft ähnelt der DisableExecuteApiEndpoint Eigenschaft einer AWS::ApiGatewayV2::Api Ressource. Sie wird direkt an die disableExecuteApiEndpoint Eigenschaft einer x-amazon-apigateway-endpoint-configuration Erweiterung übergeben, die der 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

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 ist false.

Typ: Boolesch

Required: No

AWS CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an die FailOnWarnings Eigenschaft einer AWS::ApiGatewayV2::Api Ressource übergeben.

Name

Der Name der HTTP-API-Ressource.

Wenn Sie angebenName, 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

AWS CloudFormation Kompatibilität: Diese Eigenschaft ist einzigartig für AWS SAM und hat kein AWS CloudFormation Äquivalent.

PropagateTags

Geben Sie an, ob Tags von der Tags Eigenschaft an Ihre AWS::Serverless::HttpApi 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

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 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: $default

AWS CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an die 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-._~:/? #&=,] +.

Type: Json

Required: No

AWS CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an die 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 enthaltenaws:. 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 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 Refim 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

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

Laufzeit

HttpApiAuth