Index
Any
(message)Api
(message)BoolValue
(message)BytesValue
(message)DoubleValue
(message)Duration
(message)Empty
(message)Enum
(message)EnumValue
(message)Field
(message)Field.Cardinality
(enum)Field.Kind
(enum)FieldMask
(message)FloatValue
(message)Int32Value
(message)Int64Value
(message)ListValue
(message)Method
(message)Mixin
(message)NullValue
(enum)Option
(message)SourceContext
(message)StringValue
(message)Struct
(message)Syntax
(enum)Timestamp
(message)Type
(message)UInt32Value
(message)UInt64Value
(message)Value
(message)
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
Vous pouvez utiliser des schémas autres que |
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 |
|
Méthodes de cette API, dans un ordre non spécifié. |
options |
|
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 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 |
source_context |
|
Contexte source pour le service de tampon de protocole représenté par ce message. |
mixins |
|
API incluses. Consultez les Mixin . |
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 |
|
Définitions de valeurs d'énumération. |
options |
|
Options de tampon de protocole. |
source_context |
|
Contexte source |
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 |
|
Options de tampon de protocole. |
Champ
Champ unique d'un type de message.
Nom du champ | Type | Description |
---|---|---|
kind |
|
Type de champ. |
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 |
|
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 |
|
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 |
|
Toutes les métadonnées associées à la méthode. |
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 |
|
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, |
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 |
|
Liste des champs. |
oneofs |
string |
Liste des types figurant dans les définitions de oneof de ce type. |
options |
|
Options de tampon de protocole. |
source_context |
|
Contexte source |
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 |
|
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 |
|
Représente une valeur structurée. |
list_value |
|
Représente un Value répété. |