OBSERVAÇÃO:este site foi descontinuado. O site será desativado após 31 de janeiro de 2023, e o tráfego será redirecionado para o novo site em https://protobuf.dev. Enquanto isso, as atualizações serão feitas apenas para protobuf.dev.

Package google.protobuf

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Índice

Qualquer

Any contém uma mensagem serializada arbitrária com um URL que descreve o tipo de mensagem serializada.

JSON

A representação JSON de um valor Any usa a representação regular da mensagem incorporada desserializada, com um campo adicional @type que contém o URL de tipo. Exemplo:

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

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

Se o tipo de mensagem incorporado for conhecido e tiver uma representação JSON personalizada, ela será incorporada com um campo value que contém o JSON personalizado, além do campo @type. Exemplo (para a mensagem google.protobuf.Duration):

{
  "@type": "type.googleapis.com/google.protobuf.Duration",
  "value": "1.212s"
}
Nome do campo Tipo Descrição
type_url string

Um nome de URL/recurso com conteúdo que descreve o tipo de mensagem serializada.

Para URLs que usam o esquema http, https ou nenhum esquema, as seguintes restrições e interpretações são aplicáveis:

  • Se nenhum esquema for fornecido, https será usado.
  • O último segmento do caminho do URL precisa representar o nome totalmente qualificado do tipo (como em path/google.protobuf.Duration).
  • Um HTTP GET no URL precisa gerar um valor google.protobuf.Type em formato binário ou produzir um erro.
  • Os aplicativos podem armazenar em cache os resultados da pesquisa baseados no URL ou fazer a pré-compilação em um binário para evitar pesquisas. Portanto, a compatibilidade binária precisa ser preservada após mudanças nos tipos. Use nomes de tipo com controle de versão para gerenciar alterações interruptivas.

Esquemas que não sejam http, https (ou o esquema vazio) podem ser usados com semântica específica de implementação.

value bytes Precisam ser dados serializados válidos do tipo especificado acima.

Api

A API é um descritor leve para um serviço de buffer de protocolo.

Nome do campo Tipo Descrição
name string O nome totalmente qualificado desta API, incluindo o nome do pacote seguido pelo nome simples da API.
methods Method Os métodos dessa API, em ordem não especificada.
options Option Todos os metadados anexados à API.
version string

Uma string de versão para esta API. Se especificado, precisa ter o formato major-version.minor-version, como em 1.10. Se a versão secundária for omitida, o valor padrão é zero. Se o campo da versão inteira estiver em branco, a versão principal é derivada do nome do pacote, conforme descrito abaixo. Se o campo não estiver em branco, a versão no nome do pacote será verificada para ser consistente com o que é fornecido aqui.

O esquema de versão usa o controle de versão semântico em que o número da versão principal indica uma alteração importante e a versão secundária indica uma alteração adicional e não importante. Ambos os números de versão são sinais para os usuários sobre que esperar de diferentes versões e precisam ser cuidadosamente escolhidos de acordo com o plano do produto.

A versão principal também é refletida no nome do pacote da API, que precisa terminar em v<major-version>, como em google.feature.v1. Nas versões principais 0 e 1, o sufixo pode ser omitido. As versões principais zero só podem ser usadas para APIs experimentais, que não têm disponibilidade geral.

source_context SourceContext Contexto de origem para o serviço de buffer de protocolo representado por esta mensagem.
mixins Mixin APIs incluídas. Consulte os Mixin.
syntax Syntax A sintaxe de origem do serviço.

BoolValue

Mensagem de wrapper para bool.

A representação JSON para BoolValue é JSON true e false.

Nome do campo Tipo Descrição
value bool O valor booleano.

BytesValue

Mensagem de wrapper para bytes.

A representação JSON para BytesValue é uma string JSON.

Nome do campo Tipo Descrição
value bytes Valor de bytes.

DoubleValue

Mensagem de wrapper para double.

A representação JSON de DoubleValue é um número JSON.

Nome do campo Tipo Descrição
value double O valor duplo.

Duração

