Подключиться
Войти
Yandex Cloud Functions

Вызов функции

Функцию можно вызвать:

Для каждого способа есть определенная структура данных запроса к функции и ответа функции.

Вызов функции с помощью HTTP

Если функция вызывается для обработки HTTP-запроса, то она получает данные о запросе в формате JSON: название HTTP-метода, заголовки запроса, аргументы строки запроса и другие параметры, описывающие HTTP-запрос.

Результат, который возвращает функция, также должен представлять из себя JSON-документ, содержащий код ответа HTTP, заголовки ответа и содержимое ответа. Cloud Functions автоматически обработает этот JSON, и пользователь получит данные в виде стандартного HTTP-ответа.

Возможен запуск функции с указанием параметра строки запроса integration=raw. При использовании такой формы вызова функция не может анализировать и задавать HTTP-заголовки. В качестве входных данных в функцию будет передано содержимое тела запроса без каких-либо преобразований, и результат также будет напрямую возвращен из функции с HTTP-статусом ответа 200.

Структура данных запроса

JSON-структура запроса:

{
    "httpMethod": "<название HTTP метода>",
    "headers": "<словарь со строковыми значениями HTTP-заголовков>",
    "multiValueHeaders": "<словарь со списками значений HTTP-заголовков>",
    "queryStringParameters": "<словарь queryString-параметров>",
    "multiValueQueryStringParameters": "<словарь списков значений queryString-параметров>",
    "requestContext": "<словарь с контекстом запроса>",
    "body": "<содержимое запроса>",
    "isBase64Encoded": <true или false>
}

Подробное описание запроса:

  • httpMethod — название HTTP метода, такое как: DELETE, GET, HEAD, OPTIONS, PATCH, POST или PUT.

  • headers — словарь строк, содержащий HTTP-заголовки запроса и их значения. Если один и тот же заголовок передан несколько раз, словарь содержит последнее переданное значение.

  • multiValueHeaders — словарь, содержащий HTTP-заголовки запроса и списки с их значениями. Он содержит те же самые ключи, что и словарь headers, но если какой-либо заголовок повторялся несколько раз, список для него будет содержать все переданные значения для данного заголовка. Если заголовок был передан всего один раз, он включается в этот словарь, и список для него будет содержать одно значение.

  • queryStringParameters — словарь, содержащий параметры запроса. Если один и тот же параметр указан несколько раз, словарь содержит последнее указанное значение.

  • multiValueQueryStringParameters — словарь, содержащий для каждого параметра запроса список со всеми указанными значениями. Если один и тот же параметр указан несколько раз, словарь содержит все указанные значения.

  • requestContext

    Содержит данные следующей структуры:

    {
    "identity": "<набор пар ключ:значение для аутентификации пользователя>",
    "httpMethod": "<DELETE, GET, HEAD, OPTIONS, PATCH, POST или PUT>",
    "requestId": "<ID запроса, генерируется в роутере>",
    "requestTime": "<время запроса в формате CLF>",
    "requestTimeEpoch": "<время запроса в формате Unix>"
}

    Структура элемента identity:

    {
    "sourceIp": "<адрес, с которого был сделан запрос>",
    "userAgent": "<содержимое HTTP-заголовка User-Agent исходного запроса>"
}

  • body — содержимое запроса в виде строки, содержащей JSON или двоичные данные в формате Base64.

  • isBase64Encoded — если значение параметра true, то body содержит данные закодированные в Base64.

Структура данных ответа

JSON-структура ответа:

{
    "statusCode": <HTTP код ответа>,
    "headers": "<словарь со строковыми значениями HTTP-заголовков>",
    "multiValueHeaders": "<словарь со списками значений HTTP-заголовков>",
    "body": "<содержимое ответа>",
    "isBase64Encoded": <true или false>
}

Подробное описание ответа:

  • statusCode — код состояния HTTP, по которому клиент узнаёт результаты запроса.

  • headers — словарь строк, содержащий HTTP-заголовки ответа и их значения.

  • multiValueHeaders — словарь, в котором для HTTP-заголовков ответа можно указать одно или несколько значений в виде списка. Если один и тот же заголовок указан и в headers и в multiValueHeaders, содержимое headers игнорируется.

  • body — содержимое ответа в виде строки, содержащей JSON или двоичные данные в формате Base64.

  • isBase64Encoded — если значение параметра true, то body содержит данные закодированные в Base64.

Заголовки сообщений

