ПРИМЕЧАНИЕ. Этот сайт устарел. Сайт будет отключен после 31 января 2023 года, и трафик будет перенаправлен на новый сайт по адресу https://protobuf.dev . А пока обновления будут производиться только для protobuf.dev.

Package google.protobuf

Индекс

Любой

Any содержит произвольное сериализованное сообщение вместе с URL-адресом, который описывает тип сериализованного сообщения.

JSON

В представлении значения Any в формате JSON используется обычное представление десериализованного встроенного сообщения с дополнительным полем @type , которое содержит URL-адрес типа. Пример:

package google.profile;
message Person {
  string first_name = 1;
  string last_name = 2;
}

{
  "@type": "type.googleapis.com/google.profile.Person",
  "firstName": <string>,
  "lastName": <string>
}

Если встроенный тип сообщения хорошо известен и имеет настраиваемое представление JSON, это представление будет внедрено с добавлением value поля, которое содержит настраиваемый JSON в дополнение к полю @type . Пример (для сообщения google.protobuf.Duration ):

{
  "@type": "type.googleapis.com/google.protobuf.Duration",
  "value": "1.212s"
}
Имя поля Тип Описание
type_url string

URL-адрес/имя ресурса, содержание которого описывает тип сериализованного сообщения.

Для URL-адресов, которые используют схему http , https или не используют схему, применяются следующие ограничения и интерпретации:

  • Если схема не указана, предполагается https .
  • Последний сегмент пути URL-адреса должен представлять полное имя типа (как в path/google.protobuf.Duration ).
  • HTTP GET для URL-адреса должен возвращать значение google.protobuf.Type в двоичном формате или выдавать ошибку.
  • Приложениям разрешено кэшировать результаты поиска на основе URL-адреса или предварительно компилировать их в двоичный файл, чтобы избежать любого поиска. Следовательно, бинарная совместимость должна сохраняться при изменении типов. (Используйте версионные имена типов для управления критическими изменениями.)

Схемы, отличные от http , https (или пустой схемы), могут использоваться с семантикой, специфичной для реализации.

value bytes Должны быть действительными сериализованными данными указанного выше типа.

Апи

Api — это упрощенный дескриптор службы буфера протокола.

Имя поля Тип Описание
name string Полное имя этого API, включая имя пакета, за которым следует простое имя API.
methods Method Методы этого API в неопределенном порядке.
options Option Любые метаданные, прикрепленные к API.
version string

Строка версии для этого API. Если указано, должно иметь вид major-version.minor-version , как в 1.10 . Если младшая версия не указана, по умолчанию она равна нулю. Если все поле версии пусто, основная версия получается из имени пакета, как показано ниже. Если поле не пустое, версия в имени пакета будет проверена на соответствие тому, что здесь указано.

Схема управления версиями использует семантическое управление версиями, где основной номер версии указывает на критическое изменение, а второстепенная версия — на добавочное некритическое изменение. Оба номера версии сигнализируют пользователям, чего ожидать от разных версий, и их следует тщательно выбирать на основе плана продукта.

Основная версия также отражается в имени пакета API, которое должно заканчиваться на v<major-version> , например google.feature.v1 . Для основных версий 0 и 1 суффикс можно не указывать. Нулевые основные версии должны использоваться только для экспериментальных API без GA.

source_context SourceContext Исходный контекст для службы буфера протокола, представленной этим сообщением.
mixins Mixin Включенные API. См. Mixin .
syntax Syntax Исходный синтаксис службы.

логическое значение

Сообщение-оболочка для bool .

Представление JSON для BoolValue — это JSON true и false .

Имя поля Тип Описание
value bool Логическое значение.

BytesValue

Сообщение-оболочка для bytes .

Представление JSON для BytesValue — это строка JSON.

Имя поля Тип Описание
value bytes Значение байтов.

Двойное значение

Сообщение-обертка для double .

Представление JSON для DoubleValue — это номер JSON.

Имя поля Тип Описание
value double Двойное значение.

Продолжительность

Duration представляет собой подписанный промежуток времени фиксированной длины, представленный в виде количества секунд и долей секунд с разрешением в наносекунды. Он не зависит ни от какого календаря и таких понятий, как «день» или «месяц». Это связано с меткой времени в том, что разница между двумя значениями метки времени представляет собой продолжительность, и ее можно добавить или вычесть из метки времени. Диапазон составляет примерно +-10 000 лет.

