AWS::Serverless::Api - AWS Serverless Application Model
SyntaxEigenschaftenRückgabewerteBeispiele

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

Erstellt eine Sammlung von Amazon API Gateway Gateway-Ressourcen und -Methoden, die über HTTPS-Endpunkte aufgerufen werden können.

Eine AWS::Serverless::Api Ressource muss nicht explizit zu einer Vorlage für AWS serverlose Anwendungsdefinitionen hinzugefügt werden. Eine Ressource dieses Typs wird implizit aus der Vereinigung von API-Ereignissen erstellt, die für AWS::Serverless::Function Ressourcen definiert sind, die in der Vorlage definiert sind und sich nicht auf eine AWS::Serverless::Api Ressource beziehen.

Eine AWS::Serverless::Api Ressource sollte verwendet werden, um die verwendete API zu definieren und zu dokumentieren OpenApi, was mehr Möglichkeiten bietet, die zugrunde liegenden Amazon API Gateway Gateway-Ressourcen zu konfigurieren.

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 AWS Serverless Application Model (AWS SAM) -Vorlage zu deklarieren.

Eigenschaften

AccessLogSetting

Konfiguriert die Einstellung für das Zugriffsprotokoll für eine Phase.

Typ: AccessLogSetting

Required: No

AWS CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an die AccessLogSetting Eigenschaft einer AWS::ApiGateway::Stage Ressource übergeben.

AlwaysDeploy

Stellt die API immer bereit, auch wenn keine Änderungen an der API festgestellt wurden.

Typ: Boolesch

Required: No

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

ApiKeySourceType

Die Quelle des API-Schlüssels für Messungsanforderungen nach einem Nutzungsplan. Gültige Werte sind HEADER und AUTHORIZER.

Typ: Zeichenfolge

Required: No

AWS CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an die ApiKeySourceType Eigenschaft einer AWS::ApiGateway::RestApi Ressource übergeben.

Auth

Konfigurieren Sie die Autorisierung, um den Zugriff auf Ihre API-Gateway-API zu kontrollieren.

Weitere Informationen zur Konfiguration des Zugriffs mithilfe von AWS SAM finden Sie unterSteuern API Sie den Zugriff mit Ihrer AWS SAM Vorlage.

Typ: ApiAuth

Required: No

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

BinaryMediaTypes

Liste der MIME-Typen, die Ihre API zurückgeben könnte. Verwenden Sie dies, um die binäre Unterstützung für APIs zu aktivieren. Verwenden Sie ~1 anstelle von/in den MIME-Typen.

Typ: Liste

Required: No

AWS CloudFormation Kompatibilität: Diese Eigenschaft ähnelt der BinaryMediaTypes Eigenschaft einer AWS::ApiGateway::RestApi Ressource. Die Liste von BinaryMediaTypes wird sowohl der AWS CloudFormation Ressource als auch dem OpenAPI-Dokument hinzugefügt.

CacheClusterEnabled

Gibt an, ob das Caching für die Phase aktiviert ist. Um Antworten zwischenzuspeichern, müssen Sie auch CachingEnabled auf true unter MethodSettings setzen.

Typ: Boolesch

Required: No

AWS CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an die CacheClusterEnabled Eigenschaft einer AWS::ApiGateway::Stage Ressource übergeben.

CacheClusterSize

Die Cache-Cluster-Größe der Stufe.

Typ: Zeichenfolge

Required: No

AWS CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an die CacheClusterSize Eigenschaft einer AWS::ApiGateway::Stage Ressource übergeben.

CanarySetting

Konfigurieren Sie eine Canary-Einstellung für eine Phase einer regulären Bereitstellung.

Typ: CanarySetting

Required: No

AWS CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an die CanarySetting Eigenschaft einer AWS::ApiGateway::Stage Ressource übergeben.

Cors