Ваша функция получает и передает содержимое HTTP-заголовков в виде полей JSON-структуры, как описано выше. Некоторые заголовки запроса и ответа удаляются или переименовываются, как описано ниже.

Удаляются из запроса:

  • "Expect"
  • "Te"
  • "Trailer"
  • "Upgrade"
  • "Proxy-Authenticate"
  • "Authorization"
  • "Connection"
  • "Content-Md5"
  • "Max-Forwards"
  • "Server"
  • "Transfer-Encoding"
  • "Www-Authenticate"
  • "Cookie"

  • Удаляются из ответа:

    • "Host"
    • "Authorization"
    • "User-Agent"
    • "Connection"
    • "Max-Forwards"
    • "Cookie"

  • Вызывают ошибку, если присутствуют в ответе:

    • "Proxy-Authenticate"
    • "Transfer-Encoding"
    • "Via"
    • "Www-Authenticate"

  • Перезаписываются с добавлением префикса X-Yf-Remapped-:

    • "Content-Md5"
    • "Date"
    • "Server"

Обработка ошибок в коде пользовательской функции

Список кодов состояния

  • 200 OK — функция успешно выполнена.
  • 400 BadRequest — ошибка в параметрах HTTP-запроса.
  • 401 Unauthorized — ошибка авторизации сервиса, от которого зависит Cloud Functions.
  • 403 Forbidden — запрос не может быть выполнен из-за ограничений в доступе для клиента к указанному ресурсу.
  • 404 Not Found — по указанному URL не найден соответствующий ресурс.
  • 429 TooManyRequests — превышение максимального количества одновременно выполняемых запросов.
  • 500 Internal Server Error — внутренняя ошибка сервера.
  • 502 BadGateway — ошибка в коде функции или в формате возвращаемого JSON-ответа.
  • 503 Service Unavailable — недоступность сервиса, от которого зависит Cloud Functions.
  • 504 Gateway Timeout — превышено максимальное время выполнения функции до таймаута.

В случае ошибки в пользовательской функции добавляется заголовок ответа X-Function-Error: true.

Результат в случае возникновения ошибки в пользовательском коде

В случае возникновения необработанной ошибки в пользовательском коде, Cloud Functions вернет результат с кодом ошибки 502 и подробным описанием ошибки в виде следующей JSON-структуры:

{
  "errorMessage": <сообщение ошибки>,
  "errorType": <тип ошибки>,
  "stackTrace": <список вызываемых методов>
}

Подробное описание ошибки:

  • errorMessage

    Строка с описанием ошибки.

  • errorType

    Зависящий от языка программирования тип ошибки или исключения.

  • stackTrace

    Список строк, описывающих стек выполнения функции в момент возникновения ошибки.

Конкретное содержимое указанных полей зависит от языка программирования и среды выполнения вашей функции.

Вызов функции с помощью YC CLI

Вызов функции с помощью CLI — это HTTP-запрос с методом POST и параметром integration=raw. Подробнее данный параметр описан выше.

Посмотрите справку о команде вызова функции:

yc serverless function invoke --help
Invoke the specified function

Usage:
  yc serverless function invoke <FUNCTION-NAME>|<FUNCTION-ID> [Flags...] [Global Flags...]

Flags:
      --id string          Function id.
      --name string        Function name.
      --tag string         Tag. Default $latest.
  -d, --data string        Data to be sent
      --data-file string   Data (file location) to be sent
      --data-stdin         Await stdin for data to be sent

Подробное описание способов передачи данных с использованием разных флагов и аргументов:

  • Флаг или аргумент не указан — передается пустая строка.

  • -d, --data — данные передаются как аргумент.

    yc serverless function invoke b09bhaokchn9pnbrlseb -d '{"queryStringParameters": {"parameter_name": "parameter_value"}}'

  • --data-file — данные читаются из файла.

    yc serverless function invoke b09bhaokchn9pnbrlseb --data-file <путь к файлу>

    Аналогично команде с аргументом -d, имеющим значение @<имя файла>: yc serverless function invoke b09bhaokchn9pnbrlseb -d @<путь к файлу>

  • --data-stdin — данные читаются из потока ввода.

    echo '{"queryStringParameters": "name"}' | yc serverless function invoke b09bhaokchn9pnbrlseb --data-stdin

    Аналогично команде с аргументом -d, имеющим значение @-:

    echo '{"queryStringParameters": "name"}' | yc serverless function invoke b09bhaokchn9pnbrlseb -d @-`.