Sintassi Proprietà Valori restituiti Esempi

AWS::Serverless::HttpApi

Crea un'API HTTP Amazon API Gateway, che consente di creare API RESTful con latenza e costi inferiori rispetto alle API REST. Per ulteriori informazioni, consulta Lavorare con le API HTTP nella Guida per sviluppatori di API Gateway.

Ti consigliamo di utilizzare AWS CloudFormation hook o policy IAM per verificare che alle risorse API Gateway siano associate autorizzazioni per controllarne l'accesso.

Per ulteriori informazioni sull'uso degli AWS CloudFormation hook, consulta Registrazione degli hook nella guida per l'utente della AWS CloudFormation CLI e nel repository. apigw-enforce-authorizer GitHub

Per ulteriori informazioni sull'utilizzo delle policy IAM, consulta Require che le route API abbiano l'autorizzazione nella API Gateway Developer Guide.

Nota

Quando esegui la distribuzione aAWS CloudFormation, AWS SAM trasforma le tue AWS SAM risorse in AWS CloudFormation risorse. Per ulteriori informazioni, consulta AWS CloudFormationRisorse generate.

Sintassi

Per dichiarare questa entità nel tuo modello AWS Serverless Application Model (AWS SAM), usa la seguente sintassi.

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

Proprietà

AccessLogSettings

Le impostazioni per la registrazione degli accessi in una fase.

Tipo: AccessLogSettings

Required: No

AWS CloudFormationcompatibilità: questa proprietà viene passata direttamente alla AccessLogSettings proprietà di una AWS::ApiGatewayV2::Stage risorsa.

Auth

Configura l'autorizzazione per il controllo dell'accesso all'API HTTP API Gateway.