Verwalten Sie Cross-Origin Resource Sharing (CORS) für all Ihre API-Gateway-APIs. Geben Sie die Domäne, die zugelassen werden soll, als Zeichenfolge an oder geben Sie ein Wörterbuch mit zusätzlicher Cors-Konfiguration an.

Anmerkung

CORS erfordert eine AWS SAM Änderung Ihrer OpenAPI-Definition. Erstellen Sie eine Inline-OpenAPI-Definition inDefinitionBody, um CORS zu aktivieren.

Weitere Informationen zu CORS finden Sie unter Aktivieren von CORS für eine API-Gateway-REST-API-Ressource im API Gateway Developer Guide.

Typ: Zeichenfolge | CorsConfiguration

Required: No

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

DefinitionBody

OpenAPI-Spezifikation, die Ihre API beschreibt. Wenn DefinitionUri weder noch angegeben DefinitionBody sind, generiert SAM auf der Grundlage Ihrer Vorlagenkonfiguration eine DefinitionBody für Sie.

Verwenden Sie die AWS::Include Transformation, um auf eine lokale OpenAPI Datei zu verweisen, die Ihre API definiert. Weitere Informationen hierzu finden Sie unter Wie werden AWS SAM lokale Dateien hochgeladen.

Type: JSON

Required: No

AWS CloudFormation Kompatibilität: Diese Eigenschaft ähnelt der Body Eigenschaft einer AWS::ApiGateway::RestApi Ressource. Wenn bestimmte Eigenschaften bereitgestellt werden, können Inhalte in die eingefügt oder geändert werden, DefinitionBody bevor sie an sie übergeben werden CloudFormation. Zu den Eigenschaften gehören Auth BinaryMediaTypesCors,GatewayResponses,Models, und eine EventSource vom Typ Api für eine entsprechendeAWS::Serverless::Function.

DefinitionUri

Amazon S3 S3-URI, lokaler Dateipfad oder Speicherortobjekt des OpenAPI-Dokuments, das die API definiert. Das Amazon S3 S3-Objekt, auf das diese Eigenschaft verweist, muss eine gültige OpenAPI-Datei sein. Wenn DefinitionUri weder noch angegeben DefinitionBody sind, generiert SAM auf der Grundlage Ihrer Vorlagenkonfiguration eine DefinitionBody für Sie.

Wenn ein lokaler Dateipfad angegeben wird, 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 Dateien, auf die von verwiesen wird, nicht unterstützt. DefinitionUri Verwenden Sie stattdessen die DefinitionBody Eigenschaft mit der Include-Transformation, um eine OpenApi Definition in die Vorlage zu importieren.

Typ: Zeichenfolge | ApiDefinition

Required: No

AWS CloudFormation Kompatibilität: Diese Eigenschaft ähnelt der BodyS3Location Eigenschaft einer AWS::ApiGateway::RestApi Ressource. Die verschachtelten Amazon S3 S3-Eigenschaften sind unterschiedlich benannt.

Description

Eine Beschreibung der Api-Ressource.

Typ: Zeichenfolge

Required: No

AWS CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an die Description Eigenschaft einer AWS::ApiGateway::RestApi Ressource übergeben.

DisableExecuteApiEndpoint

Gibt an, ob Clients Ihre API mithilfe des execute-api-Standardendpunkts aufrufen können. Standardmäßig können Clients Ihre API mit der Standardeinstellung https://{api_id}.execute-api.{region}.amazonaws.com aufrufen. Wenn Sie erzwingen möchten, dass Kunden einen benutzerdefinierten Domänennamen verwenden, um Ihre API aufzurufen, geben Sie a True.

Typ: Boolesch

Required: No

AWS CloudFormation Kompatibilität: Diese Eigenschaft ähnelt der DisableExecuteApiEndpoint Eigenschaft einer AWS::ApiGateway::RestApi Ressource. Sie wird direkt an die disableExecuteApiEndpoint Eigenschaft einer x-amazon-apigateway-endpoint-configuration Erweiterung übergeben, die der Body Eigenschaft einer AWS::ApiGateway::RestApi Ressource hinzugefügt wird.