Uma duração representa um período assinado de duração fixa, representada como uma contagem de segundos e frações de segundos de resolução de nanossegundos. Ela é independente de agendas e conceitos, como "dia" ou "mês". Ela está relacionada ao carimbo de data/hora porque a diferença entre dois valores é uma duração, e ela pode ser adicionada ou subtraída de um carimbo de data/hora. O intervalo é aproximadamente +-10.000 anos.

Exemplo 1: duração do cálculo de dois carimbos de data/hora em pseudocódigo.

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;
}

Exemplo 2: calcular o carimbo de data/hora usando o carimbo de data/hora + a duração em um pseudocódigo.

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;
}

A representação JSON para Duration é um String que termina em s para indicar segundos e é precedida pelo número de segundos, com nanossegundos expressos como segundos fracionários.

Nome do campo Tipo Descrição
seconds int64 Segundos assinados do intervalo de tempo. Precisa ser de -315.576.000.000 a +315.576.000.000.
nanos int32 Frações assinadas de um segundo com resolução de nanossegundos no período. Durações inferiores a um segundo são representadas por um campo seconds de 0 e um campo nanos positivo ou negativo. Para durações de um segundo ou mais, um valor diferente de zero para o campo nanos precisa ser do mesmo sinal que o campo seconds. Precisa ser de -999.999.999 a +999.999.999.

Vazio

Uma mensagem vazia genérica que você pode reutilizar para evitar a definição de mensagens vazias duplicadas nas APIs. Um exemplo comum é usá-la como solicitação ou tipo de resposta de um método de API. Por exemplo:

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

A representação JSON para Empty é o objeto JSON vazio {}.

Tipo enumerado

Definição do tipo de enumeração.

Nome do campo Tipo Descrição
name string Nome do tipo de enumeração.
enumvalue EnumValue Definições de valor de enumeração.
options Option Opções de buffer de protocolo.
source_context SourceContext O contexto de origem.
syntax Syntax A sintaxe de origem.

EnumValue

Definição do valor do enumeração.

Nome do campo Tipo Descrição
name string Nome do valor de enumeração.
number int32 Número do valor da enumeração.
options Option Opções de buffer de protocolo.

Campo

Um único campo de um tipo de mensagem.

Nome do campo Tipo Descrição
kind Kind O tipo de campo.
cardinality Cardinality A cardinalidade do campo.
number int32 O número do campo.
name string Nome do campo.
type_url string O URL do tipo de campo, sem o esquema, para tipos de mensagem ou enumeração. Exemplo: "type.googleapis.com/google.protobuf.Timestamp".
oneof_index int32 O índice do tipo de campo em Type.oneofs, para tipos de enumeração ou mensagem. O primeiro tipo tem índice 1; zero significa que o tipo não está na lista.
packed bool Define se é necessário usar uma representação eletrônica alternativa.
options Option As opções de buffer de protocolo.
json_name string O nome JSON do campo.
default_value string Valor da string do valor padrão deste campo. Somente a sintaxe do Proto2.

Cardinalidade

Indica se um campo é opcional, obrigatório ou repetido.

Valor de tipo enumerado Descrição
CARDINALITY_UNKNOWN Para campos com cardinalidade desconhecida.
CARDINALITY_OPTIONAL Para campos opcionais.
CARDINALITY_REQUIRED Para campos obrigatórios. Somente a sintaxe do Proto2.
CARDINALITY_REPEATED Para campos repetidos.

Tipo

Tipos de campo básicos.

Valor de tipo enumerado Descrição
TYPE_UNKNOWN Tipo de campo desconhecido.
TYPE_DOUBLE Tipo de campo duplo.
TYPE_FLOAT Tipo flutuante do tipo de campo.
TYPE_INT64 Tipo de campo int64.
TYPE_UINT64 Tipo de campo uint64.
TYPE_INT32 Tipo de campo int32.
TYPE_FIXED64 Tipo de campo fixed64.
TYPE_FIXED32 Tipo de campo fixed32.
TYPE_BOOL Tipo de campo booleano.
TYPE_STRING String do tipo de campo.
TYPE_GROUP Grupo de tipos de campos. Somente a sintaxe Proto2 foi descontinuada.
TYPE_MESSAGE Mensagem do tipo de campo.
TYPE_BYTES Bytes de tipo de campo.
TYPE_UINT32 Tipo de campo uint32.
TYPE_ENUM Tipo de enumeração enum.
TYPE_SFIXED32 Tipo de campo sFixed32.
TYPE_SFIXED64 Tipo de campo sFixed64.
TYPE_SINT32 Tipo de campo sint32.
TYPE_SINT64 Tipo de campo sint64.