Пример 1. Вычисление продолжительности по двум временным меткам в псевдокоде.

Timestamp start = ...;
Timestamp end = ...;
Duration duration = ...;

duration.seconds = end.seconds - start.seconds;
duration.nanos = end.nanos - start.nanos;

if (duration.seconds < 0 && duration.nanos > 0) {
  duration.seconds += 1;
  duration.nanos -= 1000000000;
} else if (duration.seconds > 0 && duration.nanos < 0) {
  duration.seconds -= 1;
  duration.nanos += 1000000000;
}

Пример 2. Вычисление временной метки из временной метки + длительность в псевдокоде.

Timestamp start = ...;
Duration duration = ...;
Timestamp end = ...;

end.seconds = start.seconds + duration.seconds;
end.nanos = start.nanos + duration.nanos;

if (end.nanos < 0) {
  end.seconds -= 1;
  end.nanos += 1000000000;
} else if (end.nanos >= 1000000000) {
  end.seconds += 1;
  end.nanos -= 1000000000;
}

Представление JSON для Duration — это String , оканчивающаяся на s для обозначения секунд, перед которой указано число секунд, а наносекунды выражены в виде долей секунды.

Имя поля Тип Описание
seconds int64 Секунды со знаком промежутка времени. Должно быть от -315 576 000 000 до +315 576 000 000 включительно.
nanos int32 Доли секунды со знаком при наносекундном разрешении промежутка времени. Продолжительность менее одной секунды представлена ​​полем 0 seconds и положительным или отрицательным полем nanos . Для длительности в одну секунду и более ненулевое значение поля nanos должно иметь тот же знак, что и поле seconds . Должно быть от -999 999 999 до +999 999 999 включительно.

Пустой

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

service Foo {
  rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);
}

Представление JSON для Empty — это пустой объект JSON {} .

перечисление

Определение типа перечисления.

Имя поля Тип Описание
name string Имя типа перечисления.
enumvalue EnumValue Определения значений перечисления.
options Option Параметры буфера протокола.
source_context SourceContext Исходный контекст.
syntax Syntax Исходный синтаксис.

EnumValue

Определение значения перечисления.

Имя поля Тип Описание
name string Имя значения перечисления.
number int32 Номер значения перечисления.
options Option Параметры буфера протокола.

Поле

Одно поле типа сообщения.

Имя поля Тип Описание
kind Kind Тип поля.
cardinality Cardinality Мощность поля.
number int32 Номер поля.
name string Имя поля.
type_url string URL-адрес типа поля без схемы для типов сообщения или перечисления. Пример: "type.googleapis.com/google.protobuf.Timestamp" .
oneof_index int32 Индекс типа поля в Type.oneofs для типов сообщения или перечисления. Первый тип имеет индекс 1; ноль означает, что тип отсутствует в списке.
packed bool Использовать ли альтернативное представление упакованной проволоки.
options Option Параметры буфера протокола.
json_name string Имя поля JSON.
default_value string Строковое значение значения по умолчанию для этого поля. Только синтаксис Proto2.

Мощность

Является ли поле необязательным, обязательным или повторяющимся.

Значение перечисления Описание
CARDINALITY_UNKNOWN Для полей с неизвестной кардинальностью.
CARDINALITY_OPTIONAL Для необязательных полей.
CARDINALITY_REQUIRED Для обязательных полей. Только синтаксис Proto2.
CARDINALITY_REPEATED Для повторяющихся полей.

вид

Основные типы полей.

Значение перечисления Описание
TYPE_UNKNOWN Тип поля неизвестен.
TYPE_DOUBLE Тип поля двойной.
TYPE_FLOAT Тип поля плавающий.
TYPE_INT64 Тип поля int64.
TYPE_UINT64 Тип поля uint64.
TYPE_INT32 Тип поля int32.
TYPE_FIXED64 Тип поля фиксированный64.
TYPE_FIXED32 Тип поля фиксированный32.
TYPE_BOOL Тип поля bool.
TYPE_STRING Строка типа поля.
TYPE_GROUP Группа типов полей. Только синтаксис Proto2 и устарел.
TYPE_MESSAGE Сообщение типа поля.
TYPE_BYTES Байты типа поля.
TYPE_UINT32 Тип поля uint32.
TYPE_ENUM Тип поля перечисление.
TYPE_SFIXED32 Тип поля фиксированный32.
TYPE_SFIXED64 Тип поля sfixed64.
TYPE_SINT32 Тип поля sint32.
TYPE_SINT64 Тип поля sint64.