Domain

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

Typ: DomainConfiguration

Required: No

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

EndpointConfiguration

Der Endpunkttyp einer REST-API.

Typ: EndpointConfiguration

Required: No

AWS CloudFormation Kompatibilität: Diese Eigenschaft ähnelt der EndpointConfiguration Eigenschaft einer AWS::ApiGateway::RestApi Ressource. Die verschachtelten Konfigurationseigenschaften sind unterschiedlich benannt.

FailOnWarnings

Gibt an, ob die 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::ApiGateway::RestApi Ressource übergeben.

GatewayResponses

Konfiguriert Gateway-Antworten für eine API. Gateway-Antworten sind Antworten, die von API Gateway entweder direkt oder mithilfe von Lambda-Autorisierern zurückgegeben werden. Weitere Informationen finden Sie in der Dokumentation zur Api OpenApi Gateway-Erweiterung für Gateway Responses.

Typ: Karte

Required: No

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

MergeDefinitions

AWS SAM generiert eine OpenAPI Spezifikation aus Ihrer API-Ereignisquelle. Geben Sie true an, dass dies mit der in Ihrer AWS::Serverless::Api Ressource definierten OpenAPI Inline-Spezifikation AWS SAM zusammengeführt werden soll. Geben Sie false an, dass nicht zusammengeführt werden soll.

MergeDefinitionserfordert, dass die DefinitionBody Eigenschaft AWS::Serverless::Api für definiert wird. MergeDefinitionsist nicht kompatibel mit der DefinitionUri Eigenschaft fürAWS::Serverless::Api.

Standardwert: false

Typ: Boolesch

Required: No

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

MethodSettings

Konfiguriert alle Einstellungen für die API-Phase, einschließlich Logging, Metrics, CacheTTL und Throttling.

Typ: Liste von MethodSetting

Required: No

AWS CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an die MethodSettings Eigenschaft einer Ressource übergeben. AWS::ApiGateway::Stage

MinimumCompressionSize

Erlaubt die Komprimierung von Antworttexten auf der Grundlage des Accept-Encoding-Headers des Clients. Die Komprimierung wird ausgelöst, wenn die Größe des Antworttextes größer oder gleich dem konfigurierten Schwellenwert ist. Der maximale Schwellenwert für die Körpergröße beträgt 10 MB (10.485.760 Byte). - Die folgenden Komprimierungstypen werden unterstützt: gzip, deflate und identity.

Typ: Ganzzahl

Required: No

AWS CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an die MinimumCompressionSize Eigenschaft einer Ressource übergeben. AWS::ApiGateway::RestApi

Mode

Diese Eigenschaft gilt nur, wenn Sie OpenAPI zur Definition Ihrer REST-API verwenden. Der Mode bestimmt, wie API Gateway mit Ressourcen-Updates umgeht. Weitere Informationen finden Sie unter Mode-Eigenschaft des AWS::ApiGateway::RestApiRessourcentyps.

Zulässige Werte: overwrite oder merge.

Typ: Zeichenfolge

Required: No

AWS CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an die Mode Eigenschaft einer AWS::ApiGateway::RestApi Ressource übergeben.

Models

Die Schemas, die von Ihren API-Methoden verwendet werden sollen. Diese Schemas können mit JSON oder YAML beschrieben werden. Im Abschnitt Beispiele unten auf dieser Seite finden Sie Beispielmodelle.

Typ: Karte

Required: No

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

Name

Ein Name für die RestApi API-Gateway-Ressource

Typ: Zeichenfolge

Required: No

AWS CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an die Name Eigenschaft einer AWS::ApiGateway::RestApi Ressource übergeben.

OpenApiVersion

Version von OpenApi , die verwendet werden soll. Dies kann entweder 2.0 für die Swagger-Spezifikation oder für eine der OpenApi 3.0-Versionen sein. 3.0.1 Weitere Informationen zu OpenAPI finden Sie in der OpenAPI-Spezifikation.