FieldMask

FieldMask representa um conjunto de caminhos de campo simbólicos, por exemplo:

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

Aqui, f representa um campo em uma mensagem raiz, campos a e b na mensagem encontrada em f e d um campo encontrado na mensagem em f.b.

As máscaras de campo são usadas para especificar um subconjunto de campos que serão retornados por uma operação get (uma projeção) ou modificados por uma operação de atualização. As máscaras de campo também têm uma codificação JSON personalizada (veja abaixo).

Máscaras de campo em projeções

Quando uma FieldMask especifica uma projeção, a API filtra a mensagem (ou submensagem) para conter apenas os campos especificados na máscara. Por exemplo, considere esta mensagem de resposta de "pré-mascaramento":

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

Depois de aplicar a máscara no exemplo anterior, a resposta da API não conterá valores específicos para os campos x, y ou z (o valor será definido como o padrão e omitido na saída do texto de proto):

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

Não é permitido um campo repetido, exceto na última posição de uma máscara de campo.

Se um objeto FieldMask não estiver presente em uma operação get, a operação será aplicada a todos os campos (como se um FieldMask de todos os campos tivesse sido especificado).

Uma máscara de campo não se aplica necessariamente à mensagem de resposta de nível superior. No caso de uma operação REST get, a máscara de campo se aplica diretamente à resposta, mas no caso de uma operação de lista REST, a máscara se aplica a cada mensagem individual na lista de recursos retornada. No caso de um método REST personalizado, outras definições podem ser usadas. Onde a máscara se aplica será documentada claramente com a respectiva declaração na API. De qualquer forma, o efeito nos recursos retornados é um comportamento obrigatório para as APIs.

Máscaras de campo em operações de atualização

Uma máscara de campo nas operações de atualização especifica quais campos do recurso de destino serão atualizados. A API é necessária apenas para alterar os valores dos campos conforme especificado na máscara e deixar os demais intactos. Se um recurso for transmitido para descrever os valores atualizados, a API ignorará os valores de todos os campos não cobertos pela máscara.

Para redefinir o valor de um campo para o padrão, o campo precisa estar na máscara e ser definido como o valor padrão no recurso fornecido. Portanto, para redefinir todos os campos de um recurso, forneça uma instância padrão do recurso e defina todos os campos na máscara ou não forneça uma máscara conforme descrito abaixo.

Se uma máscara de campo não estiver presente na atualização, a operação será aplicada a todos os campos (como se uma máscara de campo de todos os campos tenha sido especificada). Na presença de evolução do esquema, isso pode significar que os campos que o cliente não conhece e que, portanto, não foram preenchidos na solicitação serão redefinidos para o padrão. Se esse for um comportamento indesejado, um serviço específico pode exigir que um cliente sempre especifique uma máscara de campo, produzindo um erro.

Assim como com as operações get, a localização do recurso que descreve os valores atualizados na mensagem de solicitação depende do tipo de operação. De qualquer forma, o efeito da máscara de campo precisa ser honrado pela API.

Considerações sobre o REST HTTP

O tipo HTTP de uma operação de atualização que usa uma máscara de campo precisa ser definido como PATCH em vez de PUT para satisfazer a semântica HTTP (o PUT só deve ser usado para atualizações completas).

Codificação JSON de máscaras de campo

No JSON, uma máscara de campo é codificada como uma única string em que os caminhos são separados por uma vírgula. O nome dos campos em cada caminho é convertido de/para convenções de nomenclatura de concatenação.

Por exemplo, considere as seguintes declarações de mensagem:

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

No proto, uma máscara de campo para Profile pode ter esta aparência:

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

No JSON, a mesma máscara é representada abaixo:

{
  mask: "user.displayName,photo"
}
Nome do campo Tipo Descrição
paths string O conjunto de caminhos da máscara de campo.

FloatValue

Mensagem de wrapper para float.

A representação JSON de FloatValue é um número JSON.

Nome do campo Tipo Descrição
value float O valor flutuante.

Int32Value

Mensagem de wrapper para int32.

A representação JSON de Int32Value é um número JSON.

Nome do campo Tipo Descrição
value int32 O valor int32.

Int64Value

Mensagem de wrapper para int64.

A representação JSON para Int64Value é uma string JSON.

Nome do campo Tipo Descrição
value int64 O valor int64.

ListValue

ListValue é um wrapper em torno de um campo de valores repetido.

A representação JSON para ListValue é a matriz JSON.

Nome do campo Tipo Descrição
values Value Campo repetido de valores tipados dinamicamente.

Método

O método representa um método de API.

Nome do campo Tipo Descrição
name string O nome simples deste método.
request_type_url string Um URL do tipo de mensagem de entrada.
request_streaming bool Se for "True", a solicitação será transmitida.
response_type_url string O URL do tipo de mensagem de saída.
response_streaming bool Se for "True", a resposta será transmitida.
options Option Quaisquer metadados anexados ao método.
syntax Syntax A sintaxe de origem desse método.

Mixin

Declara uma API a ser incluída nesta API. A API incluída precisa declarar novamente todos os métodos da API incluída, mas a documentação e as opções são herdadas da seguinte maneira:

  • Se, após o comentário e a remoção de espaços em branco, a string de documentação do método redeclarado estiver em branco, ela será herdada do método original.

  • Cada anotação pertencente à configuração do serviço (http, visibilidade) que não está configurada no método redeclarado será herdada.

  • Se uma anotação http for herdada, o padrão de caminho será modificado da seguinte maneira. Qualquer prefixo de versão será substituído pela versão da API incluída mais o caminho root, se especificado.

Exemplo de mixin simples:

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=**}";
  }
}

Exemplo de configuração de mixin:

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

A construção de mixin implica que todos os métodos em AccessControl também são declarados com o mesmo nome e tipo de solicitação/resposta em Storage. Um gerador de documentação ou um processador de anotações vai ver o método Storage.GetAcl efetivo depois de herdar a documentação e as anotações da seguinte maneira:

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

Observe como a versão no padrão de caminho mudou de v1 para v2.

Se o campo root no mixin for especificado, ele precisa ser um caminho relativo em que os caminhos HTTP herdados são colocados. Exemplo:

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

Isso implica a seguinte anotação HTTP herdada:

service Storage {
  // Get the underlying ACL object.
  rpc GetAcl(GetAclRequest) returns (Acl) {
    option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";
  }
  ...
}
Nome do campo Tipo Descrição
name string O nome totalmente qualificado da API incluído.
root string Se não estiver em branco, especifica um caminho em que os caminhos HTTP herdados têm acesso root.

NullValue

NullValue é uma enumeração singleton para representar o valor nulo para a união de tipo Value.

A representação JSON para NullValue é JSON null.

Valor de tipo enumerado Descrição
NULL_VALUE Valor nulo.

Opção

Uma opção de buffer de protocolo, que pode ser anexada a uma mensagem, campo, enumeração etc.

Nome do campo Tipo Descrição
name string O nome da opção. Por exemplo, "java_package".
value Any Valor da opção. Por exemplo, "com.google.protobuf".

SourceContext

SourceContext representa informações sobre a origem de um elemento protobuf, como o arquivo em que ele é definido.

Nome do campo Tipo Descrição
file_name string O nome qualificado do caminho do arquivo .proto que continha o elemento protobuf associado. Por exemplo, "google/protobuf/source.proto".

StringValue

Mensagem de wrapper para string.

A representação JSON para StringValue é uma string JSON.

Nome do campo Tipo Descrição
value string O valor da string.

Struct

Struct representa um valor de dados estruturados, que consiste em campos mapeados para valores tipados dinamicamente. Em alguns idiomas, Struct pode ser compatível com uma representação nativa. Por exemplo, em linguagens de script como JS, uma struct é representada como um objeto. Os detalhes dessa representação são descritos com o suporte do protocolo para a linguagem.