Маска поля

FieldMask представляет собой набор путей к символическим полям, например:

paths: "f.a"
paths: "f.b.d"

Здесь f представляет поле в некотором корневом сообщении, поля a и b в сообщении, найденном в f , и d поле, найденное в сообщении в fb .

Маски полей используются для указания подмножества полей, которые должны быть возвращены операцией получения ( проекция ) или изменены операцией обновления. Маски полей также имеют пользовательскую кодировку JSON (см. ниже).

Маски полей в проекциях

Когда FieldMask указывает проекцию , API будет фильтровать ответное сообщение (или вложенное сообщение), чтобы оно содержало только те поля, которые указаны в маске. Например, рассмотрим это ответное сообщение «предварительной маскировки»:

f {
  a : 22
  b {
    d : 1
    x : 2
  }
  y : 13
}
z: 8

После применения маски в предыдущем примере ответ API не будет содержать определенных значений для полей x, y или z (их значения будут установлены по умолчанию и опущены в выводе прототекста):

f {
  a : 22
  b {
    d : 1
  }
}

Повторяющееся поле не допускается, за исключением последней позиции маски поля.

Если объект FieldMask отсутствует в операции получения, операция применяется ко всем полям (как если бы была указана FieldMask всех полей).

Обратите внимание, что маска поля не обязательно применяется к ответному сообщению верхнего уровня. В случае операции получения REST маска поля применяется непосредственно к ответу, но в случае операции списка REST маска вместо этого применяется к каждому отдельному сообщению в возвращаемом списке ресурсов. В случае пользовательского метода REST могут использоваться другие определения. Где применяется маска, будет четко задокументировано вместе с ее объявлением в API. В любом случае влияние на возвращаемый ресурс/ресурсы является обязательным поведением для API.

Маски полей в операциях обновления

Маска поля в операциях обновления указывает, какие поля целевого ресурса будут обновлены. API требуется только для изменения значений полей, указанных в маске, и оставить остальные нетронутыми. Если ресурс передается для описания обновленных значений, API игнорирует значения всех полей, не покрытых маской.

Чтобы сбросить значение поля до значения по умолчанию, поле должно быть в маске и установлено значение по умолчанию в предоставленном ресурсе. Следовательно, чтобы сбросить все поля ресурса, предоставьте экземпляр ресурса по умолчанию и установите все поля в маске или не предоставляйте маску, как описано ниже.

Если маска поля отсутствует при обновлении, операция применяется ко всем полям (как если бы была указана маска поля всех полей). Обратите внимание, что при наличии эволюции схемы это может означать, что поля, которые клиент не знает и поэтому не заполнил в запросе, будут сброшены к значениям по умолчанию. Если это нежелательное поведение, конкретная служба может потребовать от клиента всегда указывать маску поля, в противном случае будет выдано сообщение об ошибке.

Как и в случае с операциями получения, расположение ресурса, который описывает обновленные значения в сообщении запроса, зависит от типа операции. В любом случае эффект маски поля должен учитываться API.

Рекомендации по HTTP REST

HTTP-тип операции обновления, в которой используется маска поля, должен быть установлен на PATCH вместо PUT, чтобы соответствовать семантике HTTP (PUT должен использоваться только для полных обновлений).

JSON-кодирование масок полей

В JSON маска поля кодируется как одна строка, в которой пути разделены запятой. Имя полей в каждом пути преобразуется в/из соглашений об именах нижнего верблюда.

В качестве примера рассмотрим следующие объявления сообщений:

message Profile {
  User user = 1;
  Photo photo = 2;
}
message User {
  string display_name = 1;
  string address = 2;
}

В прототипе маска поля для Profile может выглядеть так:

mask {
  paths: "user.display_name"
  paths: "photo"
}

В JSON та же маска представлена ​​ниже:

{
  mask: "user.displayName,photo"
}
Имя поля Тип Описание
paths string Набор путей маски поля.

Плавающее значение

Сообщение-обертка для float .

Представление JSON для FloatValue — это число JSON.

Имя поля Тип Описание
value float Плавающее значение.

Int32Value

Сообщение-оболочка для int32 .

Представление JSON для Int32Value — это номер JSON.

Имя поля Тип Описание
value int32 Значение int32.

Int64Value

Сообщение-оболочка для int64 .

