REMARQUE:Ce site est obsolète. Le site sera désactivé après le 31 janvier 2023 et le trafic redirigera vers le nouveau site à l'adresse https://protobuf.dev. En attendant, les mises à jour ne seront effectuées que sur protobuf.dev.

Package google.protobuf

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Index

Tout

Any contient un message sérialisé arbitraire ainsi qu'une URL décrivant le type du message sérialisé.

JSON

La représentation JSON d'une valeur Any utilise la représentation standard du message intégré désérialisé, avec un champ supplémentaire @type contenant le type d'URL. Exemple :

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

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

Si le type de message intégré est connu et possède une représentation JSON personnalisée, cette représentation sera intégrée en ajoutant un champ value qui contient le fichier JSON personnalisé en plus du champ @type. Exemple (pour le message google.protobuf.Duration):

{
  "@type": "type.googleapis.com/google.protobuf.Duration",
  "value": "1.212s"
}
Nom du champ Type Description
type_url string

Nom de l'URL ou de la ressource dont le contenu décrit le type du message sérialisé.

Pour les URL qui utilisent le schéma http, https ou aucun schéma, les restrictions et interprétations suivantes s'appliquent:

  • Si aucun schéma n'est fourni, https est utilisé.
  • Le dernier segment du chemin de l'URL doit correspondre au nom complet du type (comme dans path/google.protobuf.Duration).
  • Une requête HTTP GET sur l'URL doit renvoyer une valeur google.protobuf.Type au format binaire ou générer une erreur.
  • Les applications sont autorisées à mettre en cache les résultats de recherche basés sur l'URL ou à les précompiler dans un fichier binaire pour éviter toute recherche. Par conséquent, la compatibilité binaire doit être conservée en cas de modification des types. (Utilisez des noms de type avec versions gérées pour gérer les modifications destructives.)

Vous pouvez utiliser des schémas autres que http, https (ou le schéma vide) avec une sémantique d'implémentation spécifique.

value bytes Il doit s'agir de données sérialisées valides du type spécifié ci-dessus.

Api

L'API est un descripteur léger pour un service de tampon de protocole.

Nom du champ Type Description
name string Nom complet de cette API, y compris le nom du package suivi du nom simple de l'API.
methods Method Méthodes de cette API, dans un ordre non spécifié.
options Option Toutes les métadonnées associées à l'API.
version string

Chaîne de version pour cette API. Si spécifié, il doit être au format major-version.minor-version, comme dans 1.10. Si la version mineure est omise, la valeur par défaut est zéro. Si le champ de la version complète est vide, la version majeure est dérivée du nom du package, comme indiqué ci-dessous. Si le champ n'est pas vide, la version du nom de package sera validée pour être cohérente avec ce qui est fourni ici.

Le schéma de gestion des versions utilise la gestion sémantique des versions : le numéro de version majeure indique une modification destructive et la version mineure un changement complémentaire non destructif. Les deux numéros de version indiquent aux utilisateurs ce qu'ils peuvent attendre des différentes versions. Ils doivent donc être choisis avec soin en fonction du forfait.

La version majeure est également reflétée dans le nom de package de l'API, qui doit se terminer par v<major-version>, comme dans google.feature.v1. Pour les versions majeures 0 et 1, le suffixe peut être omis. Aucune version majeure ne doit être utilisée pour les API expérimentales et non GA.

source_context SourceContext Contexte source pour le service de tampon de protocole représenté par ce message.
mixins Mixin API incluses. Consultez les Mixin.
syntax Syntax Syntaxe source du service.

BoolValue

Message wrapper pour bool.

La représentation JSON de BoolValue est JSON true et false.

Nom du champ Type Description
value bool Valeur booléenne.

BytesValue

Message wrapper pour bytes.

La représentation JSON de BytesValue est une chaîne JSON.

Nom du champ Type Description
value bytes Valeur en octets.

DoubleValue

Message wrapper pour double.

La représentation JSON de DoubleValue est un nombre JSON.

Nom du champ Type Description
value double Valeur double.

Durée