Anmerkung

AWS SAM erstellt eine Stage, die Stage standardmäßig aufgerufen wird. Wenn Sie diese Eigenschaft auf einen beliebigen gültigen Wert setzen, wird die Erstellung der Phase verhindertStage.

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::Api 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.

StageName

Der Name der Stufe, die API Gateway als erstes Pfadsegment im Aufruf-URI (Uniform Resource Identifier) verwendet.

Um auf die Staging-Ressource zu verweisen, verwenden Sie<api-logical-id>.Stage. Weitere Hinweise zum Verweisen auf Ressourcen, die bei der Angabe einer AWS::Serverless::Api Ressource generiert werden, finden Sie unterAWS CloudFormation Ressourcen, die generiert werdenAWS::Serverless::Api, wenn angegeben. Allgemeine Informationen zu generierten AWS CloudFormation Ressourcen finden Sie unterGenerierte AWS CloudFormation Ressourcen für AWS SAM.

Typ: Zeichenfolge

Erforderlich: Ja

AWS CloudFormation Kompatibilität: Diese Eigenschaft ähnelt der StageName Eigenschaft einer AWS::ApiGateway::Stage Ressource. Es ist in SAM erforderlich, aber nicht in API Gateway

Zusätzliche Hinweise: Die implizite API hat den Stagennamen „Prod“.

Tags

Eine Zuordnung (Zeichenfolge zu Zeichenfolge), die die Tags angibt, die zu diesem API-Gateway-Schritt hinzugefügt werden sollen. Einzelheiten zu gültigen Schlüsseln und Werten für Tags finden Sie unter Resource-Tag im AWS CloudFormation Benutzerhandbuch.

Typ: Karte

Required: No

AWS CloudFormation Kompatibilität: Diese Eigenschaft ähnelt der Tags Eigenschaft einer AWS::ApiGateway::Stage Ressource. Die Tags-Eigenschaft in SAM besteht aus Key:Value-Paaren; darin besteht CloudFormation sie aus einer Liste von Tag-Objekten.

TracingEnabled

Zeigt an, ob aktives Tracing mit X-Ray für die Phase aktiviert ist. Weitere Informationen zu X-Ray finden Sie unter Tracing user requests to REST APIs using X-Ray im API Gateway Developer Guide.

Typ: Boolesch

Required: No

AWS CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an die TracingEnabled Eigenschaft einer AWS::ApiGateway::Stage Ressource übergeben.

Variables