A representação JSON para Struct é o objeto JSON.

Nome do campo Tipo Descrição
fields map<string, Value> Mapa de valores tipados dinamicamente.

Sintaxe

A sintaxe em que um elemento de buffer de protocolo é definido.

Valor de tipo enumerado Descrição
SYNTAX_PROTO2 Sintaxe proto2.
SYNTAX_PROTO3 Sintaxe proto3.

Carimbo de data/hora

Um carimbo de data/hora representa um ponto no tempo independente de fusos horários ou calendários, representado como segundos e frações de segundos na resolução de nanossegundos no horário mundial UTC. Ele é codificado usando o calendário gregoriano proléptico, que estende o calendário gregoriano de volta para o primeiro ano. Essa codificação supõe que todos os minutos tenham 60 segundos de duração, ou seja, segundos bissextos são "indistinguíveis", assim não é preciso ter uma tabela de segundos adicionais para interpretação. O intervalo varia de 0001-01-01T00:00:00Z a 9999-12-31T23:59:59.999999999Z. Ao restringir esse intervalo, garantimos que é possível fazer a conversão de/para strings de data RFC 3339. Consulte https://www.ietf.org/rfc/rfc3339.txt.

Exemplo 1: Calcular carimbo de data/hora de POSIX time().

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

Exemplo 2: Calcular carimbo de data/hora de POSIX gettimeofday().

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

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

Exemplo 3: Calcular carimbo de data/hora de 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));

Exemplo 4: Calcular carimbo de data/hora de Java System.currentTimeMillis().

long millis = System.currentTimeMillis();

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

Exemplo 5: Calcular carimbo de data/hora a partir do horário atual no Python.

now = time.time()
seconds = int(now)
nanos = int((now - seconds) * 10**9)
timestamp = Timestamp(seconds=seconds, nanos=nanos)
Nome do campo Tipo Descrição
seconds int64 Representa os segundos do horário UTC desde a época Unix 1970-01-01T00:00:00Z. Precisa ser entre 0001-01-01T00:00:00Z e 9999-12-31T23:59:59Z.
nanos int32 Frações não negativas de um segundo com resolução de nanossegundos. Os valores de segundos negativos com frações ainda precisam ter valores em nanossegundos não negativos que representam períodos posteriores. O valor precisa ser de 0 a 999.999.999 (inclusive).

Tipo

Um tipo de mensagem do buffer de protocolo.

Nome do campo Tipo Descrição
name string O nome da mensagem totalmente qualificado.
fields Field Lista de campos.
oneofs string A lista de tipos que aparecem nas definições de oneof nesse tipo.
options Option As opções de buffer de protocolo.
source_context SourceContext O contexto de origem.
syntax Syntax A sintaxe de origem.

UInt32Value

Mensagem de wrapper para uint32.

A representação JSON de UInt32Value é um número JSON.

Nome do campo Tipo Descrição
value uint32 O valor uint32.

UInt64Value

Mensagem de wrapper para uint64.

A representação JSON para UInt64Value é uma string JSON.

Nome do campo Tipo Descrição
value uint64 O valor uint64.

Valor

Value representa um valor tipado dinamicamente que pode ser nulo, um número, uma string, um booleano, um valor de estrutura recursivo ou uma lista de valores. Um produtor de valor precisa definir uma dessas variantes. A ausência de qualquer variante indica um erro.

A representação JSON de Value é um valor JSON.

Nome do campo Tipo Descrição
Campo de união, apenas uma das seguintes opções:
null_value NullValue Representa um valor nulo.
number_value double Representa um valor duplo. Observe que tentar serializar NaN ou Infinity resulta em erro. Não é possível serializar esses valores como strings "NaN" ou "Infinity", como fazemos em campos regulares, porque eles poderiam ser analisados como string_value, não number_value.
string_value string Representa um valor de string.
bool_value bool Representa um valor booleano.
struct_value Struct Representa um valor estruturado.
list_value ListValue Representa um Value repetido.