Une durée représente une période de durée signée signée, représentée par un nombre de secondes et des fractions de secondes à une résolution de l'ordre de la nanoseconde. Il est indépendant de tout calendrier et concept tels que "jour" ou "mois". Elle est liée à l'horodatage dans la mesure où la différence entre deux valeurs d'horodatage est une durée et peut être ajoutée ou soustraite d'un horodatage. La plage est d'environ +-10 000 ans.

Exemple 1: Calculer la durée à partir de deux horodatages en pseudo-code

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

Exemple 2: Calculer l'horodatage à partir de l'horodatage et de la durée en pseudo-code

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

La représentation JSON de Duration est une String qui se termine par s pour indiquer les secondes. Elle est précédée du nombre de secondes, la nanoseconde étant exprimée en fractions de secondes.

Nom du champ Type Description
seconds int64 Signé de quelques secondes de la période. La valeur doit être comprise entre -315 576 000 000 et +315 576 000 000 (inclus).
nanos int32 Fraction de secondes d'une durée de résolution de l'ordre de quelques nanosecondes. Les durées inférieures à une seconde sont représentées par un champ de 0 seconds et un champ d'nanos positif ou négatif. Pour les durées d'une seconde ou plus, une valeur non nulle pour le champ nanos doit avoir le même signe que le champ seconds. La valeur doit être comprise entre -999 999 999 et +999 999 999 inclus.

Vide

Message générique vide que vous pouvez réutiliser pour éviter de définir des messages vides en double dans vos API. Un exemple typique consiste à l'utiliser comme requête ou type de réponse d'une méthode API. Exemple :

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

La représentation JSON de Empty est un objet JSON vide {}.

Enum

Définition du type d'énumération.

Nom du champ Type Description
name string Nom du type d'énumération.
enumvalue EnumValue Définitions de valeurs d'énumération.
options Option Options de tampon de protocole.
source_context SourceContext Contexte source
syntax Syntax Syntaxe source.

EnumValue

Définition de la valeur d'énumération.

Nom du champ Type Description
name string Nom de la valeur d'énumération.
number int32 Valeur d'énumération.
options Option Options de tampon de protocole.

Champ

Champ unique d'un type de message.

Nom du champ Type Description
kind Kind Type de champ.
cardinality Cardinality Champ cardinalité du champ.
number int32 Numéro du champ.
name string Nom du champ.
type_url string URL du type de champ, sans le schéma, pour les types de messages ou d'énumération. Exemple : "type.googleapis.com/google.protobuf.Timestamp"
oneof_index int32 Index du type de champ dans Type.oneofs, pour les messages ou les énumérations. Le premier type a l'index 1 ; zéro signifie que le type ne figure pas dans la liste.
packed bool Indique s'il faut utiliser une autre représentation sous forme de fil emballé.
options Option Options de tampon de protocole.
json_name string Nom JSON du champ.
default_value string Valeur de chaîne de la valeur par défaut de ce champ. Syntaxe Proto2 uniquement.

Cardinalité

Indique si un champ est facultatif, obligatoire ou répété.

Valeur d'énumération Description
CARDINALITY_UNKNOWN Pour les champs à cardinalité inconnue.
CARDINALITY_OPTIONAL Pour les champs facultatifs.
CARDINALITY_REQUIRED Pour les champs obligatoires. Syntaxe Proto2 uniquement.
CARDINALITY_REPEATED Pour les champs répétés.

Type

Types de champs de base.

Valeur d'énumération Description
TYPE_UNKNOWN Type de champ inconnu.
TYPE_DOUBLE Type de champ double.
TYPE_FLOAT Type de champ flottant.
TYPE_INT64 Type de champ int64.
TYPE_UINT64 Type de champ uint64.
TYPE_INT32 Type de champ int32.
TYPE_FIXED64 Type de champ fixe64.
TYPE_FIXED32 Type de champ fixe32.
TYPE_BOOL Type de champ bool.
TYPE_STRING Chaîne de type de champ.
TYPE_GROUP Type de champ. Syntaxe Proto2 uniquement et obsolète.
TYPE_MESSAGE Message de type de champ.
TYPE_BYTES Octets du type de champ.
TYPE_UINT32 Type de champ uint32.
TYPE_ENUM Énumération de type de champ.
TYPE_SFIXED32 Type de champ sfixed32.
TYPE_SFIXED64 Type de champ sfixed64.
TYPE_SINT32 Type de champ sint32.
TYPE_SINT64 Type de champ sint64.