Eine Zuordnung (Zeichenfolge zu Zeichenfolge), die die Stufenvariablen definiert, wobei der Variablenname der Schlüssel und der Variablenwert der Wert ist. Variablennamen sind auf alphanumerische Zeichen beschränkt. Werte müssen dem folgenden regulären Ausdruck entsprechen: [A-Za-z0-9._~:/?#&=,-]+.

Typ: Karte

Required: No

AWS CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an die Variables Eigenschaft einer AWS::ApiGateway::Stage Ressource übergeben.

Rückgabewerte

Punkt

Wenn die logische ID dieser Ressource für die Ref intrinsische Funktion bereitgestellt wird, gibt sie die ID der zugrunde liegenden API-Gateway-API zurück.

Weitere Informationen zur Verwendung der Ref Funktion finden Sie Refim AWS CloudFormation Benutzerhandbuch.

Fn:: GetAtt

Fn::GetAtt gibt einen Wert für ein angegebenes Attribut dieses Typs zurück. Im Folgenden sehen Sie die verfügbaren Attribute und Beispielrückgabewerte.

Weitere Informationen zur Verwendung Fn::GetAtt finden Sie Fn::GetAttim AWS CloudFormation Benutzerhandbuch.

RootResourceId

Die Stamm-Ressourcen-ID für eine RestApi-Ressource, z. B. a0bc123d4e.

Beispiele

SimpleApiExample

Eine Hello AWS SAM World-Vorlagendatei, die eine Lambda-Funktion mit einem API-Endpunkt enthält. Dies ist eine vollständige AWS SAM Vorlagendatei für eine funktionierende serverlose Anwendung.

YAML

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: AWS SAM template with a simple API definition
Resources:
  ApiGatewayApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: prod
  ApiFunction: # Adds a GET method at the root resource via an Api event
    Type: AWS::Serverless::Function
    Properties:
      Events:
        ApiEvent:
          Type: Api
          Properties:
            Path: /
            Method: get
            RestApiId:
              Ref: ApiGatewayApi
      Runtime: python3.10
      Handler: index.handler
      InlineCode: |
        def handler(event, context):
            return {'body': 'Hello World!', 'statusCode': 200}

ApiCorsExample

Ein AWS SAM Vorlagenausschnitt mit einer API, die in einer externen Swagger-Datei definiert ist, zusammen mit Lambda-Integrationen und CORS-Konfigurationen. Dies ist nur ein Teil einer Vorlagendatei, der eine Definition zeigt. AWS SAM AWS::Serverless::Api

YAML

Resources:
  ApiGatewayApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: Prod
      # Allows www.example.com to call these APIs
      # SAM will automatically add AllowMethods with a list of methods for this API
      Cors: "'www.example.com'"
      DefinitionBody: # Pull in an OpenApi definition from S3
        'Fn::Transform':
          Name: 'AWS::Include'
          # Replace "bucket" with your bucket name
          Parameters:
            Location: s3://bucket/swagger.yaml

ApiCognitoAuthExample

Ein AWS SAM Vorlagenausschnitt mit einer API, die Amazon Cognito verwendet, um Anfragen an die API zu autorisieren. Dies ist nur ein Teil einer AWS SAM Vorlagendatei, die eine Definition enthält. AWS::Serverless::Api

YAML

Resources:
  ApiGatewayApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: Prod
      Cors: "'*'"
      Auth:
        DefaultAuthorizer: MyCognitoAuthorizer
        Authorizers:
          MyCognitoAuthorizer:
            UserPoolArn:
              Fn::GetAtt: [MyCognitoUserPool, Arn]

ApiModelsExample

Ein AWS SAM Vorlagenausschnitt mit einer API, die ein Models-Schema enthält. Dies ist nur ein Teil einer AWS SAM Vorlagendatei, die eine AWS::Serverless::Api Definition mit zwei Modellschemas zeigt.

YAML

Resources:
  ApiGatewayApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: Prod
      Models:
        User:
          type: object
          required:
            - username
            - employee_id
          properties:
            username:
              type: string
            employee_id:
              type: integer
            department:
              type: string
        Item:
          type: object
          properties:
            count:
              type: integer
            category:
              type: string
            price:
              type: integer

Beispiel für Caching

Eine Hello AWS SAM World-Vorlagendatei, die eine Lambda-Funktion mit einem API-Endpunkt enthält. In der API ist das Caching für eine Ressource und Methode aktiviert. Weitere Informationen zum Caching finden Sie unter Aktivieren von API-Caching zur Verbesserung der Reaktionsfähigkeit im API Gateway Developer Guide.

YAML

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: AWS SAM template with a simple API definition with caching turned on
Resources:
  ApiGatewayApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: prod
      CacheClusterEnabled: true
      CacheClusterSize: '0.5'
      MethodSettings:
        - ResourcePath: /
          HttpMethod: GET
          CachingEnabled: true
          CacheTtlInSeconds: 300
      Tags:
        CacheMethods: All 

  ApiFunction: # Adds a GET method at the root resource via an Api event
    Type: AWS::Serverless::Function
    Properties:
      Events:
        ApiEvent:
          Type: Api
          Properties:
            Path: /
            Method: get
            RestApiId:
              Ref: ApiGatewayApi
      Runtime: python3.10
      Handler: index.handler
      InlineCode: |
        def handler(event, context):
            return {'body': 'Hello World!', 'statusCode': 200}