Представление JSON для Int64Value — это строка JSON.

Имя поля Тип Описание
value int64 Значение int64.

СписокЗначение

ListValue — это оболочка для повторяющегося поля значений.

Представление JSON для ListValue — это массив JSON.

Имя поля Тип Описание
values Value Повторяющееся поле динамически типизированных значений.

Метод

Метод представляет собой метод API.

Имя поля Тип Описание
name string Простое название этого метода.
request_type_url string URL-адрес типа входного сообщения.
request_streaming bool Если true, запрос передается в потоковом режиме.
response_type_url string URL типа выходного сообщения.
response_streaming bool Если это правда, ответ передается в потоковом режиме.
options Option Любые метаданные, прикрепленные к методу.
syntax Syntax Исходный синтаксис этого метода.

Миксин

Объявляет API для включения в этот API. Включающий API должен повторно объявить все методы включенного API, но документация и параметры наследуются следующим образом:

  • Если после удаления комментариев и пробелов строка документации повторно объявленного метода окажется пустой, она будет унаследована от исходного метода.

  • Каждая аннотация, принадлежащая конфигурации службы (http, видимость), которая не задана в переобъявленном методе, будет унаследована.

  • Если аннотация http унаследована, шаблон пути будет изменен следующим образом. Любой префикс версии будет заменен версией включающего API плюс root путь, если он указан.

Пример простого миксина:

package google.acl.v1;
service AccessControl {
  // Get the underlying ACL object.
  rpc GetAcl(GetAclRequest) returns (Acl) {
    option (google.api.http).get = "/v1/{resource=**}:getAcl";
  }
}

package google.storage.v2;
service Storage {
  //       rpc GetAcl(GetAclRequest) returns (Acl);

  // Get a data record.
  rpc GetData(GetDataRequest) returns (Data) {
    option (google.api.http).get = "/v2/{resource=**}";
  }
}

Пример конфигурации миксина:

apis:
- name: google.storage.v2.Storage
  mixins:
  - name: google.acl.v1.AccessControl

Конструкция примеси подразумевает, что все методы в AccessControl также объявлены с теми же именами и типами запроса/ответа в Storage . Генератор документации или процессор аннотаций увидит эффективный метод Storage.GetAcl после наследования документации и аннотаций следующим образом:

service Storage {
  // Get the underlying ACL object.
  rpc GetAcl(GetAclRequest) returns (Acl) {
    option (google.api.http).get = "/v2/{resource=**}:getAcl";
  }
  ...
}

Обратите внимание, как версия в шаблоне пути изменилась с v1 на v2 .

Если указано root поле в примеси, это должен быть относительный путь, под которым размещаются унаследованные пути HTTP. Пример:

apis:
- name: google.storage.v2.Storage
  mixins:
  - name: google.acl.v1.AccessControl
    root: acls

Это подразумевает следующую унаследованную аннотацию HTTP:

service Storage {
  // Get the underlying ACL object.
  rpc GetAcl(GetAclRequest) returns (Acl) {
    option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";
  }
  ...
}
Имя поля Тип Описание
name string Полное имя включенного API.
root string Если не пусто, указывает путь, по которому унаследованы пути HTTP.

нулевое значение

NullValue — это одноэлементное перечисление, представляющее нулевое значение для объединения типов Value .

Представление JSON для NullValue — это JSON null .

Значение перечисления Описание
NULL_VALUE Нулевое значение.

Вариант

Опция буфера протокола, которую можно прикрепить к сообщению, полю, перечислению и т. д.

Имя поля Тип Описание
name string Название опции. Например, "java_package" .
value Any Стоимость опции. Например, "com.google.protobuf" .

Исходный контекст

SourceContext представляет информацию об источнике элемента protobuf, например файле, в котором он определен.

Имя поля Тип Описание
file_name string Имя файла .proto с указанием пути, содержащего связанный элемент protobuf. Например: "google/protobuf/source.proto" .

Строковое значение

Сообщение-оболочка для string .

Представление JSON для StringValue — это строка JSON.

Имя поля Тип Описание
value string Строковое значение.

Структура

Struct представляет структурированное значение данных, состоящее из полей, которые сопоставляются с динамически типизированными значениями. В некоторых языках Struct может поддерживаться собственным представлением. Например, в языках сценариев, таких как JS, структура представляется как объект. Детали этого представления описаны вместе с протоподдержкой языка.

