Status

Тип Status определяет логическую модель ошибок, подходящую для различных сред программирования, включая API REST и API RPC. Он используется gRPC . Модель ошибок спроектирована так, чтобы:

  • Простой в использовании и понятный для большинства пользователей
  • Достаточно гибкий, чтобы удовлетворить неожиданные потребности

Обзор

Сообщение Status содержит три части данных: код ошибки, сообщение об ошибке и сведения об ошибке. Код ошибки должен быть перечислением google.rpc.Code , но при необходимости он может принимать дополнительные коды ошибок. Сообщение об ошибке должно быть обращено к разработчику на английском языке и поможет разработчикам понять и устранить ошибку. Если требуется локализованное сообщение об ошибке для пользователя, поместите локализованное сообщение в сведения об ошибке или локализуйте его в клиенте. Необязательные сведения об ошибке могут содержать произвольную информацию об ошибке. В пакете google.rpc имеется предопределенный набор типов сведений об ошибках, которые можно использовать для устранения распространенных ошибок.

Языковое сопоставление

Сообщение Status является логическим представлением модели ошибки, но оно не обязательно соответствует фактическому формату провода. Когда сообщение Status отображается в разных клиентских библиотеках и разных проводных протоколах, оно может отображаться по-разному. Например, он, скорее всего, будет сопоставлен с некоторыми исключениями в Java, но, скорее всего, будет сопоставлен с некоторыми кодами ошибок в C.

Другое использование

Модель ошибок и сообщение Status можно использовать в различных средах, как с API, так и без них, чтобы обеспечить единообразие работы разработчиков в разных средах.

Примеры использования этой модели ошибок включают в себя:

  • Частичные ошибки. Если службе необходимо вернуть клиенту частичные ошибки, она может встроить Status в обычный ответ, чтобы указать на частичные ошибки.

  • Ошибки рабочего процесса. Типичный рабочий процесс состоит из нескольких этапов. Каждый шаг может иметь сообщение Status для сообщения об ошибках.

  • Пакетные операции. Если клиент использует пакетный запрос и пакетный ответ, сообщение Status должно использоваться непосредственно внутри пакетного ответа, по одному для каждого подответа на ошибку.

  • Асинхронные операции. Если вызов API включает в себя результаты асинхронной операции, статус этих операций должен быть представлен непосредственно с помощью сообщения Status .

  • Ведение журнала. Если некоторые ошибки API сохраняются в журналах, Status сообщения можно использовать сразу после любого удаления, необходимого по соображениям безопасности/конфиденциальности.

JSON-представление
{
  "code": number,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Поля
code

number

Код состояния, который должен быть значением перечисления google.rpc.Code .

message

string

Сообщение об ошибке для разработчика, которое должно быть на английском языке. Любое сообщение об ошибке, обращенное к пользователю, должно быть локализовано и отправлено в поле google.rpc.Status.details или локализовано клиентом.

details[]

object

Список сообщений, содержащих сведения об ошибке. Существует общий набор типов сообщений для использования API.

Объект, содержащий поля произвольного типа. Дополнительное поле "@type" содержит URI, идентифицирующий тип. Пример: { "id": 1234, "@type": "types.example.com/standard/id" } .