Per ulteriori informazioni consulta la sezione Controlling access to HTTP APIs with JWT authorizers (Controllo dell'accesso alle API HTTP con le autorizzazioni JWT) nella Guida per gli sviluppatori dell’API Gateway.

Tipo: HttpApiAuth

Required: No

AWS CloudFormationcompatibilità: questa proprietà è unica AWS SAM e non ha un AWS CloudFormation equivalente.

CorsConfiguration

Gestisce la condivisione delle risorse tra origini (CORS) per tutte le API HTTP dell'API Gateway. Specificate il dominio da consentire come stringa o specificate un oggetto. HttpApiCorsConfiguration Nota che CORS richiede AWS SAM di modificare la definizione OpenAPI, quindi CORS funziona solo se DefinitionBody la proprietà è specificata.

Per ulteriori informazioni, consulta Configurazione di CORS per un'API HTTP nella Guida per sviluppatori di API Gateway.

Nota

Se CorsConfiguration è impostato sia in una definizione OpenAPI che a livello di proprietà, AWS SAM unisce entrambe le fonti di configurazione con le proprietà che hanno la precedenza. Se questa proprietà è impostata sutrue, tutte le origini sono consentite.

Tipo: String | HttpApiCorsConfiguration

Required: No

AWS CloudFormationcompatibilità: Questa proprietà è unica AWS SAM e non ha un AWS CloudFormation equivalente.

DefaultRouteSettings

Le impostazioni di routing predefinite per questa API HTTP. Queste impostazioni si applicano a tutti i percorsi a meno che non vengano sovrascritte dalla RouteSettings proprietà per determinati percorsi.

Tipo: RouteSettings

Required: No

AWS CloudFormationcompatibilità: questa proprietà viene passata direttamente alla RouteSettings proprietà di una AWS::ApiGatewayV2::Stage risorsa.

DefinitionBody

La definizione OpenAPI che descrive la tua API HTTP. Se non specifichi a DefinitionUri o aDefinitionBody, AWS SAM genera una DefinitionBody per te in base alla configurazione del modello.

Type: JSON

Required: No

AWS CloudFormationcompatibilità: questa proprietà è simile alla Body proprietà di una AWS::ApiGatewayV2::Api risorsa. Se vengono fornite determinate proprietà, AWS SAM può inserire o modificare il contenuto DefinitionBody prima che venga passato aAWS CloudFormation. Le proprietà includono Auth e un EventSource tipo HttpApi per una AWS::Serverless::Function risorsa corrispondente.

DefinitionUri

L'URI, il percorso del file locale o l'oggetto location di Amazon Simple Storage Service (Amazon S3) Simple Storage Service (Amazon S3) Simple Storage Service (Amazon S3) che definisce l'API HTTP. L'oggetto Amazon S3 a cui fa riferimento questa proprietà deve essere un file di definizione OpenAPI valido. Se non specifichi a DefinitionUri o a are DefinitionBody sono specificati, AWS SAM genera un messaggio DefinitionBody in base alla configurazione del modello.

Se fornite un percorso di file locale, il modello deve passare attraverso il flusso di lavoro che include il sam package comando sam deploy o affinché la definizione venga trasformata correttamente.

Le funzioni intrinseche non sono supportate nei file di OpenApi definizione esterni a cui si fa riferimento. DefinitionUri Per importare una OpenApi definizione nel modello, utilizzate la DefinitionBody proprietà con la trasformazione Include.

Tipo: String | HttpApiDefinition

Required: No

AWS CloudFormationcompatibilità: Questa proprietà è simile alla BodyS3Location proprietà di una AWS::ApiGatewayV2::Api risorsa. Le proprietà annidate di Amazon S3 sono denominate in modo diverso.

Description

La descrizione della risorsa API HTTP.

Quando si specificaDescription, AWS SAM modificherà la OpenApi definizione della risorsa API HTTP impostando il description campo. I seguenti scenari genereranno un errore:

La DefinitionBody proprietà viene specificata con il description campo impostato nella definizione di Open API: ciò genera un conflitto del description campo che AWS SAM non verrà risolto.
La DefinitionUri proprietà è specificata: AWS SAM non modificherà una definizione di Open API recuperata da Amazon S3.

Tipo: stringa

Required: No

AWS CloudFormationcompatibilità: questa proprietà è unica AWS SAM e non ha un AWS CloudFormation equivalente.

DisableExecuteApiEndpoint

Speciifica se i client possono richiamare l'API HTTP utilizzando l'endpoint predefinitoexecute-api. https://{api_id}.execute-api.{region}.amazonaws.com Per impostazione predefinita, i client possono richiamare l'API con l'endpoint predefinito. Per richiedere che i client utilizzino solo un nome di dominio personalizzato per richiamare l'API, disabilita l'endpoint predefinito.

Tipo: Booleano

Required: No

AWS CloudFormationcompatibilità: questa proprietà è simile alla DisableExecuteApiEndpoint proprietà di una AWS::ApiGatewayV2::Api risorsa. Viene passato direttamente alla disableExecuteApiEndpoint proprietà di un' x-amazon-apigateway-endpoint-configurationestensione, che viene aggiunta alla Body proprietà di una AWS::ApiGatewayV2::Api risorsa.

Domain

Configura un dominio personalizzato per questa API HTTP API Gateway.

Tipo: HttpApiDomainConfiguration

Required: No

AWS CloudFormationcompatibilità: questa proprietà è unica AWS SAM e non ha un AWS CloudFormation equivalente.

FailOnWarnings

Speciifica se ripristinare la creazione dell'API HTTP (true) o meno (false) quando viene rilevato un avviso. Il valore predefinito è false.

Tipo: Booleano

Required: No

AWS CloudFormationcompatibilità: questa proprietà viene passata direttamente alla FailOnWarnings proprietà di una AWS::ApiGatewayV2::Api risorsa.

Name

Il nome della risorsa API HTTP.

Quando si specificaName, AWS SAM modificherà la definizione OpenAPI della risorsa API HTTP impostando il title campo. I seguenti scenari genereranno un errore:

La DefinitionBody proprietà viene specificata con il title campo impostato nella definizione di Open API: ciò genera un conflitto del title campo che AWS SAM non verrà risolto.
La DefinitionUri proprietà è specificata: AWS SAM non modificherà una definizione di Open API recuperata da Amazon S3.

Tipo: stringa

Required: No

AWS CloudFormationcompatibilità: questa proprietà è unica AWS SAM e non ha un AWS CloudFormation equivalente.

PropagateTags

Indica se passare o meno i tag dalla Tags proprietà alle risorse AWS::Serverless::HttpApi generate. TrueSpecificate di propagare i tag nelle risorse generate.

Tipo: Booleano

Required: No

Default: False

AWS CloudFormationcompatibilità: questa proprietà è unica AWS SAM e non ha un AWS CloudFormation equivalente.

RouteSettings

Le impostazioni del percorso, per percorso, per questa API HTTP. Per ulteriori informazioni, consulta Lavorare con i percorsi per le API HTTP nella Guida per sviluppatori di API Gateway.

Tipo: RouteSettings

Required: No

AWS CloudFormationcompatibilità: questa proprietà viene passata direttamente alla RouteSettings proprietà di una AWS::ApiGatewayV2::Stage risorsa.

StageName

Il nome della fase API. Se non viene specificato alcun nome, AWS SAM utilizza lo $default stage di API Gateway.

Tipo: stringa

Required: No

Predefinito: $default

AWS CloudFormationcompatibilità: questa proprietà viene passata direttamente alla StageName proprietà di una AWS::ApiGatewayV2::Stage risorsa.

StageVariables

Mappa che definisce le variabili delle fasi. I nomi delle variabili possono avere caratteri alfanumerici e caratteri di sottolineatura. I valori devono corrispondere a [a-zA-Z0-9-._~:/? #&=,] +.

Type: Json

Required: No

AWS CloudFormationcompatibilità: questa proprietà viene passata direttamente alla StageVariables proprietà di una AWS::ApiGatewayV2::Stage risorsa.

Tags

Una mappa (da stringa a stringa) che specifica i tag da aggiungere a questa fase di API Gateway. Le chiavi possono contenere da 1 a 128 caratteri Unicode e non possono includere il prefisso. aws: Puoi utilizzare uno qualsiasi dei seguenti caratteri: l'insieme delle lettere Unicode, cifre, spazi, _, ., /, =, + e -. I valori possono avere una lunghezza compresa tra 1 e 256 caratteri Unicode.

Tipo: Mappa

Required: No

AWS CloudFormationcompatibilità: questa proprietà è unica AWS SAM e non ha un AWS CloudFormation equivalente.

Note aggiuntive: La Tags proprietà richiede di AWS SAM modificare la definizione di OpenAPI, quindi i tag vengono aggiunti solo se la DefinitionBody proprietà è specificata, non viene aggiunto alcun tag se la proprietà è specificata. DefinitionUri AWS SAMaggiunge automaticamente un tag. httpapi:createdBy:SAM I tag vengono aggiunti anche alla AWS::ApiGatewayV2::Stage risorsa e alla AWS::ApiGatewayV2::DomainName risorsa (se DomainName specificato).

Valori restituiti

Ref

Quando si passa l'ID logico di questa risorsa alla Ref funzione intrinseca, Ref restituisce l'ID API della AWS::ApiGatewayV2::Api risorsa sottostante, ad esempio. a1bcdef2gh

Per ulteriori informazioni sull'uso della Ref funzione, consulta Refla Guida per l'AWS CloudFormationutente.

Esempi

Semplice HttpApi

L'esempio seguente mostra il minimo necessario per configurare un endpoint API HTTP supportato da una funzione Lambda. Questo esempio utilizza l'API HTTP predefinita che AWS SAM crea.

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

L'esempio seguente mostra come impostare l'autorizzazione sugli endpoint dell'API HTTP.

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"

HttpApicon definizione OpenAPI

L'esempio seguente mostra come aggiungere una definizione OpenAPI al modello.

Tieni presente che AWS SAM compila tutte le integrazioni Lambda mancanti HttpApi per gli eventi che fanno riferimento a questa API HTTP. AWS SAMaggiunge anche eventuali percorsi mancanti a cui fanno riferimento gli HttpApi eventi.

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 con impostazioni di configurazione

L'esempio seguente mostra come aggiungere API HTTP e configurazioni di stage al modello.

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

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Runtime

HttpApiAuth