Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
# Estensioni OpenAPI per Gateway API
Le estensioni API Gateway supportano l'autorizzazione AWS specifica e le integrazioni API specifiche per API Gateway per REST e HTTP. APIs APIs In questa sezione vengono descritte le estensioni API Gateway nella specifica OpenAPI.
**Suggerimento**
Per comprendere come vengono utilizzate le estensioni API Gateway in un'applicazione, puoi usare la console API Gateway per creare un'API REST o API HTTP ed esportarla in un file di definizione OpenAPI. Per ulteriori informazioni su come esportare un'API, consulta [Esportazione di un'API REST da API Gateway](api-gateway-export-api.md) e [Esporta HTTP APIs da API Gateway](http-api-export.md).
**Topics**
+ [x-amazon-apigateway-anyoggetto -method](api-gateway-swagger-extensions-any-method.md)
+ [x-amazon-apigateway-cors oggetto](api-gateway-swagger-extensions-cors-configuration.md)
+ [x-amazon-apigateway-apiproprietà -key-source](api-gateway-swagger-extensions-api-key-source.md)
+ [x-amazon-apigateway-auth oggetto](api-gateway-swagger-extensions-auth.md)
+ [x-amazon-apigateway-authorizer oggetto](api-gateway-swagger-extensions-authorizer.md)
+ [x-amazon-apigateway-authtype proprietà](api-gateway-swagger-extensions-authtype.md)
+ [x-amazon-apigateway-binaryproprietà -media-types](api-gateway-swagger-extensions-binary-media-types.md)
+ [x-amazon-apigateway-documentation oggetto](api-gateway-swagger-extensions-documentation.md)
+ [x-amazon-apigateway-endpoint-modalità di accesso](openapi-extensions-endpoint-access-mode.md)
+ [x-amazon-apigateway-endpoint-oggetto di configurazione](api-gateway-swagger-extensions-endpoint-configuration.md)
+ [x-amazon-apigateway-gatewayoggetto -response](api-gateway-swagger-extensions-gateway-responses.md)
+ [x-amazon-apigateway-gateway-Response.oggetto GatewayResponse](api-gateway-swagger-extensions-gateway-responses.gatewayResponse.md)
+ [x-amazon-apigateway-gateway-Oggetto Response.responseParameters](api-gateway-swagger-extensions-gateway-responses.responseParameters.md)
+ [x-amazon-apigateway-gatewayOggetto -Response.responseTemplates](api-gateway-swagger-extensions-gateway-responses.responseTemplates.md)
+ [x-amazon-apigateway-importexport-versione](api-gateway-extensions-importexport-version.md)
+ [x-amazon-apigateway-integration oggetto](api-gateway-swagger-extensions-integration.md)
+ [x-amazon-apigateway-integrations oggetto](api-gateway-extensions-integrations.md)
+ [x-amazon-apigateway-integration.oggetto RequestTemplates](api-gateway-swagger-extensions-integration-requestTemplates.md)
+ [x-amazon-apigateway-integration.oggetto RequestParameters](api-gateway-swagger-extensions-integration-requestParameters.md)
+ [x-amazon-apigateway-integrationoggetto.response](api-gateway-swagger-extensions-integration-responses.md)
+ [x-amazon-apigateway-integrationoggetto.response](api-gateway-swagger-extensions-integration-response.md)
+ [x-amazon-apigateway-integration.oggetto responseTemplates](api-gateway-swagger-extensions-integration-responseTemplates.md)
+ [x-amazon-apigateway-integration.ResponseParameters](api-gateway-swagger-extensions-integration-responseParameters.md)
+ [x-amazon-apigateway-integrationOggetto.TLSConfig](api-gateway-extensions-integration-tls-config.md)
+ [x-amazon-apigateway-minimum-dimensione di compressione](api-gateway-openapi-minimum-compression-size.md)
+ [x-amazon-apigateway-policy](openapi-extensions-policy.md)
+ [x-amazon-apigateway-requestproprietà -validator](api-gateway-swagger-extensions-request-validator.md)
+ [x-amazon-apigateway-requestoggetto -validators](api-gateway-swagger-extensions-request-validators.md)
+ [x-amazon-apigateway-request-Validators.RequestValidator oggetto](api-gateway-swagger-extensions-request-validators.requestValidator.md)
+ [x-amazon-apigateway-security-politica](openapi-extensions-security-policy.md)
+ [x-amazon-apigateway-tagproprietà -value](api-gateway-openapi-extensions-x-amazon-apigateway-tag-value.md)
# x-amazon-apigateway-anyoggetto -method
Specifica l'[oggetto OpenAPI Operation](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#operation-object) per il metodo `ANY` catch-all di API Gateway in un [oggetto OpenAPI Path Item](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#path-item-object). Questo oggetto può coesistere con altri oggetti Operation e rileverà qualsiasi metodo HTTP non esplicitamente dichiarato.
Nella tabella seguente sono elencate le proprietà estese da API Gateway. Per le altre proprietà OpenAPI Operation, consulta le specifiche di OpenAPI.
| Nome proprietà | Tipo | Descrizione |
| --- | --- | --- |
| isDefaultRoute | Boolean | Specificare se una route è la route \$1default. Supportato solo per HTTP APIs. Per ulteriori informazioni, consulta [Crea percorsi per HTTP APIs in API Gateway](http-api-develop-routes.md). |
| x-amazon-apigateway-integration | [x-amazon-apigateway-integration oggetto](api-gateway-swagger-extensions-integration.md) | Specifica l'integrazione del metodo con il back-end. Si tratta di una proprietà estesa dell'oggetto [OpenAPI Operation](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#operation-object). L'integrazione può essere del tipo AWS, AWS\$1PROXY, HTTP, HTTP\$1PROXY o MOCK. |
## x-amazon-apigateway-any-method: esempi
L'esempio seguente integra il metodo `ANY` per una risorsa proxy, `{proxy+}`, con una funzione Lambda, `TestSimpleProxy`.
```
"/{proxy+}": {
"x-amazon-apigateway-any-method": {
"produces": [
"application/json"
],
"parameters": [
{
"name": "proxy",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {},
"x-amazon-apigateway-integration": {
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:TestSimpleProxy/invocations",
"httpMethod": "POST",
"type": "aws_proxy"
}
```
Nell'esempio seguente viene creata una route `$default` per un'API HTTP che si integra con una funzione Lambda, `HelloWorld`.
```
"/$default": {
"x-amazon-apigateway-any-method": {
"isDefaultRoute": true,
"x-amazon-apigateway-integration": {
"type": "AWS_PROXY",
"httpMethod": "POST",
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:HelloWorld/invocations",
"timeoutInMillis": 1000,
"connectionType": "INTERNET",
"payloadFormatVersion": 1.0
}
}
}
```
# x-amazon-apigateway-cors oggetto
Specificare la configurazione CORS (Cross-origin Resource Sharing) per un'API HTTP. L'estensione si applica alla struttura OpenAPI a livello root. Per ulteriori informazioni, consulta [Configurazione di CORS per HTTP APIs in API Gateway](http-api-cors.md).
| Nome proprietà | Tipo | Descrizione |
| --- | --- | --- |
| allowOrigins | Array | Specifica le origini consentite. |
| allowCredentials | Boolean | Specifica se le credenziali sono incluse nella richiesta CORS. |
| exposeHeaders | Array | Specifica le intestazioni esposte. |
| maxAge | Integer | Specifica il numero di secondi in cui il browser deve memorizzare nella cache i risultati delle richieste preliminari. |
| allowMethods | Array | Specifica i metodi HTTP consentiti. |
| allowHeaders | Array | Specifica le intestazioni consentite. |
## x-amazon-apigateway-cors esempio
Di seguito è riportato un esempio di configurazione CORS per un'API HTTP.
```
"x-amazon-apigateway-cors": {
"allowOrigins": [
"https://www.example.com"
],
"allowCredentials": true,
"exposeHeaders": [
"x-apigateway-header",
"x-amz-date",
"content-type"
],
"maxAge": 3600,
"allowMethods": [
"GET",
"OPTIONS",
"POST"
],
"allowHeaders": [
"x-apigateway-header",
"x-amz-date",
"content-type"
]
}
```
# x-amazon-apigateway-apiproprietà -key-source
Specifica l'origine per la ricezione di una chiave API per il throttling dei metodi API che richiedono una chiave. Questa proprietà a livello di API è un tipo `String`. Per ulteriori informazioni sulla configurazione di un metodo per richiedere una chiave API, consulta [Configurazione di un metodo per utilizzare le chiavi API con una definizione OpenAPI](api-key-usage-plan-oas.md).
Specifica l'origine della chiave API per le richieste. I valori validi sono:
+ `HEADER` per ricevere la chiave API dall'intestazione `X-API-Key` di una richiesta.
+ `AUTHORIZER` per ricevere la chiave API da `UsageIdentifierKey` di un provider di autorizzazioni Lambda (nota in precedenza come autorizzazioni ad hoc).
## x-amazon-apigateway-apiesempio di -key-source
L'esempio seguente imposta l'intestazione `X-API-Key` come fonte della chiave API.
------
#### [ OpenAPI 2.0 ]
```
{
"swagger" : "2.0",
"info" : {
"title" : "Test1"
},
"schemes" : [ "https" ],
"basePath" : "/import",
"x-amazon-apigateway-api-key-source" : "HEADER",
.
.
.
}
```
------
#### [ OpenAPI 3.0.1 ]
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Test1"
},
"servers" : [ {
"url" : "/{basePath}",
"variables" : {
"basePath" : {
"default" : "import"
}
}
} ],
"x-amazon-apigateway-api-key-source" : "HEADER",
.
.
.
}
```
------
# x-amazon-apigateway-auth oggetto
Definisce un tipo di autorizzazione da applicare per l'autorizzazione dei richiami dei metodi in API Gateway.
| Nome proprietà | Tipo | Descrizione |
| --- | --- | --- |
| type | string | Specifica il tipo di autorizzazione. Specifica "NONE" per l'accesso aperto. Specifica "AWS\$1IAM" per l'utilizzo di autorizzazioni IAM. I valori non rispettano la distinzione tra maiuscole e minuscole. |
## x-amazon-apigateway-auth esempio
Nell'esempio seguente viene impostato il tipo di autorizzazione per un metodo API.
------
#### [ OpenAPI 3.0.1 ]
```
{
"openapi": "3.0.1",
"info": {
"title": "openapi3",
"version": "1.0"
},
"paths": {
"/protected-by-iam": {
"get": {
"x-amazon-apigateway-auth": {
"type": "AWS_IAM"
}
}
}
}
}
```
------
# x-amazon-apigateway-authorizer oggetto
Definisce un sistema di autorizzazione Lambda, pool di utenti Amazon Cognito o provider di autorizzazioni JWT da applicare per l'autorizzazione delle invocazioni dei metodi in API Gateway. Questa estensione si applica alla definizione di sicurezza in [OpenAPI 2](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#security-definitions-object) e allo schema di sicurezza in [OpenAPI 3](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md#security-scheme-object).
| Nome proprietà | Tipo | Descrizione |
| --- | --- | --- |
| type | string | Il tipo di autorizzazione. Questa proprietà è obbligatoria. Per REST APIs, specificare `token` un autorizzatore con l'identità del chiamante incorporata in un token di autorizzazione. Specificare `request` per un'autorizzazione con l'identità dell'intermediario contenuta nei parametri della richiesta. Specifica `cognito_user_pools` per un provider di autorizzazioni che utilizza un pool di utenti Amazon Cognito per controllare l'accesso all'API. Per HTTP APIs, specifica `request` un autorizzatore Lambda con l'identità del chiamante contenuta nei parametri della richiesta. Specificare `jwt` per un'autorizzazione JWT. |
| authorizerUri | string | L'URI (Uniform Resource Identifier) della funzione Lambda del provider di autorizzazioni. La sintassi è esposta di seguito: "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:account-id:function:auth_function_name/invocations"
|
| authorizerCredentials | string | Le credenziali richieste per invocare il provider di autorizzazioni, se presente, nel formato di un ARN di un ruolo di esecuzione IAM. Ad esempio, «arn:aws:iam:::». *account-id* *IAM\$1role* |
| authorizerPayloadFormatVersion | string | Per HTTP APIs, specifica il formato dei dati che API Gateway invia a un sistema di autorizzazione Lambda e il modo in cui API Gateway interpreta la risposta di Lambda. Per ulteriori informazioni, consulta [Tipo di formato payload](http-api-lambda-authorizer.md#http-api-lambda-authorizer.payload-format). |
| enableSimpleResponses | Boolean | Per HTTP APIs, specifica se un `request` autorizzatore restituisce un valore booleano o una policy IAM. Supportato solo per le autorizzazioni con un `authorizerPayloadFormatVersion` `2.0`. Se abilitata, la funzione del provider di autorizzazioni Lambda restituisce un valore booleano. Per ulteriori informazioni, consulta [Risposta della funzione Lambda per il formato 2.0](http-api-lambda-authorizer.md#http-api-lambda-authorizer.v2). |
| identitySource | string | Un elenco separato da virgole di espressioni di mappatura dei parametri di richiesta come origine di identità. Applicabile solo per l'autorizzazione del tipo `request` e `jwt`. |
| jwtConfiguration | Object | Specifica l'emittente e i gruppi di destinatari per un autorizzatore JWT. Per ulteriori informazioni, consulta [JWTConfiguration](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration)l'API Reference di API Gateway versione 2. Supportato solo per HTTP APIs. |
| identityValidationExpression | string | Espressione regolare per la convalida del token come identità in ingresso. Ad esempio, "^x-[a-z]\$1". Supportato solo per gli `TOKEN` autorizzatori per REST APIs. |
| authorizerResultTtlInSeconds | string | Numero di secondi durante i quali il risultato dell'autorizzazione viene memorizzato nella cache. |
| providerARNs | Una matrice di string | Un elenco del pool di utenti di Amazon Cognito ARNs per. `COGNITO_USER_POOLS` |
## x-amazon-apigateway-authorizer esempi per REST APIs
Il seguente esempio di definizioni di sicurezza OpenAPI specifica un provider di autorizzazioni Lambda di tipo "token" denominato `test-authorizer`.
```
"securityDefinitions" : {
"test-authorizer" : {
"type" : "apiKey", // Required and the value must be "apiKey" for an API Gateway API.
"name" : "Authorization", // The name of the header containing the authorization token.
"in" : "header", // Required and the value must be "header" for an API Gateway API.
"x-amazon-apigateway-authtype" : "custom", // Specifies the authorization mechanism for the client.
"x-amazon-apigateway-authorizer" : { // An API Gateway Lambda authorizer definition
"type" : "token", // Required property and the value must "token"
"authorizerUri" : "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:account-id:function:function-name/invocations",
"authorizerCredentials" : "arn:aws:iam::account-id:role",
"identityValidationExpression" : "^x-[a-z]+",
"authorizerResultTtlInSeconds" : 60
}
}
}
```
Il seguente frammento di oggetto operazione OpenAPI imposta `GET /http` per l'uso del provider di autorizzazioni Lambda precedente.
```
"/http" : {
"get" : {
"responses" : { },
"security" : [ {
"test-authorizer" : [ ]
} ],
"x-amazon-apigateway-integration" : {
"type" : "http",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"httpMethod" : "GET",
"uri" : "http://api.example.com"
}
}
}
```
Il seguente esempio di definizioni di sicurezza OpenAPI specifica un provider di autorizzazioni Lambda di tipo "request", con un parametro di intestazione singolo (`auth`) come origine di identità. Il nome di `securityDefinitions` è `request_authorizer_single_header`.
```
"securityDefinitions": {
"request_authorizer_single_header" : {
"type" : "apiKey",
"name" : "auth", // The name of a single header or query parameter as the identity source.
"in" : "header", // The location of the single identity source request parameter. The valid value is "header" or "query"
"x-amazon-apigateway-authtype" : "custom",
"x-amazon-apigateway-authorizer" : {
"type" : "request",
"identitySource" : "method.request.header.auth", // Request parameter mapping expression of the identity source. In this example, it is the 'auth' header.
"authorizerCredentials" : "arn:aws:iam::123456789012:role/AWSepIntegTest-CS-LambdaRole",
"authorizerUri" : "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:APIGateway-Request-Authorizer:vtwo/invocations",
"authorizerResultTtlInSeconds" : 300
}
}
}
```
Il seguente esempio di definizioni di sicurezza OpenAPI specifica un provider di autorizzazioni Lambda di tipo "request", con un'intestazione (`HeaderAuth1`) e un parametro di stringa di query `QueryString1` come origini di identità.
```
"securityDefinitions": {
"request_authorizer_header_query" : {
"type" : "apiKey",
"name" : "Unused", // Must be "Unused" for multiple identity sources or non header or query type of request parameters.
"in" : "header", // Must be "header" for multiple identity sources or non header or query type of request parameters.
"x-amazon-apigateway-authtype" : "custom",
"x-amazon-apigateway-authorizer" : {
"type" : "request",
"identitySource" : "method.request.header.HeaderAuth1, method.request.querystring.QueryString1", // Request parameter mapping expressions of the identity sources.
"authorizerCredentials" : "arn:aws:iam::123456789012:role/AWSepIntegTest-CS-LambdaRole",
"authorizerUri" : "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:APIGateway-Request-Authorizer:vtwo/invocations",
"authorizerResultTtlInSeconds" : 300
}
}
}
```
Il seguente esempio di definizioni di sicurezza OpenAPI specifica un provider di autorizzazioni Lambda API Gateway di tipo "request", con una variabile di fase singola (`stage`) come origine di identità.
```
"securityDefinitions": {
"request_authorizer_single_stagevar" : {
"type" : "apiKey",
"name" : "Unused", // Must be "Unused", for multiple identity sources or non header or query type of request parameters.
"in" : "header", // Must be "header", for multiple identity sources or non header or query type of request parameters.
"x-amazon-apigateway-authtype" : "custom",
"x-amazon-apigateway-authorizer" : {
"type" : "request",
"identitySource" : "stageVariables.stage", // Request parameter mapping expression of the identity source. In this example, it is the stage variable.
"authorizerCredentials" : "arn:aws:iam::123456789012:role/AWSepIntegTest-CS-LambdaRole",
"authorizerUri" : "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:APIGateway-Request-Authorizer:vtwo/invocations",
"authorizerResultTtlInSeconds" : 300
}
}
}
```
Il seguente esempio di definizione di sicurezza OpenAPI specifica un pool di utenti Amazon Cognito come provider di autorizzazioni.
```
"securityDefinitions": {
"cognito-pool": {
"type": "apiKey",
"name": "Authorization",
"in": "header",
"x-amazon-apigateway-authtype": "cognito_user_pools",
"x-amazon-apigateway-authorizer": {
"type": "cognito_user_pools",
"providerARNs": [
"arn:aws:cognito-idp:us-east-1:123456789012:userpool/us-east-1_ABC123"
]
}
}
```
Il seguente frammento di oggetto dell'operazione OpenAPI imposta `GET /http` per utilizzare il pool di utenti di Amazon Cognito precedente come provider di autorizzazioni, senza ambiti personalizzati.
```
"/http" : {
"get" : {
"responses" : { },
"security" : [ {
"cognito-pool" : [ ]
} ],
"x-amazon-apigateway-integration" : {
"type" : "http",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"httpMethod" : "GET",
"uri" : "http://api.example.com"
}
}
}
```
## x-amazon-apigateway-authorizer esempi per HTTP APIs
Nell'esempio OpenAPI 3.0 riportato di seguito viene creato un provider di autorizzazioni JWT per un'API HTTP che utilizza Amazon Cognito come provider di identità, con l'intestazione `Authorization` come origine identità.
```
"securitySchemes": {
"jwt-authorizer-oauth": {
"type": "oauth2",
"x-amazon-apigateway-authorizer": {
"type": "jwt",
"jwtConfiguration": {
"issuer": "https://cognito-idp.region.amazonaws.com/userPoolId",
"audience": [
"audience1",
"audience2"
]
},
"identitySource": "$request.header.Authorization"
}
}
}
```
L'esempio di OpenAPI 3.0 seguente produce lo stesso autorizzatore JWT dell'esempio precedente. Tuttavia, questo esempio utilizza la proprietà `openIdConnectUrl` di OpenAPI per rilevare automaticamente l'emittente. Il `openIdConnectUrl` deve essere completamente formato.
```
"securitySchemes": {
"jwt-authorizer-autofind": {
"type": "openIdConnect",
"openIdConnectUrl": "https://cognito-idp.region.amazonaws.com/userPoolId/.well-known/openid-configuration",
"x-amazon-apigateway-authorizer": {
"type": "jwt",
"jwtConfiguration": {
"audience": [
"audience1",
"audience2"
]
},
"identitySource": "$request.header.Authorization"
}
}
}
```
Nell'esempio seguente viene creato un provider di autorizzazioni Lambda per un'API HTTP. In questo esempio l'autorizzazione utilizza l'intestazione `Authorization` come origine di identità. L'autorizzazione utilizza il tipo di formato payload `2.0` e restituisce il valore booleano, poiché `enableSimpleResponses` è impostato su `true`.
```
"securitySchemes" : {
"lambda-authorizer" : {
"type" : "apiKey",
"name" : "Authorization",
"in" : "header",
"x-amazon-apigateway-authorizer" : {
"type" : "request",
"identitySource" : "$request.header.Authorization",
"authorizerUri" : "arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:function-name/invocations",
"authorizerPayloadFormatVersion" : "2.0",
"authorizerResultTtlInSeconds" : 300,
"enableSimpleResponses" : true
}
}
}
```
# x-amazon-apigateway-authtype proprietà
Per REST APIs, questa estensione può essere utilizzata per definire un tipo personalizzato di autorizzatore Lambda. In questo caso, il valore è in formato libero. Ad esempio, un'API può avere più provider di autorizzazioni Lambda che utilizzano schemi interni diversi. È possibile utilizzare questa estensione per identificare lo schema interno di un provider di autorizzazioni Lambda.
Più comunemente, in HTTP APIs e REST APIs, può essere utilizzata anche per definire l'autorizzazione IAM per diverse operazioni che condividono lo stesso schema di sicurezza. In questo caso, il termine `awsSigv4` è un termine riservato, insieme a qualsiasi termine con prefisso `aws`.
Questa estensione si applica allo schema di sicurezza dei tipi `apiKey` in [OpenAPI 2](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#security-scheme-object) e [OpenAPI 3. ](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md#security-scheme-object)
## x-amazon-apigateway-authtype esempio
Il seguente esempio OpenAPI 3 definisce l'autorizzazione IAM su più risorse in un'API REST o in un'API HTTP:
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "openapi3",
"version" : "1.0"
},
"paths" : {
"/operation1" : {
"get" : {
"responses" : {
"default" : {
"description" : "Default response"
}
},
"security" : [ {
"sigv4Reference" : [ ]
} ]
}
},
"/operation2" : {
"get" : {
"responses" : {
"default" : {
"description" : "Default response"
}
},
"security" : [ {
"sigv4Reference" : [ ]
} ]
}
}
},
"components" : {
"securitySchemes" : {
"sigv4Reference" : {
"type" : "apiKey",
"name" : "Authorization",
"in" : "header",
"x-amazon-apigateway-authtype": "awsSigv4"
}
}
}
}
```
Il seguente esempio OpenAPI 3 definisce un provider di autorizzazioni Lambda con uno schema personalizzato per un'API REST:
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "openapi3 for REST API",
"version" : "1.0"
},
"paths" : {
"/protected-by-lambda-authorizer" : {
"get" : {
"responses" : {
"200" : {
"description" : "Default response"
}
},
"security" : [ {
"myAuthorizer" : [ ]
} ]
}
}
},
"components" : {
"securitySchemes" : {
"myAuthorizer" : {
"type" : "apiKey",
"name" : "Authorization",
"in" : "header",
"x-amazon-apigateway-authorizer" : {
"identitySource" : "method.request.header.Authorization",
"authorizerUri" : "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:account-id:function:function-name/invocations",
"authorizerResultTtlInSeconds" : 300,
"type" : "request",
"enableSimpleResponses" : false
},
"x-amazon-apigateway-authtype": "Custom scheme with corporate claims"
}
}
},
"x-amazon-apigateway-importexport-version" : "1.0"
}
```
## Consulta anche
[authorizer.authType](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#apigw-Type-Authorizer-authType)
# x-amazon-apigateway-binaryproprietà -media-types
Specifica l'elenco di tipi di supporto binari che devono essere supportati da API Gateway, ad esempio `application/octet-stream` e `image/jpeg`. Questa estensione è una matrice JSON. Deve essere inclusa come estensione del fornitore di primo livello nel documento OpenAPI.
## x-amazon-apigateway-binary-esempio di tipi di media
L'esempio di seguito mostra l'ordine di ricerca della codifica di un'API
```
"x-amazon-apigateway-binary-media-types": [ "application/octet", "image/jpeg" ]
```
# x-amazon-apigateway-documentation oggetto
Definisce le parti della documentazione da importare in API Gateway. Si tratta di un oggetto JSON contenente una matrice di istanze di `DocumentationPart`.
| Nome proprietà | Tipo | Descrizione |
| --- | --- | --- |
| documentationParts | Array | Matrice delle istanze di `DocumentationPart` esportate o importate. |
| version | String | L'identificatore di versione dello snapshot delle parti di documentazione esportate. |
## x-amazon-apigateway-documentation esempio
L'esempio seguente dell'estensione di API Gateway in OpenAPI definisce le istanze di `DocumentationParts` da importare in o esportare da un'API in API Gateway.
```
{ ...
"x-amazon-apigateway-documentation": {
"version": "1.0.3",
"documentationParts": [
{
"location": {
"type": "API"
},
"properties": {
"description": "API description",
"info": {
"description": "API info description 4",
"version": "API info version 3"
}
}
},
{
… // Another DocumentationPart instance
}
]
}
}
```
# x-amazon-apigateway-endpoint-modalità di accesso
Speciifica una modalità di accesso all'endpoint per un'API REST o un nome di dominio personalizzato. Per ulteriori informazioni sulla modalità di accesso agli endpoint, consulta. [Modalità di accesso agli endpoint](apigateway-security-policies.md#apigateway-security-policies-endpoint-access-mode)
## `x-amazon-apigateway-endpoint-access-mode` Esempio
L'esempio seguente specifica la modalità di accesso agli endpoint su strict.
```
"x-amazon-apigateway-endpoint-access-mode": "STRICT"
```
# x-amazon-apigateway-endpoint-oggetto di configurazione
Specifica i dettagli della configurazione dell'endpoint per un'API. Questa estensione è una proprietà estesa dell'oggetto [OpenAPI Operation](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#operation-object). Questo oggetto deve essere presente nelle [estensioni dei fornitori di primo livello](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#specification-extensions) per Swagger 2.0. Per OpenAPI 3.0, deve essere presente nelle estensioni dei fornitori dell'[oggetto Server](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#server-object).
| Nome proprietà | Tipo | Descrizione |
| --- | --- | --- |
| disableExecuteApiEndpoint | Booleano | Specifica se i client possono richiamare l'API utilizzando l'endpoint `execute-api` predefinito. Per impostazione predefinita, i client possono richiamare l'API con l'endpoint `https://{api_id}.execute-api.{region}.amazonaws.com` predefinito. Per richiedere che i client utilizzino un nome di dominio personalizzato per richiamare l'API, specifica `true`. |
| vpcEndpointIds | Una matrice di String | Un elenco di VpcEndpoint identificatori in base ai quali creare record di alias Route 53 per un'API REST. È supportato solo per REST, APIs il tipo di `PRIVATE` endpoint. |
| ipAddressType | string | I tipi di indirizzo IP che possono invocare un’API HTTP. Viene utilizzato `ipv4` per consentire ai tipi di IPv4 indirizzo di richiamare un'API HTTP. Viene utilizzato `dualstack` per consentire IPv4 ai tipi di IPv6 indirizzo di richiamare un'API HTTP. È supportato solo per HTTP APIs. |
## x-amazon-apigateway-endpoint-esempi di configurazione
L'esempio seguente associa gli endpoint VPC specificati all'API REST.
```
"x-amazon-apigateway-endpoint-configuration": {
"vpcEndpointIds": ["vpce-0212a4ababd5b8c3e", "vpce-01d622316a7df47f9"]
}
```
Nell'esempio seguente l'endpoint predefinito per un'API viene disattivato.
```
"x-amazon-apigateway-endpoint-configuration": {
"disableExecuteApiEndpoint": true
}
```
Nell’esempio seguente si imposta il tipo di indirizzo IP su Dualstack per un’API HTTP.
```
"x-amazon-apigateway-endpoint-configuration": {
"ipAddressType": "dualstack"
}
```
# x-amazon-apigateway-gatewayoggetto -response
Definisce le risposte del gateway per un'API come una [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)mappa stringa-valore di coppie chiave-valore. L'estensione si applica alla struttura OpenAPI a livello root.
| Nome proprietà | Tipo | Description |
| --- | --- | --- |
| responseType | [x-amazon-apigateway-gateway-response.GatewayResponse](api-gateway-swagger-extensions-gateway-responses.gatewayResponse.md) | A sta per il specificato. `GatewayResponse` *responseType* |
## x-amazon-apigateway-gateway-esempio di risposte
Il seguente esempio di estensione API Gateway a OpenAPI definisce una [GatewayResponses](https://docs.aws.amazon.com/apigateway/latest/api/API_GetGatewayResponses.html)mappa che contiene due [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)istanze, una per il tipo e l'altra per il `DEFAULT_4XX` tipo. `INVALID_API_KEY`
```
{
"x-amazon-apigateway-gateway-responses": {
"DEFAULT_4XX": {
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'domain.com'"
},
"responseTemplates": {
"application/json": "{\"message\": test 4xx b }"
}
},
"INVALID_API_KEY": {
"statusCode": "429",
"responseTemplates": {
"application/json": "{\"message\": test forbidden }"
}
}
}
}
```
# x-amazon-apigateway-gateway-Response.oggetto GatewayResponse
Definisce una risposta del gateway di un tipo di risposta specificato, inclusi il codice di stato, eventuali modelli di risposta o parametri di risposta applicabili.
| Nome proprietà | Tipo | Description |
| --- | --- | --- |
| responseParameters | [x-amazon-apigateway-gateway-response.Parametri di risposta](api-gateway-swagger-extensions-gateway-responses.responseParameters.md) | Specifica i parametri, vale a dire i parametri dell'intestazione. [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) I valori di parametro possono assumere qualsiasi valore di [parametro di richiesta](rest-api-parameter-mapping.md) in ingresso o un valore personalizzato statico. |
| responseTemplates | [x-amazon-apigateway-gateway-Response.responseTemplates](api-gateway-swagger-extensions-gateway-responses.responseTemplates.md) | Specifica i modelli di mappatura della risposta del gateway. I modelli non sono elaborati dal motore VTL. |
| statusCode | string | Un codice di stato HTTP per la risposta del gateway. |
## x-amazon-apigateway-gateway-Esempio di response.GatewayResponse
L'esempio seguente dell'estensione API Gateway a OpenAPI definisce un [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)modo per personalizzare la `INVALID_API_KEY` risposta per restituire il codice di stato`456`, il valore dell'`api-key`intestazione della richiesta in entrata e un messaggio. `"Bad api-key"`
```
"INVALID_API_KEY": {
"statusCode": "456",
"responseParameters": {
"gatewayresponse.header.api-key": "method.request.header.api-key"
},
"responseTemplates": {
"application/json": "{\"message\": \"Bad api-key\" }"
}
}
```
# x-amazon-apigateway-gateway-Oggetto Response.responseParameters
Definisce una string-to-string mappa di coppie chiave-valore per generare i parametri di risposta del gateway dai parametri della richiesta in entrata o utilizzando stringhe letterali. Supportato solo per REST. APIs
| Nome proprietà | Tipo | Descrizione |
| --- | --- | --- |
| gatewayresponse.param-position.param-name | string | `param-position` può essere `header`, `path` o `querystring`. Per ulteriori informazioni, consulta [Mappatura dei parametri per REST APIs in API Gateway](rest-api-parameter-mapping.md). |
## x-amazon-apigateway-gateway-Esempio di response.responseParameters
Il seguente esempio di estensioni OpenAPI mostra un'espressione di mappatura dei parametri di [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)risposta per abilitare il supporto CORS per le risorse sui domini. `*.example.domain`
```
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": '*.example.domain',
"gatewayresponse.header.from-request-header" : method.request.header.Accept,
"gatewayresponse.header.from-request-path" : method.request.path.petId,
"gatewayresponse.header.from-request-query" : method.request.querystring.qname
}
```
# x-amazon-apigateway-gatewayOggetto -Response.responseTemplates
Definisce i modelli di [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)mappatura, come una string-to-string mappa di coppie chiave-valore, per una determinata risposta del gateway. Per ogni coppia chiave-valore, la chiave è il tipo di contenuto. Ad esempio, «application/json» e il valore è un modello di mappatura stringified per semplici sostituzioni variabili. Un modello di mappatura `GatewayResponse` non viene elaborato dal motore [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html).
| Nome proprietà | Tipo | Descrizione |
| --- | --- | --- |
| content-type | string | Modello di mappatura del corpo `GatewayResponse` che supporta solo la semplice sostituzione di variabili per personalizzare un corpo della risposta del gateway. |
## x-amazon-apigateway-gateway-Esempio di response.responseTemplates
Il seguente esempio di estensioni OpenAPI mostra un modello di [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)mappatura per personalizzare una risposta di errore generata da API Gateway in un formato specifico dell'app.
```
"responseTemplates": {
"application/json": "{ \"message\": $context.error.messageString, \"type\":$context.error.responseType, \"statusCode\": '488' }"
}
```
Il seguente esempio di estensioni OpenAPI mostra un modello di [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)mappatura per sovrascrivere una risposta di errore generata da API Gateway con un messaggio di errore statico.
```
"responseTemplates": {
"application/json": "{ \"message\": 'API-specific errors' }"
}
```
# x-amazon-apigateway-importexport-versione
Specifica la versione dell'algoritmo di importazione ed esportazione API Gateway per HTTP APIs. Attualmente, l'unico valore supportato è `1.0`. Per ulteriori informazioni, consulta [exportVersion](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-exports-specification.html#w125aab9c10b3b1b4) nella *documentazione di riferimento di API Gateway versione 2*.
## x-amazon-apigateway-importexport-version (esempio)
Nell'esempio seguente viene impostata la versione di importazione ed esportazione su `1.0`.
```
{
"openapi": "3.0.1",
"x-amazon-apigateway-importexport-version": "1.0",
"info": { ...
```
# x-amazon-apigateway-integration oggetto
Specifica i dettagli dell'integrazione di back-end utilizzati per questo metodo. Questa estensione è una proprietà estesa dell'oggetto [OpenAPI Operation](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#operation-object). Il risultato è un oggetto di [integrazione API Gateway](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html).
| Nome proprietà | Tipo | Descrizione |
| --- | --- | --- |
| cacheKeyParameters | Una matrice di string | Elenco di parametri di richiesta i cui valori devono essere memorizzati nella cache. |
| cacheNamespace | string | Gruppo di tag specifici dell'API di parametri correlati memorizzati nella cache. |
| connectionId | string | L'ID di a [VpcLink](https://docs.aws.amazon.com/apigateway/latest/api/API_VpcLink.html)per l'integrazione privata. |
| connectionType | string | Il tipo di connessione dell'integrazione. Il valore valido è "VPC\$1LINK" per l'integrazione privata, in caso contrario, "INTERNET". |
| credentials | string | Per le credenziali basate sui ruoli AWS IAM, specifica l'ARN di un ruolo IAM appropriato. Se non specificate, vengono utilizzate per impostazione predefinita le autorizzazioni basate su risorsa che devono essere aggiunte manualmente per consentire all'API di accedere alla risorsa. Per ulteriori informazioni, consulta l'argomento relativo alla [concessione di autorizzazioni mediante una policy per le risorse](https://docs.aws.amazon.com/lambda/latest/dg/lambda-permissions.html#intro-permission-model-access-policy). Nota: quando usi le credenziali IAM, assicurati che siano abilitati gli [endpoint regionali AWS STS](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html) per la regione in cui questa API viene distribuita per ottenere le prestazioni migliori. |
| contentHandling | string | Tipi di conversione per la codifica del payload delle richieste. Valori validi sono 1) CONVERT\$1TO\$1TEXT, per la conversione di un payload binario in una stringa con codifica base64 o per la conversione di un payload di testo in una stringa con codifica utf-8 o per passare il payload di testo in modo nativo senza modifica e 2) CONVERT\$1TO\$1BINARY, per la conversione di un payload di testo nel BLOB con decodifica base64 o per passare un payload binario in modo nativo senza modifica. |
| httpMethod | string | Il metodo HTTP utilizzato nella richiesta di integrazione. Per le invocazioni della funzione Lambda, il valore deve essere POST. |
| integrationSubtype | string | Speciifica il sottotipo di integrazione per l'integrazione di un servizio. AWS Supportato solo per HTTP. APIs Per i sottotipi di integrazione supportati, consulta [Riferimento al sottotipo di integrazione](http-api-develop-integrations-aws-services-reference.md). |
| integrationTarget | string | Il listener ALB o NLB a cui inviare la richiesta. Supportato solo per le integrazioni private che utilizzano collegamenti VPC V2. Per ulteriori informazioni, consulta [Configura i collegamenti VPC V2 in API Gateway](apigateway-vpc-links-v2.md). |
| passthroughBehavior | string | Specifica il modo in cui deve essere passato un payload di richiesta del tipo di contenuto non mappato attraverso la richiesta di integrazione senza modifiche. I valori supportati sono when\$1no\$1templates, when\$1no\$1match e never. Per ulteriori informazioni, consulta [Integration.passthroughBehavior](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#passthroughBehavior). |
| payloadFormatVersion | string | Specifica il formato del payload inviato a un'integrazione. Obbligatorio per HTTP. APIs Per HTTP APIs, i valori supportati per le integrazioni del proxy Lambda sono e. 1.0 2.0 Per tutte le altre integrazioni, 1.0 è l'unico valore supportato. Per ulteriori informazioni, consulta [Crea integrazioni AWS Lambda proxy per HTTP APIs in API Gateway](http-api-develop-integrations-lambda.md) e [Riferimento al sottotipo di integrazione](http-api-develop-integrations-aws-services-reference.md). |
| requestParameters | [x-amazon-apigateway-integration.oggetto RequestParameters](api-gateway-swagger-extensions-integration-requestParameters.md) | Per REST APIs, specifica le mappature dai parametri di richiesta del metodo ai parametri della richiesta di integrazione. I parametri di richiesta supportati sono `querystring`, `path`, `header` e `body`. Per HTTP APIs, i parametri di richiesta sono una mappa chiave-valore che specifica i parametri che vengono passati alle integrazioni con un valore specificato. `AWS_PROXY` `integrationSubtype` È possibile fornire valori statici o dati di richiesta di mappatura, variabili di stadio o variabili di contesto che vengono valutate in fase di esecuzione. Per ulteriori informazioni, consulta [Crea integrazioni AWS di servizi per HTTP APIs in API Gateway](http-api-develop-integrations-aws-services.md). |
| requestTemplates | [x-amazon-apigateway-integration.oggetto RequestTemplates](api-gateway-swagger-extensions-integration-requestTemplates.md) | I modelli di mappatura per un payload di richiesta dei tipi MIME specificati. |
| responses | [x-amazon-apigateway-integrationoggetto.response](api-gateway-swagger-extensions-integration-responses.md) | Definisce le risposte di metodo e specifica le mappature di payload o dei parametri desiderate dalle risposte di integrazione alle risposte di metodo. |
| responseTransferMode | string | La modalità di trasferimento della risposta dell'integrazione. BUFFEREDDa utilizzare per fare in modo che API Gateway attenda di ricevere la risposta completa prima di iniziare la trasmissione. STREAMDa utilizzare per fare in modo che API Gateway invii risposte parziali al client non appena diventano disponibili. Per ulteriori informazioni, consulta [Trasmetti in streaming la risposta di integrazione per le integrazioni proxy in API Gateway](response-transfer-mode.md). |
| timeoutInMillis | integer | Timeout di integrazione tra 50 ms e 29.000 ms. |
| type | string | Il tipo di integrazione con il back-end specificato. I valori validi sono: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/api-gateway-swagger-extensions-integration.html) Per ulteriori informazioni sui tipi di integrazione, consulta [integration:type](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#type). |
| tlsConfig | [x-amazon-apigateway-integrationOggetto.TLSConfig](api-gateway-extensions-integration-tls-config.md) | Specifica la configurazione TLS per un'integrazione. |
| uri | string | L'URI dell'endpoint del back-end. Per le integrazioni del tipo aws, è un valore ARN. Per l'integrazione HTTP, è l'URL dell'endpoint HTTP che include lo schema https o http. |
## x-amazon-apigateway-integration esempi
Per HTTP APIs, puoi definire le integrazioni nella sezione dei componenti della tua definizione OpenAPI. Per ulteriori informazioni, consulta [x-amazon-apigateway-integrations oggetto](api-gateway-extensions-integrations.md).
```
"x-amazon-apigateway-integration": {
"$ref": "#/components/x-amazon-apigateway-integrations/integration1"
}
```
L'esempio seguente crea un'integrazione con una funzione Lambda. A scopo dimostrativo, si presuppone che i modelli di mappatura di esempio mostrati in `requestTemplates` e `responseTemplates` negli esempi sotto si applichino al seguente payload con formattazione JSON: `{ "name":"value_1", "key":"value_2", "redirect": {"url" :"..."} }` per generare l'output JSON `{ "stage":"value_1", "user-id":"value_2" }` o l'output XML `value_1`.
```
"x-amazon-apigateway-integration" : {
"type" : "aws",
"uri" : "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:012345678901:function:HelloWorld/invocations",
"httpMethod" : "POST",
"credentials" : "arn:aws:iam::012345678901:role/apigateway-invoke-lambda-exec-role",
"requestTemplates" : {
"application/json" : "#set ($root=$input.path('$')) { \"stage\": \"$root.name\", \"user-id\": \"$root.key\" }",
"application/xml" : "#set ($root=$input.path('$')) $root.name "
},
"requestParameters" : {
"integration.request.path.stage" : "method.request.querystring.version",
"integration.request.querystring.provider" : "method.request.querystring.vendor"
},
"cacheNamespace" : "cache namespace",
"cacheKeyParameters" : [],
"responses" : {
"2\\d{2}" : {
"statusCode" : "200",
"responseParameters" : {
"method.response.header.requestId" : "integration.response.header.cid"
},
"responseTemplates" : {
"application/json" : "#set ($root=$input.path('$')) { \"stage\": \"$root.name\", \"user-id\": \"$root.key\" }",
"application/xml" : "#set ($root=$input.path('$')) $root.name "
}
},
"302" : {
"statusCode" : "302",
"responseParameters" : {
"method.response.header.Location" : "integration.response.body.redirect.url"
}
},
"default" : {
"statusCode" : "400",
"responseParameters" : {
"method.response.header.test-method-response-header" : "'static value'"
}
}
}
}
```
I doppi apici (") della stringa JSON nei modelli di mappatura devono includere il carattere di escape di stringa (\$1").
# x-amazon-apigateway-integrations oggetto
Definisce una raccolta di integrazioni. Puoi definire le integrazioni nella sezione componenti della definizione OpenAPI e riutilizzare le integrazioni per più route. Supportato solo per HTTP APIs.
| Nome proprietà | Tipo | Description |
| --- | --- | --- |
| integration | [x-amazon-apigateway-integration oggetto](api-gateway-swagger-extensions-integration.md) | Una raccolta di oggetti di integrazione. |
## x-amazon-apigateway-integrations esempio
Nell'esempio seguente viene creata un'API HTTP che definisce due integrazioni e fa riferimento alle integrazioni utilizzando `$ref": "#/components/x-amazon-apigateway-integrations/integration-name`.
```
{
"openapi": "3.0.1",
"info":
{
"title": "Integrations",
"description": "An API that reuses integrations",
"version": "1.0"
},
"servers": [
{
"url": "https://example.com/{basePath}",
"description": "The production API server",
"variables":
{
"basePath":
{
"default": "example/path"
}
}
}],
"paths":
{
"/":
{
"get":
{
"x-amazon-apigateway-integration":
{
"$ref": "#/components/x-amazon-apigateway-integrations/integration1"
}
}
},
"/pets":
{
"get":
{
"x-amazon-apigateway-integration":
{
"$ref": "#/components/x-amazon-apigateway-integrations/integration1"
}
}
},
"/checkout":
{
"get":
{
"x-amazon-apigateway-integration":
{
"$ref": "#/components/x-amazon-apigateway-integrations/integration2"
}
}
}
},
"components": {
"x-amazon-apigateway-integrations":
{
"integration1":
{
"type": "aws_proxy",
"httpMethod": "POST",
"uri": "arn:aws:apigateway:us-east-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-2:123456789012:function:my-function/invocations",
"passthroughBehavior": "when_no_templates",
"payloadFormatVersion": "1.0"
},
"integration2":
{
"type": "aws_proxy",
"httpMethod": "POST",
"uri": "arn:aws:apigateway:us-east-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-2:123456789012:function:example-function/invocations",
"passthroughBehavior": "when_no_templates",
"payloadFormatVersion" : "1.0"
}
}
}
}
```
# x-amazon-apigateway-integration.oggetto RequestTemplates
Specifica i modelli di mappatura per un payload di richiesta dei tipi MIME specificati.
| Nome proprietà | Tipo | Descrizione |
| --- | --- | --- |
| MIME type | string | Un esempio del tipo MIME è `application/json`. Per informazioni su come creare un modello di mappatura, consulta [Trasformazioni dei modelli di mappatura per REST APIs in API Gateway](models-mappings.md). |
## x-amazon-apigateway-integrationEsempio di .requestTemplates
Il modello seguente imposta i modelli di mappatura per un payload di richiesta de tipi MIME `application/json` e `application/xml`.
```
"requestTemplates" : {
"application/json" : "#set ($root=$input.path('$')) { \"stage\": \"$root.name\", \"user-id\": \"$root.key\" }",
"application/xml" : "#set ($root=$input.path('$')) $root.name "
}
```
# x-amazon-apigateway-integration.oggetto RequestParameters
Per REST APIs, specifica le mappature dai parametri di richiesta del metodo denominato ai parametri della richiesta di integrazione. Prima di fare riferimento ai parametri delle richieste dei metodi, è necessario definirli.
Per HTTP APIs, specifica i parametri che vengono passati alle `AWS_PROXY` integrazioni con un valore specificato. `integrationSubtype`
| Nome proprietà | Tipo | Description |
| --- | --- | --- |
| integration.request.. | string | Per REST APIs, il valore è in genere un parametro di richiesta del metodo predefinito del `method.request..` formato, dove `` può essere`querystring`,`path`, `header` o. `body` Tuttavia, sono validi anche `$context.VARIABLE_NAME`, `$stageVariables.VARIABLE_NAME` e `STATIC_VALUE`. Per il parametro `body`, `` è un'espressione di percorso JSON senza il prefisso `$.` |
| parameter | string | Per HTTP APIs, i parametri di richiesta sono una mappa chiave-valore che specifica i parametri che vengono passati alle `AWS_PROXY` integrazioni con un valore specificato. `integrationSubtype` È possibile fornire valori statici o dati di richiesta di mappatura, variabili di stadio o variabili di contesto che vengono valutate in fase di esecuzione. Per ulteriori informazioni, consulta [Crea integrazioni AWS di servizi per HTTP APIs in API Gateway](http-api-develop-integrations-aws-services.md). |
## `x-amazon-apigateway-integration.requestParameters`Esempio
L'esempio di mappatura dei parametri di richiesta seguente converte i parametri di query (`version`), intestazione (`x-user-id`) e percorso (`service`) della richiesta del metodo rispettivamente in parametri di query (`stage`), intestazione (`x-userid`) e percorso (`op`) della richiesta di integrazione.
**Nota**
Se stai creando risorse tramite OpenAPI o CloudFormation, i valori statici devono essere racchiusi tra virgolette singole.
Per aggiungere questo valore dalla console, immetti `application/json` nella casella, senza virgolette.
```
"requestParameters" : {
"integration.request.querystring.stage" : "method.request.querystring.version",
"integration.request.header.x-userid" : "method.request.header.x-user-id",
"integration.request.path.op" : "method.request.path.service"
},
```
# x-amazon-apigateway-integrationoggetto.response
Definisce le risposte di metodo e specifica le mappature di payload o dei parametri dalle risposte di integrazione alle risposte di metodo.
| Nome proprietà | Tipo | Description |
| --- | --- | --- |
| Response status pattern | [x-amazon-apigateway-integrationoggetto.response](api-gateway-swagger-extensions-integration-response.md) | Un'espressione regolare utilizzata per abbinare la risposta di integrazione alla risposta del metodo, o `default` per raccogliere qualsiasi risposta che non è stata configurata. Per le integrazioni HTTP, la regex si applica al codice di stato della risposta di integrazione. Per le chiamate Lambda, l'espressione regolare si applica al `errorMessage` campo dell'oggetto informativo sull'errore restituito da AWS Lambda come corpo di risposta all'errore quando l'esecuzione della funzione Lambda genera un'eccezione. Il nome della *Response status pattern* proprietà si riferisce a un codice di stato della risposta o a un'espressione regolare che descrive un gruppo di codici di stato della risposta. Non corrisponde a nessun identificatore di una [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html)risorsa nell'API REST di API Gateway. |
## `x-amazon-apigateway-integration.responses`Esempio
L'esempio seguente mostra un elenco di risposte dalle risposte `2xx` e `302`. Per la risposta `2xx`, la risposta del metodo è mappata dal payload della risposta di integrazione del tipo MIME `application/json` o `application/xml`. Questa risposta usa i modelli di mappatura forniti. Per la risposta `302`, la risposta del metodo restituisce un'intestazione `Location` il cui valore viene derivato dalla proprietà `redirect.url` nel payload della risposta di integrazione.
```
"responses" : {
"2\\d{2}" : {
"statusCode" : "200",
"responseTemplates" : {
"application/json" : "#set ($root=$input.path('$')) { \"stage\": \"$root.name\", \"user-id\": \"$root.key\" }",
"application/xml" : "#set ($root=$input.path('$')) $root.name "
}
},
"302" : {
"statusCode" : "302",
"responseParameters" : {
"method.response.header.Location": "integration.response.body.redirect.url"
}
}
}
```
# x-amazon-apigateway-integrationoggetto.response
Definisce una risposta e specifica le mappature di payload o dei parametri dalla risposta di integrazione alla risposta di metodo.
| Nome proprietà | Tipo | Descrizione |
| --- | --- | --- |
| statusCode | string | Codice di stato HTTP per la risposta di metodo, ad esempi, `"200"`. Deve corrispondere a una risposta associata nel campo [OpenAPI Operation](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#operation-object) `responses`. |
| responseTemplates | [x-amazon-apigateway-integration.oggetto responseTemplates](api-gateway-swagger-extensions-integration-responseTemplates.md) | Indica i modelli di mappatura specifici del tipo MIME per il payload della risposta. |
| responseParameters | [x-amazon-apigateway-integration.ResponseParameters](api-gateway-swagger-extensions-integration-responseParameters.md) | Specifica le mappature dei parametri per la risposta. Solo i parametri `header` e `body` della risposta di integrazione possono essere mappati ai parametri `header` del metodo. |
| contentHandling | string | Tipi di conversione per la codifica del payload delle risposte. Valori validi sono 1) CONVERT\$1TO\$1TEXT, per la conversione di un payload binario in una stringa con codifica base64 o per la conversione di un payload di testo in una stringa con codifica utf-8 o per passare il payload di testo in modo nativo senza modifica e 2) CONVERT\$1TO\$1BINARY, per la conversione di un payload di testo nel BLOB con decodifica base64 o per passare un payload binario in modo nativo senza modifica. |
## `x-amazon-apigateway-integration.response`Esempio
L'esempio che segue definisce una risposta `302` per il metodo che deriva un payload del tipo MIME `application/json` o `application/xml` dal back-end. La risposta usa i modelli di mappatura forniti e restituisce l'URL di reindirizzamento dalla risposta di integrazione nell'intestazione `Location` del metodo.
```
{
"statusCode" : "302",
"responseTemplates" : {
"application/json" : "#set ($root=$input.path('$')) { \"stage\": \"$root.name\", \"user-id\": \"$root.key\" }",
"application/xml" : "#set ($root=$input.path('$')) $root.name "
},
"responseParameters" : {
"method.response.header.Location": "integration.response.body.redirect.url"
}
}
```
# x-amazon-apigateway-integration.oggetto responseTemplates
Specifica i modelli di mappatura per un payload di risposta dei tipi MIME specificati.
| Nome proprietà | Tipo | Descrizione |
| --- | --- | --- |
| MIME type | string | Specifica un modello di mappatura per trasformare il corpo della risposta di integrazione nel corpo della risposta di metodo per un tipo MIME specificato. Per informazioni su come creare un modello di mappatura, consulta [Trasformazioni dei modelli di mappatura per REST APIs in API Gateway](models-mappings.md). Un esempio di is. *MIME type* `application/json` |
## x-amazon-apigateway-integrationEsempio di .responseTemplate
Il modello seguente imposta i modelli di mappatura per un payload di richiesta de tipi MIME `application/json` e `application/xml`.
```
"responseTemplates" : {
"application/json" : "#set ($root=$input.path('$')) { \"stage\": \"$root.name\", \"user-id\": \"$root.key\" }",
"application/xml" : "#set ($root=$input.path('$')) $root.name "
}
```
# x-amazon-apigateway-integration.ResponseParameters
Specifica le mappature dai parametri delle risposte dei metodi di integrazione ai parametri delle risposte di metodo. Puoi mappare `header`, `body` o valori statici al tipo `header` della risposta dei metodi. Supportato solo per REST. APIs
| Nome proprietà | Tipo | Description |
| --- | --- | --- |
| method.response.header. | string | Il valore di parametro denominato può essere derivato dai tipi `header` e `body` di parametri delle risposte di integrazione. |
## `x-amazon-apigateway-integration.responseParameters` Esempio
L'esempio seguente mappa i parametri `body` e `header` della risposta di integrazione a due parametri `header` della risposta di metodo.
```
"responseParameters" : {
"method.response.header.Location" : "integration.response.body.redirect.url",
"method.response.header.x-user-id" : "integration.response.header.x-userid"
}
```
# x-amazon-apigateway-integrationOggetto.TLSConfig
Specifica la configurazione TLS per un'integrazione.
| Nome proprietà | Tipo | Description |
| --- | --- | --- |
| insecureSkipVerification | Boolean | Supportato solo per REST. APIs Specifica se API Gateway ignora o meno la verifica che il certificato per un endpoint di integrazione sia emesso da un'[autorità di certificazione supportata](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-supported-certificate-authorities-for-http-endpoints.html). Questa operazione non è consigliata, ma consente di utilizzare certificati firmati da autorità di certificazione private o certificati autofirmati. Se abilitato, API Gateway esegue comunque la convalida di base del certificato, che include il controllo della data di scadenza, del nome host e della presenza di un'autorità di certificazione root del certificato. Il certificato radice appartenente all'autorità privata deve soddisfare i seguenti vincoli: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/api-gateway-extensions-integration-tls-config.html) Supportato solo per integrazioni `HTTP` e `HTTP_PROXY`. L'abilitazione di `insecureSkipVerification` non è consigliata, soprattutto per le integrazioni con endpoint HTTPS pubblici. Se abiliti`insecureSkipVerification`, aumenti il rischio di man-in-the-middle attacchi. |
| serverNameToVerify | string | Supportato solo per le integrazioni private API HTTP. Se si specifica un nome server, API Gateway lo utilizza per verificare il nome host sul certificato dell'integrazione. Il nome del server è incluso anche nell'handshake TLS per supportare SNI (Server Name Indication) o l'hosting virtuale. |
## x-amazon-apigateway-integrationEsempi in formato.TLSConfig
L'esempio seguente di OpenAPI 3.0 abilita `insecureSkipVerification` per un'integrazione del proxy HTTP API REST.
```
"x-amazon-apigateway-integration": {
"uri": "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses": {
default": {
"statusCode": "200"
}
},
"passthroughBehavior": "when_no_match",
"httpMethod": "ANY",
"tlsConfig" : {
"insecureSkipVerification" : true
}
"type": "http_proxy",
}
```
L'esempio seguente di OpenAPI 3.0 specifica un `serverNameToVerify` per un'integrazione privata API HTTP.
```
"x-amazon-apigateway-integration" : {
"payloadFormatVersion" : "1.0",
"connectionId" : "abc123",
"type" : "http_proxy",
"httpMethod" : "ANY",
"uri" : "arn:aws:elasticloadbalancing:us-west-2:123456789012:listener/app/my-load-balancer/50dc6c495c0c9188/0467ef3c8400ae65",
"connectionType" : "VPC_LINK",
"tlsConfig" : {
"serverNameToVerify" : "example.com"
}
}
```
# x-amazon-apigateway-minimum-dimensione di compressione
Specifica la dimensione minima di compressione per un'API REST. Per abilitare la compressione, specificare un numero intero compreso tra 0 e 10485760. Per ulteriori informazioni, consulta [Compressione del payload per REST APIs in API Gateway](api-gateway-gzip-compression-decompression.md).
## x-amazon-apigateway-minimum-esempio di dimensioni di compressione
Nell'esempio seguente viene specificata una dimensione minima di compressione di `5242880` byte per un'API REST.
```
"x-amazon-apigateway-minimum-compression-size": 5242880
```
# x-amazon-apigateway-policy
Specifica una policy delle risorse per un'API REST. Per ulteriori informazioni sulle policy delle risorse, consulta [Controllo degli accessi a una REST API con le policy delle risorse Gateway API](apigateway-resource-policies.md). Per esempi di policy delle risorse, consulta [Esempi di policy delle risorse API Gateway](apigateway-resource-policies-examples.md).
## `x-amazon-apigateway-policy`Esempio
Nell'esempio seguente viene specificata una policy delle risorse per un'API REST. La policy delle risorse nega (blocca) il traffico in entrata a un'API da un blocco di indirizzi IP di origine specificato. Al momento dell'importazione, `"execute-api:/*"` viene convertito in`arn:aws:execute-api:region:account-id:api-id/*`, utilizzando la regione corrente, l'ID AWS dell'account e l'ID API REST corrente.
```
"x-amazon-apigateway-policy": {
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
]
},
{
"Effect": "Deny",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
],
"Condition" : {
"IpAddress": {
"aws:SourceIp": "192.0.2.0/24"
}
}
}
]
}
```
# x-amazon-apigateway-requestproprietà -validator
Specifica un validatore di richiesta facendo riferimento a `request_validator_name` della mappa [x-amazon-apigateway-requestoggetto -validators](api-gateway-swagger-extensions-request-validators.md) per abilitare la convalida della richiesta in un metodo o nell'API che la contiene. Il valore di questa estensione è una stringa JSON.
Questa estensione può essere specificata a livello di API o a livello di metodo. Il validatore a livello di API si applica a tutti i metodi, a meno che non venga ignorato dal validatore a livello di metodo.
## `x-amazon-apigateway-request-validator`Esempio
L'esempio che segue applica il validatore di richieste `basic` a livello d API, mentre applica il validatore di richieste `parameter-only` per la richiesta `POST /validation`.
------
#### [ OpenAPI 2.0 ]
```
{
"swagger": "2.0",
"x-amazon-apigateway-request-validators" : {
"basic" : {
"validateRequestBody" : true,
"validateRequestParameters" : true
},
"params-only" : {
"validateRequestBody" : false,
"validateRequestParameters" : true
}
},
"x-amazon-apigateway-request-validator" : "basic",
"paths": {
"/validation": {
"post": {
"x-amazon-apigateway-request-validator" : "params-only",
...
}
}
```
------
# x-amazon-apigateway-requestoggetto -validators
Definisce i validatori di richieste supportati per l'API che le contiene come mappa tra un nome di validatore e le regole di convalida delle richieste associate. Questa estensione si applica a un'API REST.
| Nome proprietà | Tipo | Descrizione |
| --- | --- | --- |
| `request_validator_name` | [x-amazon-apigateway-request-Validators.RequestValidator oggetto](api-gateway-swagger-extensions-request-validators.requestValidator.md) | Specifica le regole di convalida costituite dal validatore denominato. Ad esempio: "basic" : {
"validateRequestBody" : true,
"validateRequestParameters" : true
},
Per applicare il validatore a un metodo specifico, fai riferimento al rispettivo nome (`basic`) come al valore della proprietà [x-amazon-apigateway-requestproprietà -validator](api-gateway-swagger-extensions-request-validator.md). |
## `x-amazon-apigateway-request-validators`Esempio
L'esempio che segue mostra un set di validatori di richieste per un'API come mappa tra un nome di validatore e le regole di convalida delle richieste associate.
------
#### [ OpenAPI 2.0 ]
```
{
"swagger": "2.0",
...
"x-amazon-apigateway-request-validators" : {
"basic" : {
"validateRequestBody" : true,
"validateRequestParameters" : true
},
"params-only" : {
"validateRequestBody" : false,
"validateRequestParameters" : true
}
},
...
}
```
------
# x-amazon-apigateway-request-Validators.RequestValidator oggetto
Specifica le regole di convalida di un validatore di richieste nell'ambito della definizione della mappa [x-amazon-apigateway-requestoggetto -validators](api-gateway-swagger-extensions-request-validators.md).
| Nome proprietà | Tipo | Descrizione |
| --- | --- | --- |
| `validateRequestBody` | Boolean | Specifica se convalidare (`true`) o non convalidare (`false`) il corpo della richiesta. |
| `validateRequestParameters` | Boolean | Specifica se convalidare (`true`) o non convalidare (`false`) i parametri di richiesta necessari. |
## `x-amazon-apigateway-request-validators.requestValidator`Esempio
L'esempio seguente mostra un validatore di risposte di soli parametri.
```
"params-only": {
"validateRequestBody" : false,
"validateRequestParameters" : true
}
```
# x-amazon-apigateway-security-politica
Specifica una politica di sicurezza per un'API REST. Se si crea una politica di sicurezza che inizia con`"SecurityPolicy_"`, è necessario impostare anche la modalità di [accesso agli endpoint](openapi-extensions-endpoint-access-mode.md). Per ulteriori informazioni sulle politiche di sicurezza, consulta[Politiche di sicurezza per REST APIs in API Gateway](apigateway-security-policies.md).
## `x-amazon-apigateway-security-policy` Esempio
L'esempio seguente specifica `SecurityPolicy_TLS13_1_3_2025_0` un'API REST.
```
"x-amazon-apigateway-security-policy": "SecurityPolicy_TLS13_1_3_2025_09"
```
# x-amazon-apigateway-tagproprietà -value
Specifica il valore di un [tag AWS](https://docs.aws.amazon.com/tag-editor/latest/userguide/tagging.html) per un'API HTTP. È possibile utilizzare la `x-amazon-apigateway-tag-value` proprietà come parte dell'oggetto [tag OpenAPI a livello di root per AWS specificare i tag per un'API](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#tag-object) HTTP. Se specifichi un nome tag senza la proprietà `x-amazon-apigateway-tag-value`, API Gateway crea un tag con una stringa vuota per un valore.
Per ulteriori informazioni sul tagging, consulta [Tagging delle risorse API Gateway](apigateway-tagging.md).
| Nome proprietà | Tipo | Descrizione |
| --- | --- | --- |
| `name` | String | Specifica la chiave di tag. |
| `x-amazon-apigateway-tag-value` | String | Specifica il valore del tag. |
## `x-amazon-apigateway-tag-value`Esempio
L'esempio seguente specifica due tag per un'API HTTP:
+ "Owner": "Admin"
+ "Prod": ""
```
"tags": [
{
"name": "Owner",
"x-amazon-apigateway-tag-value": "Admin"
},
{
"name": "Prod"
}
]
```