FieldMask

FieldMask représente un ensemble de chemins d'accès à des champs symboliques, par exemple:

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

Ici, f représente un champ dans un message racine, a et b dans le message trouvé dans f, et d un champ dans le message dans f.b.

Les masques de champ permettent de spécifier un sous-ensemble de champs devant être renvoyés par une opération "get" (une projection) ou modifiés par une opération de mise à jour. Les masques de champ possèdent également un encodage JSON personnalisé (voir ci-dessous).

Masques de champ dans les projections

Lorsqu'un FieldMask spécifie une projection, l'API filtre le message (ou sous-message) de réponse pour ne contenir que les champs spécifiés dans le masque. Prenons par exemple le message de réponse suivant : "pré-masquage" :

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

Après avoir appliqué le masque dans l'exemple précédent, la réponse de l'API ne contient pas de valeurs spécifiques pour les champs x, y ou z (leur valeur sera définie sur la valeur par défaut et omise dans la sortie du texte proto):

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

Un champ répété n'est autorisé qu'à la dernière position d'un masque de champ.

Si un objet FieldMask n'est pas présent dans une opération get, l'opération s'applique à tous les champs (comme si un champ FieldMask de tous les champs avait été spécifié).

Notez qu'un masque de champ ne s'applique pas nécessairement au message de réponse de niveau supérieur. Dans le cas d'une opération "get" de REST, le masque de champ s'applique directement à la réponse, mais dans le cas d'une opération de liste REST, le masque s'applique à chaque message individuel de la liste de ressources renvoyée. Dans le cas d'une méthode personnalisée REST, d'autres définitions peuvent être utilisées. L'emplacement du masque sera clairement documenté avec sa déclaration dans l'API. Dans tous les cas, l'effet sur les ressources renvoyées est obligatoire pour les API.

Masques de champ dans les opérations de mise à jour

Dans les opérations de mise à jour, un masque de champ spécifie les champs de la ressource ciblée qui seront mis à jour. L'API est requise pour ne modifier que les valeurs des champs spécifiées dans le masque et laisser les autres intactes. Si une ressource est transmise pour décrire les valeurs mises à jour, l'API ignore les valeurs de tous les champs non couverts par le masque.

Pour rétablir la valeur par défaut d'un champ, celui-ci doit se trouver dans le masque et être défini sur la valeur par défaut dans la ressource fournie. Par conséquent, pour réinitialiser tous les champs d'une ressource, fournissez une instance par défaut de la ressource et définissez tous les champs du masque, ou ne fournissez pas de masque comme décrit ci-dessous.

Si aucun masque de champ n'est présent lors de la mise à jour, l'opération s'applique à tous les champs (comme si un masque de champ avait été spécifié). Notez qu'en présence d'évolution de schéma, les champs que le client ne connaît pas et qui n'ont donc pas rempli la requête peuvent donc être réinitialisés. Si ce comportement est indésirable, un service spécifique peut exiger qu'un client spécifie toujours un masque de champ, ce qui génère une erreur.

Comme pour les opérations get, l'emplacement de la ressource qui décrit les valeurs mises à jour dans le message de requête dépend du genre d'opération. Dans tous les cas, l'effet du masque de champ doit être pris en compte par l'API.

Considérations pour HTTP REST

Le genre HTTP d'une opération de mise à jour utilisant un masque de champ doit être défini sur PATCH au lieu de PUT afin de respecter la sémantique HTTP (PUT ne doit être utilisé que pour les mises à jour complètes).

Encodage JSON des masques de champ

En JSON, un masque de champ est encodé sous la forme d'une chaîne unique où les chemins sont séparés par une virgule. Le nom des champs de chaque chemin d'accès est converti vers/depuis des conventions de nommage des chameaux.

Prenons l'exemple des déclarations de message suivantes:

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

En proto, un masque de champ pour Profile peut se présenter comme suit:

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

En JSON, le même masque est représenté comme suit:

{
  mask: "user.displayName,photo"
}
Nom du champ Type Description
paths string Ensemble de chemins d'accès de masque de champ.

FloatValue

Message wrapper pour float.

La représentation JSON de FloatValue est un nombre JSON.

Nom du champ Type Description
value float Valeur flottante.

Int32Value

Message wrapper pour int32.

La représentation JSON de Int32Value est un nombre JSON.

Nom du champ Type Description
value int32 Valeur int32.

Int64Value

Message wrapper pour int64.

La représentation JSON de Int64Value est une chaîne JSON.

Nom du champ Type Description
value int64 Valeur int64.

ListValue

ListValue est un wrapper autour d'un champ répété de valeurs.

La représentation JSON de ListValue est un tableau JSON.

Nom du champ Type Description
values Value Champ répété de valeurs saisies de manière dynamique.

Méthode

Method représente une méthode d'API.

Nom du champ Type Description
name string Nom simple de cette méthode.
request_type_url string URL du type de message saisi.
request_streaming bool Si la valeur est "true", la requête est diffusée.
response_type_url string URL du type de message de sortie.
response_streaming bool Si la valeur est "true", la réponse est diffusée.
options Option Toutes les métadonnées associées à la méthode.
syntax Syntax Syntaxe source de cette méthode.

Mixin

Déclare une API à inclure dans cette API. L'API d'inclusion doit redéclarer toutes les méthodes de l'API incluse, mais la documentation et les options sont héritées comme suit:

  • Si, après suppression des commentaires et des espaces, la chaîne de documentation de la méthode redéclarée est vide, elle est héritée de la méthode d'origine.

  • Chaque annotation appartenant à la configuration de service (http, visibilité) qui n'est pas définie dans la méthode redéclarée est héritée.

  • Si une annotation HTTP est héritée, le format de chemin est modifié comme suit. Tout préfixe de version sera remplacé par la version de l'API, y compris le chemin d'accès root si spécifié.

Exemple de mixin simple:

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

Exemple de configuration d'une combinaison:

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

La construction mixin implique que toutes les méthodes de AccessControl sont également déclarées avec le même nom et les mêmes types de requêtes/réponses dans Storage. Un générateur de documentation ou un processeur d'annotations verra la méthode Storage.GetAcl effective après avoir intégré la documentation et les annotations, comme suit:

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

Notez que la version du format de chemin est passée de v1 à v2.

Si le champ root du mixin est spécifié, il doit s'agir d'un chemin d'accès relatif sous lequel les chemins HTTP hérités sont placés. Exemple :

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

Cela implique l'annotation HTTP héritée suivante:

service Storage {
  // Get the underlying ACL object.
  rpc GetAcl(GetAclRequest) returns (Acl) {
    option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";
  }
  ...
}
Nom du champ Type Description
name string Nom complet de l'API inclus.
root string Si ce champ n'est pas vide, indique un chemin sous lequel les chemins HTTP hérités sont en mode root.

NullValue

NullValue est une énumération unique qui représente la valeur nulle pour l'union de type Value.

La représentation JSON de NullValue est JSON null.

Valeur d'énumération Description
NULL_VALUE Valeur nulle.

Option

Option de tampon de protocole, qui peut être associée à un message, un champ, une énumération, etc.

Nom du champ Type Description
name string Nom de l'option. Par exemple, "java_package".
value Any Valeur de l'option. Par exemple, "com.google.protobuf".

SourceContext

SourceContext représente les informations sur la source d'un élément protobuf, comme le fichier dans lequel il est défini.

Nom du champ Type Description
file_name string Nom complet du chemin du fichier .proto contenant l'élément protobuf associé. Exemple : "google/protobuf/source.proto".

StringValue

Message wrapper pour string.

La représentation JSON de StringValue est une chaîne JSON.

Nom du champ Type Description
value string Valeur de la chaîne.

Struct

Struct représente une valeur de données structurées, composée de champs qui correspondent à des valeurs de type dynamique. Dans certaines langues, Struct peut être compatible avec une représentation native. Par exemple, dans les langages de script comme JS, une structure est représentée en tant qu'objet. Les détails de cette représentation sont décrits avec la compatibilité du proto pour le langage.

