Index
AuthProvider(message)AuthRequirement(message)Authentication(message)AuthenticationRule(message)CustomHttpPattern(message)Documentation(message)DocumentationRule(message)Endpoint(message)Http(message)HttpRule(message)LabelDescriptor(message)LabelDescriptor.ValueType(enum)MetricDescriptor(message)MetricDescriptor.MetricKind(enum)MetricDescriptor.ValueType(enum)MetricRule(message)Page(message)Quota(message)QuotaLimit(message)Service(message)SystemParameter(message)SystemParameterRule(message)SystemParameters(message)Usage(message)UsageRule(message)
AuthProvider
Configuration d'un fournisseur d'authentification, y compris la compatibilité avec les jetons Web JSON (JWT)
| Champs | |
|---|---|
id |
Identifiant unique du fournisseur d'authentification. Il est désigné sous le nom Exemple : "bookstore_auth" |
issuer |
Identifie le compte principal qui a émis le jeton JWT. Consultez la section https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.1. Il s'agit généralement d'une URL ou d'une adresse e-mail. Exemple : Exemple : |
jwks_uri |
URL de la clé publique du fournisseur définie pour valider la signature du jeton JWT. Consultez la page relative à OpenID Discovery. Ce champ est facultatif si le document de l'ensemble de clés : peut être récupéré depuis [OpenID Discovery] (https://openid.net/specs/openid-connect-discovery-1_0.html) ; peut être déduit du domaine de messagerie de l'émetteur (par exemple, un compte de service Google). |
audiences |
Liste des audiences JWT auxquelles l'accès est accordé. Un jeton JWT contenant l'une de ces audiences sera accepté. En l'absence de ce paramètre, seuls les jetons JWT présentant l'audience "https:// Exemple :
|
authorization_url |
URL de redirection dans le cas où le jeton JWT est requis, mais est absent ou a expiré. Mise en œuvre du paramètre "authorizationUrl" défini dans la section "securityDefinitions" de la spécification OpenAPI. |
AuthRequirement
Exigences d'authentification définies par l'utilisateur, y compris la compatibilité des jetons JSON Web Token (JWT).
| Champs | |
|---|---|
provider_id |
Exemple :
|
audiences |
REMARQUE : Ce champ sera bientôt obsolète, une fois qu'AuthProvider.audiences sera mis en œuvre et accepté dans tous les composants de l'environnement d'exécution. Liste des audiences JWT auxquelles l'accès est accordé. Un jeton JWT contenant l'une de ces audiences sera accepté. En l'absence de ce paramètre, seuls les jetons JWT présentant l'audience "https:// Exemple :
|
Authentification
Authentication définit la configuration de l'authentification pour une API.
Exemple pour une API destinée à une utilisation externe :
name: calendar.googleapis.com
authentication:
providers:
- id: google_calendar_auth
jwks_uri: https://www.googleapis.com/oauth2/v1/certs
issuer: https://securetoken.google.com
rules:
- selector: "*"
requirements:
provider_id: google_calendar_auth
| Champs | |
|---|---|
rules[] |
Liste des règles d'authentification s'appliquant individuellement aux méthodes d'API. REMARQUE : Toutes les règles de configuration de service obéissent au principe de "priorité au dernier", selon lequel c'est la dernière règle qui l'emporte. |
providers[] |
Définit un ensemble de fournisseurs d'authentification pris en charge par un service. |
AuthenticationRule
Règles d'authentification pour le service.
Par défaut, si une méthode présente des exigences d'authentification, chaque requête doit contenir un identifiant valide répondant à l'une de ces exigences. C'est une erreur d'inclure plusieurs types d'identifiants dans une même requête.
Si une méthode ne présente pas d'exigences d'authentification, les identifiants présents dans la requête seront ignorés.
| Champs | |
|---|---|
selector |
Sélectionne les méthodes auxquelles la règle s'applique. Consultez la section |
requirements[] |
Exigences pour les fournisseurs d'authentification supplémentaires. |
CustomHttpPattern
Un modèle personnalisé sert à définir un verbe HTTP personnalisé.
| Champs | |
|---|---|
kind |
Nom de ce verbe HTTP personnalisé. |
path |
Chemin correspondant à ce verbe personnalisé. |
Documentation
Documentation fournit les informations permettant de décrire un service.
Exemple :
documentation:
summary: >
The Google Calendar API gives access
to most calendar features.
pages:
- name: Overview
content: (== include google/foo/overview.md ==)
- name: Tutorial
content: (== include google/foo/tutorial.md ==)
subpages;
- name: Java
content: (== include google/foo/tutorial_java.md ==)
rules:
- selector: google.calendar.Calendar.Get
description: >
...
- selector: google.calendar.Calendar.Put
description: >
...
La documentation est fournie dans la syntaxe Markdown. Outre les fonctionnalités standards de Markdown, les listes de définitions, les tableaux et les blocs de code isolés sont acceptés. Il est possible de fournir des en-têtes de section, qui sont alors interprétés sur la base de l'imbrication des sections propre au contexte dans lequel un fragment de documentation est intégré.
La documentation générée par le langage de définition d'interface (IDL, Interface Definition Language) est fusionnée avec la documentation définie par la configuration au moment de la normalisation, sachant que la documentation fournie par les règles de configuration remplace l'IDL fourni.
Un certain nombre de constructions spécifiques à la plate-forme d'API sont gérées dans le texte de la documentation :
Pour faire référence à un élément proto, vous pouvez utiliser la notation suivante :
[fully.qualified.proto.name][]Pour remplacer le texte d'affichage associé au lien, vous pouvez utiliser cette notation :
[display text][fully.qualified.proto.name]Vous avez la possibilité d'exclure du texte de la documentation en utilisant la notation suivante :
(-- internal comment --)Vous pouvez également rendre les commentaires conditionnels à l'aide d'une étiquette de visibilité. Le texte ci-dessous ne fera l'objet d'un rendu que si l'étiquette BETA est disponible :
(--BETA: comment for BETA users --)La documentation met à disposition quelques directives. Notez que les directives doivent apparaître sur une seule ligne pour être correctement identifiées. La directive include inclut un fichier Markdown provenant d'une source externe :
(== include path/to/file ==)La directive resource_for permet de marquer un message en tant que ressource d'une collection dans la vue REST. Si la ressource n'est pas spécifiée, les outils tentent de la déduire des opérations spécifiées dans une collection :
(== resource_for v1.shelves.books ==)La directive suppress_warning n'affecte pas directement la documentation. Elle est documentée conjointement avec la validation de la configuration du service.
| Champs | |
|---|---|
summary |
Résumé du service assuré. Ne peut être fourni que sous forme de texte brut. |
pages[] |
Pages de premier niveau associées à l'ensemble de documentation. |
rules[] |
Liste de règles de documentation qui s'appliquent aux différents éléments de l'API. REMARQUE : Toutes les règles de configuration de service obéissent au principe de "priorité au dernier", selon lequel c'est la dernière règle qui l'emporte. |
documentation_root_url |
URL de la racine de la documentation. |
overview |
Permet de déclarer une page d'aperçu unique. Par exemple :
Raccourci pour la déclaration suivante (utilisant le style des pages) :
Remarque : Vous ne pouvez pas spécifier à la fois les champs |
DocumentationRule
Une règle de documentation fournit des informations sur les différents éléments de l'API.
| Champs | |
|---|---|
selector |
Le sélecteur est une liste de schémas séparés par des virgules. Chaque schéma représente le nom complet d'un élément, susceptible de se terminer par le caractère générique "*". Les caractères génériques ne sont autorisés qu'à la fin et pour un composant entier du nom complet. Par exemple, "foo.*" est valide, mais pas "foo.b*" ni "foo.*.bar". Pour spécifier une valeur par défaut pour tous les éléments applicables, c'est le schéma "*" tout entier qui est utilisé. |
description |
Description de la ou des API sélectionnées. |
deprecation_description |
Description de l'obsolescence du ou des éléments sélectionnés. Une telle description peut être fournie lorsqu'un élément est marqué comme |
Endpoint
Endpoint décrit un point de terminaison de réseau diffusant un ensemble d'API. Un service peut exposer un nombre quelconque de points de terminaison, et tous les points de terminaison partagent la même configuration de service, en particulier en termes de quotas et de surveillance.
Exemple de configuration de service :
name: library-example.googleapis.com
endpoints:
# Below entry makes 'google.example.library.v1.Library'
# API be served from endpoint address library-example.googleapis.com.
# It also allows HTTP OPTIONS calls to be passed to the backend, for
# it to decide whether the subsequent cross-origin request is
# allowed to proceed.
- name: library-example.googleapis.com
allow_cors: true
| Champs | |
|---|---|
name |
Nom canonique de ce point de terminaison. |
allow_cors |
Le fait d'autoriser le partage de ressources interorigines (CORS, Cross-Origin Resource Sharing), autrement dit le trafic interdomaine, permet aux backends diffusés par ce point de terminaison de recevoir des requêtes HTTP OPTIONS et d'y répondre. Le navigateur s'appuiera sur la réponse pour autoriser ou non le traitement de la requête multi-origines suivante. |
HTTP
Définit la configuration HTTP pour un service d'API. Il contient une liste de règles HttpRule spécifiant chacune comment mapper une méthode RPC sur une ou plusieurs méthodes API HTTP REST.
| Champs | |
|---|---|
rules[] |
Liste des règles de configuration HTTP s'appliquant individuellement aux méthodes d'API. REMARQUE : Toutes les règles de configuration de service obéissent au principe de "priorité au dernier", selon lequel c'est la dernière règle qui l'emporte. |
fully_decode_reserved_expansion |
Lorsque ce champ est défini à la valeur true, les paramètres de chemin d'URL sont entièrement décodés en URI, sauf en cas de correspondance de segments individuels en extension réservée, auquel cas "%2F" reste encodé. Le comportement par défaut consiste à ne pas décoder les caractères réservés RFC 6570 dans les correspondances multi-segments. |
HttpRule
HttpRule définit comment mapper une méthode RPC vers une ou plusieurs méthodes API HTTP REST. Le mappage spécifie comment les différentes parties constituant le message de la requête RPC sont mappées vers le chemin de l'URL, les paramètres de requête de l'URL et le corps de la requête HTTP. Le mappage est généralement spécifié sous la forme d'une annotation google.api.http sur la méthode RPC (pour plus d'informations, reportez-vous à la section "google/api/annotations.proto").
Le mappage est constitué d'un champ spécifiant le modèle de chemin et le type de méthode. Le modèle de chemin peut faire référence à des champs dans le message de la requête, comme dans l'exemple ci-dessous qui décrit une opération REST GET appliquée à une collection de ressources de messages :
service Messaging {
rpc GetMessage(GetMessageRequest) returns (Message) {
option (google.api.http).get = "/v1/messages/{message_id}/{sub.subfield}";
}
}
message GetMessageRequest {
message SubMessage {
string subfield = 1;
}
string message_id = 1; // mapped to the URL
SubMessage sub = 2; // `sub.subfield` is url-mapped
}
message Message {
string text = 1; // content of the resource
}
Il est également possible d'exprimer la même annotation HTTP dans le fichier YAML GRPC API Configuration.
http:
rules:
- selector: <proto_package_name>.Messaging.GetMessage
get: /v1/messages/{message_id}/{sub.subfield}
Cette définition active un mappage bidirectionnel automatique de HTTP JSON vers RPC. Exemple :
| HTTP | RPC |
|---|---|
GET /v1/messages/123456/foo |
GetMessage(message_id: "123456" sub: SubMessage(subfield: "foo")) |
En général, il est possible à partir d'un modèle de chemin de référencer non seulement des champs, mais également des chemins d'accès à des champs. Les champs mappés dans le modèle de chemin ne peuvent pas être répétés et doivent posséder un type primitif (c'est-à-dire ne pas être un message).
Tout champ du message de requête qui n'est pas lié par le modèle de chemin devient alors automatiquement un paramètre de requête HTTP (facultatif). Imaginons la définition suivante pour le message de requête :
service Messaging {
rpc GetMessage(GetMessageRequest) returns (Message) {
option (google.api.http).get = "/v1/messages/{message_id}";
}
}
message GetMessageRequest {
message SubMessage {
string subfield = 1;
}
string message_id = 1; // mapped to the URL
int64 revision = 2; // becomes a parameter
SubMessage sub = 3; // `sub.subfield` becomes a parameter
}
Cette définition active un mappage de HTTP JSON vers RPC comme suit :
| HTTP | RPC |
|---|---|
GET /v1/messages/123456?revision=2&sub.subfield=foo |
GetMessage(message_id: "123456" revision: 2 sub: SubMessage(subfield: "foo")) |
Notez que les champs mappés avec les paramètres HTTP doivent présenter un type primitif ou un type primitif répété. Les types de message ne sont pas autorisés. Dans le cas d'un type répété, le paramètre peut figurer plusieurs fois dans l'URL, comme par exemple ...?param=A¶m=B.
Pour les types de méthodes HTTP autorisant un corps de requête, le champ body spécifie le mappage. Considérons une méthode de mise à jour REST d'une collection de ressources de message :
service Messaging {
rpc UpdateMessage(UpdateMessageRequest) returns (Message) {
option (google.api.http) = {
put: "/v1/messages/{message_id}"
body: "message"
};
}
}
message UpdateMessageRequest {
string message_id = 1; // mapped to the URL
Message message = 2; // mapped to the body
}
Le mappage de HTTP JSON vers RPC présenté ci-dessous est activé. La représentation du JSON dans le corps de la requête est déterminée par l'encodage des protos JSON :
| HTTP | RPC |
|---|---|
PUT /v1/messages/123456 { "text": "Hi!" } |
UpdateMessage(message_id: "123456" message { text: "Hi!" }) |
Le nom spécial * peut être utilisé dans le mappage du corps pour indiquer que tout champ non lié par le modèle de chemin d'accès doit être mappé vers le corps de la requête. Ceci active la définition alternative suivante pour la méthode de mise à jour :
service Messaging {
rpc UpdateMessage(Message) returns (Message) {
option (google.api.http) = {
put: "/v1/messages/{message_id}"
body: "*"
};
}
}
message Message {
string message_id = 1;
string text = 2;
}
Le mappage HTTP JSON vers RPC suivant est activé :
| HTTP | RPC |
|---|---|
PUT /v1/messages/123456 { "text": "Hi!" } |
UpdateMessage(message_id: "123456" text: "Hi!") |
Notez que lorsque vous utilisez * dans le mappage du corps, il n'est pas possible d'avoir des paramètres HTTP. En effet, tous les champs non liés par le chemin sont intégrés au corps. De ce fait, dans la pratique, cette option est plus rarement utilisée pour définir des API REST. * est plus couramment utilisée dans les méthodes personnalisées qui ne font pas du tout appel à l'URL pour transférer des données.
Il est possible de définir plusieurs méthodes HTTP pour une même méthode RPC grâce à l'option additional_bindings. Exemple :
service Messaging {
rpc GetMessage(GetMessageRequest) returns (Message) {
option (google.api.http) = {
get: "/v1/messages/{message_id}"
additional_bindings {
get: "/v1/users/{user_id}/messages/{message_id}"
}
};
}
}
message GetMessageRequest {
string message_id = 1;
string user_id = 2;
}
Cela active les deux mappages alternatifs HTTP JSON vers RPC suivants :
| HTTP | RPC |
|---|---|
GET /v1/messages/123456 |
GetMessage(message_id: "123456") |
GET /v1/users/me/messages/123456 |
GetMessage(user_id: "me" message_id: "123456") |
Règles pour le mappage HTTP
Les règles de mappage du chemin, des paramètres de requête et des champs du corps HTTP avec le message de requête sont les suivantes :
- Le champ
bodyspécifie soit*, soit un chemin d'accès à un champ, ou alors il est omis. S'il est omis, cela indique qu'il n'y a pas de corps de requête HTTP. - Les champs feuilles (correspondant au développement récursif de messages imbriqués dans la requête) peuvent être classés en trois catégories : (a) Champs avec correspondance dans le modèle d'URL. (b) Champs couverts par le corps (si le corps est
*, cela inclut tout élément sauf les champs (a) ; sinon, tout ce qui figure sous le corps) (c) Tous les autres champs. - Les paramètres de requête de l'URL identifiés dans la requête HTTP sont mappés vers des champs (c).
- Tout corps envoyé avec une requête HTTP ne peut contenir que des champs de type (b).
La syntaxe du modèle de chemin est la suivante :
Template = "/" Segments [ Verb ] ;
Segments = Segment { "/" Segment } ;
Segment = "*" | "**" | LITERAL | Variable ;
Variable = "{" FieldPath [ "=" Segments ] "}" ;
FieldPath = IDENT { "." IDENT } ;
Verb = ":" LITERAL ;
La syntaxe * correspond à un segment de chemin unique. La syntaxe ** correspond à zéro ou plusieurs segments de chemin, qui doivent constituer la dernière partie du chemin à l'exception du Verb. La syntaxe LITERAL correspond au texte littéral dans le chemin.
La syntaxe Variable correspond à une partie du chemin de l'URL telle que spécifiée par son modèle. Un modèle de variable ne doit pas contenir d'autres variables. Si une variable correspond à un unique segment de chemin, son modèle peut être omis : par exemple, {var} est équivalent à {var=*}.
Si une variable contient exactement un segment de chemin (par exemple "{var}" ou "{var=*}"), alors lorsqu'elle est développée dans un chemin d'URL, tous les caractères, à l'exception de [-_.~0-9a-zA-Z], sont encodés en pourcentage. Les variables de ce type apparaissent dans le document de découverte sous la forme {var}.
Si une variable contient un ou plusieurs segments de chemin (par exemple "{var=foo/*}" ou "{var=**}"), alors lorsqu'elle est développée dans un chemin d'URL, tous les caractères, à l'exception de [-_.~/0-9a-zA-Z], sont encodés en pourcentage. Les variables de ce type apparaissent dans le document de découverte sous la forme {+var}.
REMARQUE : Bien que la variable à segment unique corresponde à la sémantique de la RFC 6570 Section 3.2.2 Simple String Expansion (Extension de chaîne simple), la variable à segments multiples ne correspond pas à la RFC 6570 en matière d'extension réservée. Ceci est dû au fait que l'extension réservée ne développe pas les caractères spéciaux tels que ? et #, ce qui conduirait à des URL incorrectes.
REMARQUE : les chemins d'accès aux champs dans les variables et dans le corps body ne doivent pas faire référence à des champs répétés ou à des champs de mise en correspondance.
| Champs | ||
|---|---|---|
selector |
Sélectionne les méthodes auxquelles la règle s'applique. Consultez la section |
|
body |
Nom du champ de requête dont la valeur est mappée vers le corps HTTP ou |
|
additional_bindings[] |
Liaisons HTTP supplémentaires pour le sélecteur. Les liaisons imbriquées ne doivent pas elles-mêmes contenir de champ |
|
rest_collection |
NE PAS UTILISER. Il s'agit d'un champ expérimental. Facultatif. Par défaut, le nom de la collection REST est dérivé du modèle d'URL. S'il est spécifié, ce champ remplace le nom de la collection par défaut. Exemple :
Pour cette méthode, le nom de collection est dérivé automatiquement et correspond à "projects.aggregated". Sémantiquement, ce RPC est en fait une opération sur la collection "projects.addresses". Par conséquent, le champ |
|
rest_method_name |
NE PAS UTILISER. Il s'agit d'un champ expérimental. Facultatif. Par défaut, le nom de la méthode REST est dérivé du modèle d'URL. S'il est spécifié, ce champ remplace le nom de méthode par défaut. Exemple :
Pour cette méthode, le nom dérivé automatiquement est "create", mais pour des raisons de rétro-compatibilité avec apiary, il est spécifié en tant que "insert". |
|
Champ d'union pattern. Détermine si le modèle d'URL correspond à ces règles. Ce modèle peut être utilisé avec n'importe laquelle des méthodes {get|put|post|delete|patch}. Il est possible de définir une méthode personnalisée à l'aide du champ "custom". pattern ne peut être qu'un des éléments suivants : |
||
get |
Utilisé pour répertorier les ressources et obtenir des informations sur celles-ci. |
|
put |
Utilisé pour mettre à jour une ressource. |
|
post |
Utilisé pour créer une ressource. |
|
delete |
Utilisé pour supprimer une ressource. |
|
patch |
Utilisé pour mettre à jour une ressource. |
|
custom |
Le modèle personnalisé est utilisé pour spécifier une méthode HTTP qui n'est pas incluse dans le champ |
|
LabelDescriptor
Description d'un libellé.
| Champs | |
|---|---|
key |
Clé du libellé. |
value_type |
Type de données pouvant être affecté au libellé. |
description |
Description du libellé dans un format lisible. |
ValueType
Types de valeur pouvant être utilisés en tant que valeurs de libellés.
| Énumérations (Enums) | |
|---|---|
STRING |
Chaîne de longueur variable. Il s'agit de la valeur par défaut. |
BOOL |
Booléen : TRUE ou FALSE. |
INT64 |
Entier signé de 64 bits |
MetricDescriptor
Définit un type de métrique et son schéma. Une fois qu'un descripteur de métrique est créé, sa suppression ou sa modification arrête la collecte de données et rend inutilisables les données existantes qui lui sont associées.
| Champs | |
|---|---|
name |
Nom de ressource du descripteur de métrique. |
type |
Type de métrique, y compris son préfixe de nom DNS. Le type n'est pas encodé au format URL. Tous les types de métriques personnalisés définis par les utilisateurs possèdent le nom DNS
|
labels[] |
Ensemble de libellés pouvant être utilisés pour décrire une instance spécifique de ce type de métrique. Par exemple, le type de métrique |
metric_kind |
Indique si la métrique enregistre des valeurs instantanées, des variations d'une valeur, etc. Certaines combinaisons de |
value_type |
Indique si la mesure est un entier, un nombre à virgule flottante, etc. Certaines combinaisons de |
unit |
Unité associée à la valeur de la métrique. Cela ne s'applique que si le type de valeur Unités de base (UNIT)
Préfixes (PREFIX)
Grammaire La grammaire inclut l’unité sans dimension La grammaire comprend également les connecteurs suivants :
La grammaire d'une unité est la suivante :
Remarques :
|
description |
Description détaillée de la métrique, qui peut être utilisée dans la documentation. |
display_name |
Un nom concis pour la métrique, qui peut être affiché dans les interfaces utilisateur. Utilisez la même casse que dans une phrase, sans toutefois de point final, par exemple "Nombre de requêtes". Ce champ est facultatif, mais il est recommandé de le définir pour toute métrique associée à des concepts visibles par l'utilisateur, par exemple un Quota. |
MetricKind
Le type de métrique. Il décrit comment les données sont enregistrées.
| Énumérations (Enums) | |
|---|---|
METRIC_KIND_UNSPECIFIED |
N'utilisez pas cette valeur par défaut. |
GAUGE |
Mesure instantanée d'une valeur. |
DELTA |
Amplitude d'une valeur au cours d'un intervalle de temps. |
CUMULATIVE |
Valeur cumulée sur un intervalle de temps. Les mesures cumulatives au sein d'une série temporelle doivent correspondre au même instant initial et voir les instants finaux s'accroître jusqu'à ce qu'un événement réinitialise la valeur cumulative à zéro et définisse un nouvel instant initial pour les points suivants. |
ValueType
Le type de valeur d'une métrique.
| Énumérations (Enums) | |
|---|---|
VALUE_TYPE_UNSPECIFIED |
N'utilisez pas cette valeur par défaut. |
BOOL |
La valeur est de type booléen. Ce type de valeur ne peut être utilisé que si le type de métrique associé est GAUGE. |
INT64 |
La valeur est un entier signé de 64 bits. |
DOUBLE |
La valeur est un nombre à virgule flottante à double précision. |
STRING |
La valeur est une chaîne de caractères. Ce type de valeur ne peut être utilisé que si le type de métrique associé est GAUGE. |
DISTRIBUTION |
La valeur est de type [Distribution][google.api.Distribution]. |
MONEY |
La valeur est de type monétaire. |
MetricRule
Permet de lier des méthodes de l'API à des métriques. Lorsqu'une méthode est liée à une métrique, le comportement des quotas configurés pour cette métrique s'applique à l'appel de la méthode.
| Champs | |
|---|---|
selector |
Sélectionne les méthodes auxquelles la règle s'applique. Consultez la section |
metric_costs |
Métriques à mettre à jour lorsque les méthodes sélectionnées sont appelées, et coût associé à chacune de ces métriques. La clé du mappage est le nom de la métrique, et les valeurs représentent l'augmentation associée à la métrique visée par les limites de quota. La valeur ne doit pas être négative. |
Page
Représente une page de documentation. Une page peut contenir des sous-pages afin de représenter une structure d'ensemble de documentations imbriquées.
| Champs | |
|---|---|
name |
Nom de la page. Ce nom servira d'identifiant pour générer l'URI de la page, le texte du lien pointant vers cette page dans la navigation, etc. Le nom complet de la page est formé par concaténation des noms de la page racine et de ses sous-pages successives jusqu'à cette page, séparés par un point (
Vous pouvez utiliser la syntaxe des liens de référence Markdown pour faire référence à une page |
content |
Contenu Markdown de la page. Vous pouvez utiliser la notation
pour inclure le contenu d'un fichier Markdown. |
subpages[] |
Sous-pages de cette page. L'ordre que vous spécifiez ici pour les sous-pages sera respecté dans le docset généré. |
Quotas
La configuration de quotas contribue à plus d'équité et à une meilleure budgétisation dans l'utilisation des services.
La configuration de quotas fonctionne comme suit : - La configuration du service définit un ensemble de métriques. - Pour les appels d'API, l'élément quota.metric_rules mappe les méthodes vers des métriques associées à des coûts. - L'élément quotas.limits définit les limites de métriques qui seront utilisées pour les vérifications de quota lors de l'exécution.
Voici un exemple de configuration de quota au format YAML :
Quota :
- name: apiWriteQpsPerProject
metric: library.googleapis.com/write_calls
unit: "1/min/{project}" # rate limit for consumer projects
values:
STANDARD: 10000
# The metric rules bind all methods to the read_calls metric,
# except for the UpdateBook and DeleteBook methods. These two methods
# are mapped to the write_calls metric, with the UpdateBook method
# consuming at twice rate as the DeleteBook method.
metric_rules:
- selector: "*"
metric_costs:
library.googleapis.com/read_calls: 1
- selector: google.example.library.v1.LibraryService.UpdateBook
metric_costs:
library.googleapis.com/write_calls: 2
- selector: google.example.library.v1.LibraryService.DeleteBook
metric_costs:
library.googleapis.com/write_calls: 1
Définition des métriques correspondantes :
metrics:
- name: library.googleapis.com/read_calls
display_name: Read requests
metric_kind: DELTA
value_type: INT64
- name: library.googleapis.com/write_calls
display_name: Write requests
metric_kind: DELTA
value_type: INT64
| Champs | |
|---|---|
limits[] |
Liste des définitions |
metric_rules[] |
Liste des définitions |
QuotaLimit
QuotaLimit définit une limite déterminée qui s'applique sur une durée spécifiée pour un type de limite. Il peut y avoir au plus une limite pour chacune des combinaisons entre durée et type de limite définies dans un groupe de quotas (QuotaGroup).
| Champs | |
|---|---|
name |
Nom de la limite de quota. Ce nom doit être spécifié et il doit être unique dans le service. Il ne peut contenir que des caractères alphanumériques et des tirets ("-"). La longueur maximale d'un nom de limite est de 64 caractères. |
description |
Facultatif. Description détaillée de la limite de quota, visible par l'utilisateur. Ce champ ne doit être utilisé que pour des limites dont la compréhension nécessite davantage de contexte que les indications fournies par leur nom d'affichage (voir l'élément |
metric |
Nom de la métrique à laquelle la limite de quota s'applique. Les limites de quota associées à une même métrique seront vérifiées ensemble pendant l'exécution. La métrique doit être définie dans la configuration du service. |
unit |
Unité dans laquelle la limite de quota est spécifiée. Cette valeur respecte la même syntaxe que [Metric.unit][]. Les types d'unité acceptés sont déterminés par le système backend des quotas. En voici un exemple : * "1/min/{projet}" pour un quota par minute et par projet. Remarque : L'ordre des composants de l'unité n'est pas significatif. Le "1" initial est imposé par la syntaxe des unités de métriques. |
values |
Valeurs de limite par niveau. Vous devez spécifier ce champ sous la forme d'une paire clé/valeur, avec une valeur entière représentant le nombre maximal de requêtes autorisées pour l'unité spécifiée. Actuellement, seul le niveau STANDARD est accepté. |
Service
Service est l'objet racine du schéma de configuration des services Google. Il contient les informations de base relatives à un service telles que son nom et son titre, tandis que les autres aspects sont délégués à des sous-sections. Chaque sous-section est constituée d'un message proto unique ou répété, qui configure un aspect spécifique, tel que auth. Pour plus de détails, consultez la définition de chaque message proto pour plus de détails.
Exemple :
type: google.api.Service
config_version: 3
name: calendar.googleapis.com
title: Google Calendar API
apis:
- name: google.calendar.v3.Calendar
authentication:
providers:
- id: google_calendar_auth
jwks_uri: https://www.googleapis.com/oauth2/v1/certs
issuer: https://securetoken.google.com
rules:
- selector: "*"
requirements:
provider_id: google_calendar_auth
| Champs | |
|---|---|
config_version |
Version sémantique de la configuration du service. La version de la configuration affecte l'interprétation de la configuration du service. Par exemple, certaines fonctionnalités sont activées par défaut pour certaines versions de configuration. La dernière version de la configuration est |
name |
Adresse DNS à laquelle le service est disponible, par exemple |
id |
Identifiant unique pour une instance spécifique de ce message, généralement attribué par le client à des fins de suivi. Si ce champ est vide, le serveur peut choisir d'en générer un. |
title |
Titre de produit associé au service. |
apis[] |
Liste des interfaces API exportées par le service. Seul le champ |
types[] |
Liste de tous les types de messages proto inclus dans ce service d'API. Les types référencés directement ou indirectement par les
|
enums[] |
Liste de tous les types d’énumération inclus dans ce service d’API. Les énumérations référencées par les
|
http |
Configuration HTTP. |
quota |
Configuration des quotas. |
authentication |
Configuration de l'authentification. |
usage |
Configuration contrôlant l'utilisation de ce service. |
endpoints[] |
Configuration pour les points de terminaison du réseau. Si ce champ est laissé vide, un point de terminaison portant le même nom que le service est automatiquement généré pour desservir toutes les API définies. |
metrics[] |
Définit les métriques utilisées par ce service. |
system_parameters |
Configuration des paramètres système. |
SystemParameter
Définit le nom et l'emplacement d'un paramètre. Le paramètre peut être transmis sous la forme d'un en-tête HTTP ou d'un paramètre de requête dans l'URL. Si un paramètre est transmis par ces deux voies, le comportement dépend de la mise en œuvre.
| Champs | |
|---|---|
name |
Définit le nom du paramètre, par exemple "api_key". Ce champ est sensible à la casse. |
http_header |
Définit le nom de l'en-tête HTTP à utiliser pour ce paramètre. Ce champ n'est pas sensible à la casse. |
url_query_parameter |
Définit le nom du paramètre de requête d'URL à utiliser pour ce paramètre. Ce champ est sensible à la casse. |
SystemParameterRule
Définit une règle de paramètre système assurant une correspondance entre les définitions de paramètres système et des méthodes.
| Champs | |
|---|---|
selector |
Sélectionne les méthodes auxquelles la règle s'applique. Le caractère générique "*" désigne toutes les méthodes de toutes les API. Consultez la section |
parameters[] |
Définit les paramètres. Plusieurs noms peuvent être définis pour un même paramètre. Pour un appel de méthode donné, un seul d'entre eux doit être utilisé. Si plusieurs noms sont utilisés, le comportement dépend de la mise en œuvre. Si aucun des noms spécifiés n'est présent, le comportement dépend du paramètre. |
SystemParameters
Configuration des paramètres système
Un paramètre système est un type particulier de paramètre défini par le système d'API et non par une API individuelle. Il est généralement associé à un en-tête HTTP et/ou à un paramètre de requête d'URL. Cette configuration spécifie quelles méthodes modifient les noms des paramètres système.
| Champs | |
|---|---|
rules[] |
Définit les paramètres du système. Les paramètres définis ici remplaceront les paramètres par défaut mis en œuvre par le système. Si ce champ est absent de la configuration du service, les paramètres système par défaut seront utilisés. Les paramètres système par défaut, ainsi que les noms, dépendent de la mise en œuvre. Exemple : définition d'une clé API pour toutes les méthodes
Exemple : définition de deux noms de clé API pour une méthode donnée.
REMARQUE : Toutes les règles de configuration de service obéissent au principe de "priorité au dernier", selon lequel c'est la dernière règle qui l'emporte. |
Utilisation
Configuration contrôlant l'utilisation d'un service.
| Champs | |
|---|---|
rules[] |
Liste de règles d'utilisation s'appliquant à différentes méthodes d'API. REMARQUE : Toutes les règles de configuration de service obéissent au principe de "priorité au dernier", selon lequel c'est la dernière règle qui l'emporte. |
UsageRule
Règles de configuration d'utilisation associées au service.
Remarque : En cours de développement.
Cette règle vous permet de configurer les appels du service qui n'ont pas été enregistrés. Les appels non enregistrés sont ceux qui ne contiennent pas l'identité du projet client (par exemple, les appels ne contenant pas de clé API). Par défaut, les méthodes d'API n'autorisent pas les appels non enregistrés, et chaque appel de méthode doit être identifié par une identité de projet client. Cette règle vous permet d'autoriser ou d'interdire les appels non enregistrés.
Exemple d'API autorisant les appels non enregistrés pour l'ensemble d'un service :
usage:
rules:
- selector: "*"
allow_unregistered_calls: true
Exemple de méthode autorisant les appels non enregistrés :
usage:
rules:
- selector: "google.example.library.v1.LibraryService.CreateBook"
allow_unregistered_calls: true
| Champs | |
|---|---|
selector |
Sélectionne les méthodes auxquelles la règle s'applique. Le caractère générique "*" désigne toutes les méthodes de toutes les API. Consultez la section |
allow_unregistered_calls |
Si la valeur est "true", la méthode sélectionnée autorise les appels non enregistrés (par exemple, les appels qui n'identifient pas d'utilisateur ni d'application). |