Индекс
-
Any
(сообщение) -
Api
(сообщение) -
BoolValue
(сообщение) -
BytesValue
(сообщение) -
DoubleValue
(сообщение) -
Duration
(сообщение) -
Empty
(сообщение) -
Enum
(сообщение) -
EnumValue
(сообщение) -
Field
(сообщение) -
Field.Cardinality
(перечисление) -
Field.Kind
(перечисление) -
FieldMask
(сообщение) -
FloatValue
(сообщение) -
Int32Value
(сообщение) -
Int64Value
(сообщение) -
ListValue
(сообщение) -
Method
(сообщение) -
Mixin
(сообщение) -
NullValue
(перечисление) -
Option
(сообщение) -
SourceContext
(сообщение) -
StringValue
(сообщение) -
Struct
(сообщение) -
Syntax
(перечисление) -
Timestamp
(сообщение) -
Type
(сообщение) -
UInt32Value
(сообщение) -
UInt64Value
(сообщение) -
Value
(сообщение)
Любой
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-адресов, которые используют схему
Схемы, отличные от |
value | bytes | Должны быть действительными сериализованными данными указанного выше типа. |
Апи
Api — это упрощенный дескриптор службы буфера протокола.
Имя поля | Тип | Описание |
---|---|---|
name | string | Полное имя этого API, включая имя пакета, за которым следует простое имя API. |
methods |
| Методы этого API в неопределенном порядке. |
options |
| Любые метаданные, прикрепленные к API. |
version | string | Строка версии для этого API. Если указано, должно иметь вид Схема управления версиями использует семантическое управление версиями, где основной номер версии указывает на критическое изменение, а второстепенная версия — на добавочное некритическое изменение. Оба номера версии сигнализируют пользователям, чего ожидать от разных версий, и их следует тщательно выбирать на основе плана продукта. Основная версия также отражается в имени пакета API, которое должно заканчиваться на |
source_context |
| Исходный контекст для службы буфера протокола, представленной этим сообщением. |
mixins |
| Включенные API. См. Mixin . |
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 |
| Определения значений перечисления. |
options |
| Параметры буфера протокола. |
source_context |
| Исходный контекст. |
syntax |
| Исходный синтаксис. |
EnumValue
Определение значения перечисления.
Имя поля | Тип | Описание |
---|---|---|
name | string | Имя значения перечисления. |
number | int32 | Номер значения перечисления. |
options |
| Параметры буфера протокола. |
Поле
Одно поле типа сообщения.
Имя поля | Тип | Описание |
---|---|---|
kind |
| Тип поля. |
cardinality |
| Мощность поля. |
number | int32 | Номер поля. |
name | string | Имя поля. |
type_url | string | URL-адрес типа поля без схемы для типов сообщения или перечисления. Пример: "type.googleapis.com/google.protobuf.Timestamp" . |
oneof_index | int32 | Индекс типа поля в Type.oneofs для типов сообщения или перечисления. Первый тип имеет индекс 1; ноль означает, что тип отсутствует в списке. |
packed | bool | Использовать ли альтернативное представление упакованной проволоки. |
options |
| Параметры буфера протокола. |
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 |
| Повторяющееся поле динамически типизированных значений. |
Метод
Метод представляет собой метод API.
Имя поля | Тип | Описание |
---|---|---|
name | string | Простое название этого метода. |
request_type_url | string | URL-адрес типа входного сообщения. |
request_streaming | bool | Если true, запрос передается в потоковом режиме. |
response_type_url | string | URL типа выходного сообщения. |
response_streaming | bool | Если это правда, ответ передается в потоковом режиме. |
options |
| Любые метаданные, прикрепленные к методу. |
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 |
| Стоимость опции. Например, "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, | Карта динамически типизированных значений. |
Синтаксис
Синтаксис, в котором определяется элемент буфера протокола.
Значение перечисления | Описание |
---|---|
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 |
| Список полей. |
oneofs | string | Список типов, встречающихся в oneof определений этого типа. |
options |
| Параметры буфера протокола. |
source_context |
| Исходный контекст. |
syntax |
| Исходный синтаксис. |
UInt32Value
Сообщение-оболочка для uint32
.
Представление JSON для UInt32Value
— это номер JSON.
Имя поля | Тип | Описание |
---|---|---|
value | uint32 | Значение uint32. |
UInt64Value
Сообщение-оболочка для uint64
.
Представление JSON для UInt64Value
— это строка JSON.
Имя поля | Тип | Описание |
---|---|---|
value | uint64 | Значение uint64. |
Ценить
Value
представляет собой динамически типизированное значение, которое может быть нулевым, числом, строкой, логическим значением, значением рекурсивной структуры или списком значений. Ожидается, что производитель значения установит один из этих вариантов, отсутствие любого варианта указывает на ошибку.
Представление JSON для Value
— это значение JSON.
Имя поля | Тип | Описание |
---|---|---|
Поле Union, только одно из следующего: | ||
null_value |
| Представляет нулевое значение. |
number_value | double | Представляет двойное значение. Обратите внимание, что попытка сериализовать NaN или Infinity приводит к ошибке. (Мы не можем сериализовать их как строковые значения «NaN» или «Бесконечность», как мы делаем для обычных полей, потому что они будут анализироваться как строковое_значение, а не числовое_значение). |
string_value | string | Представляет строковое значение. |
bool_value | bool | Представляет логическое значение. |
struct_value |
| Представляет структурированное значение. |
list_value |
| Представляет повторяющееся Value . |