La représentation JSON de Struct est un objet JSON.

Nom du champ Type Description
fields map<string, Value> Carte de valeurs de type dynamique.

Syntaxe

Syntaxe dans laquelle un élément de tampon de protocole est défini.

Valeur d'énumération Description
SYNTAX_PROTO2 Syntaxe proto2.
SYNTAX_PROTO3 Syntaxe proto3.

Code temporel

Un objet Timestamp représente un moment indépendant de tout fuseau horaire ou calendrier, représenté par des secondes et des fractions de secondes avec une précision de l'ordre de la nanoseconde dans l'epoch UTC. Il est encodé à l'aide du calendrier grégorien proleptique, qui étend le calendrier grégorien à la première année. L'objet est encodé en supposant que toutes les minutes durent 60 secondes, c'est-à-dire que les secondes intercalaires sont "lissées" de sorte qu'aucune table de secondes intercalaires n'est nécessaire pour l'interprétation. La plage va de 0001-01-01T00:00:00Z à 9999-12-31T23:59:59.999999999Z. En nous limitant à cette plage, nous nous assurons que nous pouvons convertir des chaînes de date au format RFC 3339. Consultez la page https://www.ietf.org/rfc/rfc3339.txt.

Exemple 1 : Calculer l'horodatage à partir du paramètre POSIX time()

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

Exemple 2 : Calculer l'horodatage à partir du paramètre POSIX gettimeofday()

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

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

Exemple 3 : Calculer l'horodatage à partir du paramètre 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));

Exemple 4 : Calculer l'horodatage à partir du paramètre Java System.currentTimeMillis()

long millis = System.currentTimeMillis();

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

Exemple 5 : Calculer l'horodatage à partir de l'heure actuelle en Python

now = time.time()
seconds = int(now)
nanos = int((now - seconds) * 10**9)
timestamp = Timestamp(seconds=seconds, nanos=nanos)
Nom du champ Type Description
seconds int64 Représente les secondes de l'heure UTC à partir de l'epoch Unix 1970-01-01T00:00:00Z. La valeur doit être comprise entre 0001-01-01T00:00:00Z et 9999-12-31T23:59:59Z inclus.
nanos int32 Fractions de secondes non négatives avec une précision de l'ordre de la nanoseconde. Les valeurs de secondes négatives avec des fractions doivent toujours comporter des valeurs de nanosecondes non négatives comptabilisées dans le temps. La valeur doit être comprise entre 0 et 999 999 999 inclus.

Type

Type de message de tampon de protocole.

Nom du champ Type Description
name string Nom complet du message.
fields Field Liste des champs.
oneofs string Liste des types figurant dans les définitions de oneof de ce type.
options Option Options de tampon de protocole.
source_context SourceContext Contexte source
syntax Syntax Syntaxe source.

UInt32Value

Message wrapper pour uint32.

La représentation JSON de UInt32Value est un nombre JSON.

Nom du champ Type Description
value uint32 Valeur uint32.

UInt64Value

Message wrapper pour uint64.

La représentation JSON de UInt64Value est une chaîne JSON.

Nom du champ Type Description
value uint64 Valeur uint64.

Valeur

Value représente une valeur de type dynamique qui peut être une valeur nulle, un nombre, une chaîne, une valeur booléenne, une valeur de structure récursive ou une liste de valeurs. Un producteur de valeur doit définir l'une de ces variantes. L'absence de variante indique une erreur.

La représentation JSON de Value est une valeur JSON.

Nom du champ Type Description
Union, un seul des champs suivants:
null_value NullValue Représente une valeur nulle.
number_value double Représente une double valeur. Notez que toute tentative de sérialisation de NaN ou d'Infinity entraîne une erreur. (Nous ne pouvons pas sérialiser ces valeurs en tant que valeurs "NaN" ou "Infinity" comme pour les champs standards, car ces valeurs seraient analysées en tant que "string_value", et non "number_value").
string_value string Représente une valeur de chaîne.
bool_value bool Représente une valeur booléenne.
struct_value Struct Représente une valeur structurée.
list_value ListValue Représente un Value répété.