Представление JSON для Struct — это объект JSON.

Имя поля Тип Описание
fields map<string, Value > Карта динамически типизированных значений.

Синтаксис

Синтаксис, в котором определяется элемент буфера протокола.

Значение перечисления Описание
SYNTAX_PROTO2 Синтаксис proto2 .
SYNTAX_PROTO3 Синтаксис proto3 .

Отметка времени

Отметка времени представляет момент времени, не зависящий от часового пояса или календаря, представленный в виде секунд и долей секунд с разрешением в наносекундах во времени эпохи UTC. Он кодируется с использованием пролептического григорианского календаря, который расширяет григорианский календарь до первого года. Он кодируется, предполагая, что все минуты имеют длину 60 секунд, т. е. дополнительные секунды «размазаны», так что для интерпретации не требуется таблица дополнительных секунд. Диапазон от 0001-01-01T00:00:00Z до 9999-12-31T23:59:59.999999999Z. Ограничившись этим диапазоном, мы гарантируем, что сможем преобразовывать строки даты RFC 3339 и обратно. См. https://www.ietf.org/rfc/rfc3339.txt .

Пример 1: Вычисление метки времени из POSIX time() .

Timestamp timestamp;
timestamp.set_seconds(time(NULL));
timestamp.set_nanos(0);

Пример 2: Вычисление метки времени из POSIX gettimeofday() .

struct timeval tv;
gettimeofday(&tv, NULL);

Timestamp timestamp;
timestamp.set_seconds(tv.tv_sec);
timestamp.set_nanos(tv.tv_usec * 1000);

Пример 3: Вычисление метки времени из Win32 GetSystemTimeAsFileTime() .

FILETIME ft;
GetSystemTimeAsFileTime(&ft);
UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime;

// A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z
// is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z.
Timestamp timestamp;
timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL));
timestamp.set_nanos((INT32) ((ticks % 10000000) * 100));

Пример 4. Вычисление метки времени из Java System.currentTimeMillis() .

long millis = System.currentTimeMillis();

Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000)
    .setNanos((int) ((millis % 1000) * 1000000)).build();

Пример 5: Вычисление метки времени из текущего времени в Python.

now = time.time()
seconds = int(now)
nanos = int((now - seconds) * 10**9)
timestamp = Timestamp(seconds=seconds, nanos=nanos)
Имя поля Тип Описание
seconds int64 Представляет секунды времени UTC с эпохи Unix 1970-01-01T00:00:00Z. Должен быть от 0001-01-01T00:00:00Z до 9999-12-31T23:59:59Z включительно.
nanos int32 Неотрицательные доли секунды при наносекундном разрешении. Отрицательные значения секунд с дробями должны по-прежнему иметь неотрицательные значения нано, которые отсчитываются вперед во времени. Должно быть от 0 до 999 999 999 включительно.

Тип

Тип сообщения буфера протокола.

Имя поля Тип Описание
name string Полное имя сообщения.
fields Field Список полей.
oneofs string Список типов, встречающихся в oneof определений этого типа.
options Option Параметры буфера протокола.
source_context SourceContext Исходный контекст.
syntax Syntax Исходный синтаксис.

UInt32Value

Сообщение-оболочка для uint32 .

Представление JSON для UInt32Value — это номер JSON.

Имя поля Тип Описание
value uint32 Значение uint32.

UInt64Value

Сообщение-оболочка для uint64 .

Представление JSON для UInt64Value — это строка JSON.

Имя поля Тип Описание
value uint64 Значение uint64.

Ценить

Value представляет собой динамически типизированное значение, которое может быть нулевым, числом, строкой, логическим значением, значением рекурсивной структуры или списком значений. Ожидается, что производитель значения установит один из этих вариантов, отсутствие любого варианта указывает на ошибку.

Представление JSON для Value — это значение JSON.

Имя поля Тип Описание
Поле Union, только одно из следующего:
null_value NullValue Представляет нулевое значение.
number_value double Представляет двойное значение. Обратите внимание, что попытка сериализовать NaN или Infinity приводит к ошибке. (Мы не можем сериализовать их как строковые значения «NaN» или «Бесконечность», как мы делаем для обычных полей, потому что они будут анализироваться как строковое_значение, а не числовое_значение).
string_value string Представляет строковое значение.
bool_value bool Представляет логическое значение.
struct_value Struct Представляет структурированное значение.
list_value ListValue Представляет повторяющееся Value .