x-yc-apigateway-integration:cloud_functions extension
Written by
Updated at April 24, 2025
The x-yc-apigateway-integration:cloud_functions extension invokes the relevant function. As its input, the function accepts the HTTP request data and values of the properties listed in the specification. As the output, it returns the result of function execution to the client.
You can add an extension to a specification using the specification constructor.
Supported parameters
The table below lists the parameters specific to API Gateway API gateways. You can find the description of other parameters in the OpenAPI 3.0 specification.
| Parameter | Type | Description |
|---|---|---|
function_id |
string |
Function ID. |
tag |
string |
This is an optional parameter. It specifies the tag of the function version. The default value is $latest. The parameters are subsituted into tag. |
service_account_id |
string |
ID of the service account used for authorization when accessing the function. Invoking a function requires a service account with the functions.functionInvoker role or higher for that function. If you omit the parameter, the service_account_id top-level parameter value will be used. If the top-level parameter is also missing, the function is invoked without authorization. |
payload_format_version |
string |
Function call format version. It can be either 0.1 or 1.0. 0.1 is the default version. |
context |
object |
This is an optional parameter. It provides the operation context, i.e., an object in YAML or JSON format. It is provided to a function within a request in the requestContext.apiGateway.operationContext field. The parameters are subsituted into context. |
Extension specification
Specification example:
/example/{ID}:
get:
summary: Get ID
operationId: getID
tags:
- example
parameters:
- name: ID
in: path
description: Return ID
required: true
schema:
type: string
x-yc-apigateway-integration:
type: cloud_functions
function_id: b095c95icnvb********
tag: "$latest"
service_account_id: ajehfe56hhl********
Function example:
exports.handler= async function (data, context) {
return {
'statusCode': 200,
'isBase64Encoded': false,
'body': JSON.stringify({
'petId': data.params.ID
}),
}
};
Request structure for v0.1
The request JSON structure for version 0.1 replicates the structure of a request to a function with some additional fields:
{
"url": <actual request path>,
"path": <path matching specification request>,
"httpMethod": <HTTP method name>,
"headers": <dictionary with HTTP header string values>,
"multiValueHeaders": <dictionary with lists of HTTP header values>,
"queryStringParameters": <dictionary of queryString parameters>,
"multiValueQueryStringParameters": <dictionary with lists of queryString parameter values>,
"requestContext": <dictionary with request context>,
"body": <request contents>,
"isBase64Encoded": <true or false>,
"pathParams": <dictionary of request path parameter values>,
"params": <dictionary of request parameter values as described in the OpenAPI spec>,
"multiValueParams": <dictionary with request parameter value lists as described in the OpenAPI spec>
}
Request structure for v1.0
The request JSON structure for version 1.0 is compatible with the request format for AWS API Gateway version 1.0 with some additional fields:
{
"version": <request format version>,
"resource": <resource matching specification request>,
"path": <actual request path>,
"httpMethod": <HTTP method name>,
"headers": <dictionary with HTTP header string values>,
"multiValueHeaders": <dictionary with lists of HTTP header values>,
"queryStringParameters": <dictionary of queryString parameters>,
"multiValueQueryStringParameters": <dictionary with lists of queryString parameter values>,
"requestContext": <dictionary with request context>,
"pathParameters": <dictionary of request path parameter values>,
"body": <request contents>,
"isBase64Encoded": <true or false>,
// additional fields:
"parameters": <dictionary of request parameter values as described in the OpenAPI spec>,
"multiValueParameters": <dictionary with request parameter value lists as described in the OpenAPI spec>,
"operationId": <operationId matching the request in the OpenAPI spec>
}
Structure of the requestContext element:
{
"identity": <a set of key:value pairs to authenticate the user>,
"httpMethod": <DELETE, GET, HEAD, OPTIONS, PATCH, POST, or PUT>,
"requestId": <request ID generated in the router>,
"requestTime": <request time in CLF format>,
"requestTimeEpoch": <request time in Unix format>,
"authorizer": <dictionary with authorization context>,
"apiGateway": <dictionary with specific data transmitted by API gateway during function invocation>,
"connectionId": <web socket connection ID>",
"connectedAt": <web socket connection time>,
"eventType": <type of web socket event or operation: CONNECT, MESSAGE, DISCONNECT>,
"messageId": <ID of the message received from the web socket>,
"disconnectStatusCode": <web socket close code>,
"disconnectReason": <text description of the reason the web socket was closed>
}
Structure of the authorizer element:
{
"jwt": { // Field filled in by the API Gateway JWT authorizer. It contains the token data about the user and the user's permissions'
"claims": <dictionary of JWT body fields>,
"scopes": <list of JWT owner permissions>
}
// Other authorization context fields returned from the authorizer function
}