REST Resource: projects.locations.grpcRoutes

Ressource: GrpcRoute

GrpcRoute est la ressource définissant la manière dont le trafic gRPC acheminé par une ressource de réseau maillé ou de passerelle est acheminé.

Représentation JSON
{
  "name": string,
  "selfLink": string,
  "createTime": string,
  "updateTime": string,
  "labels": {
    string: string,
    ...
  },
  "description": string,
  "hostnames": [
    string
  ],
  "meshes": [
    string
  ],
  "gateways": [
    string
  ],
  "rules": [
    {
      object (RouteRule)
    }
  ]
}
Champs
name

string

Obligatoire. Nom de la ressource GrpcRoute. Il correspond au schéma projects/*/locations/global/grpcRoutes/<grpc_route_name>

createTime

string (Timestamp format)

Uniquement en sortie. Code temporel de la création de la ressource.

Horodatage au format RFC3339 UTC "Zulu", avec une résolution de l'ordre de la nanoseconde et jusqu'à neuf chiffres décimaux. Exemples : "2014-10-02T15:01:23Z" et "2014-10-02T15:01:23.045123456Z".

updateTime

string (Timestamp format)

Uniquement en sortie. Code temporel de la mise à jour de la ressource.

Horodatage au format RFC3339 UTC "Zulu", avec une résolution de l'ordre de la nanoseconde et jusqu'à neuf chiffres décimaux. Exemples : "2014-10-02T15:01:23Z" et "2014-10-02T15:01:23.045123456Z".

labels

map (key: string, value: string)

Facultatif. Ensemble de tags d'étiquette associés à la ressource GrpcRoute.

Objet contenant une liste de paires "key": value. Exemple : { "name": "wrench", "mass": "1.3kg", "count": "3" }.

description

string

Facultatif. Description en texte libre de la ressource. Longueur maximale : 1 024 caractères.

hostnames[]

string

Obligatoire. Noms d'hôte de service avec un port facultatif pour lequel cette route décrit le trafic.

Format: [:]

Le nom d'hôte est le nom de domaine complet d'un hôte réseau. Cela correspond à la définition RFC 1123 des noms d'hôte, à deux exceptions près: - Les adresses IP ne sont pas autorisées. - Un nom d'hôte peut être précédé d'un libellé générique (*.). Le libellé générique doit apparaître seul en tant que premier libellé.

Le nom d'hôte peut être "exact", c'est-à-dire un nom de domaine sans le point de fin d'un hôte réseau (par exemple, foo.example.com) ou "caractère générique", qui correspond à un nom de domaine précédé d'une seule étiquette générique (par exemple, *.example.com).

Notez que conformément aux normes RFC1035 et RFC1123, une étiquette doit être composée de caractères alphanumériques en minuscules ou de "-", et doit commencer et se terminer par un caractère alphanumérique. Aucun autre signe de ponctuation n'est autorisé.

Les routes associées à un réseau maillé ou à une passerelle doivent avoir des noms d'hôte uniques. Si vous tentez d'associer plusieurs routes avec des noms d'hôte en conflit, la configuration sera refusée.

Par exemple, bien qu'il soit acceptable que les routes soient associées à la même route pour les noms d'hôte *.foo.bar.com et *.bar.com, il n'est pas possible d'associer deux routes à *.bar.com ou les deux à bar.com.

Si un port est spécifié, les clients gRPC doivent utiliser l'URI du canal avec le port correspondant à cette règle (par exemple, "xds:///service:123"), sinon ils doivent fournir l'URI sans port (par exemple, "xds:///service").

meshes[]

string

Facultatif. Les maillages définissent une liste de réseaux maillés auxquels ce GrpcRoute est associé, comme l'une des règles de routage pour acheminer les requêtes diffusées par le maillage.

Chaque référence au maillage doit correspondre au modèle suivant: projects/*/locations/global/meshes/<mesh_name>

gateways[]

string

Facultatif. Gateways définit la liste des passerelles auxquelles ce GrpcRoute est associé. Il s'agit de l'une des règles de routage permettant d'acheminer les requêtes diffusées par la passerelle.

Chaque référence de passerelle doit correspondre au format suivant: projects/*/locations/global/gateways/<gateway_name>

rules[]

object (RouteRule)

Obligatoire. Liste de règles détaillées définissant comment acheminer le trafic.

Dans une seule GrpcRoute, la classe GrpcRoute.RouteAction associée à la première GrpcRoute.RouteRule correspondante sera exécutée. Vous devez indiquer au moins une règle.

RouteRule

Cette page vous explique comment acheminer le trafic.

Représentation JSON
{
  "matches": [
    {
      object (RouteMatch)
    }
  ],
  "action": {
    object (RouteAction)
  }
}
Champs
matches[]

object (RouteMatch)

Facultatif. Les correspondances définissent les conditions utilisées pour mettre en correspondance la règle avec les requêtes gRPC entrantes. Chaque correspondance est indépendante : la règle sera prise en compte si l'une des correspondances est satisfaite. Si aucun champ de correspondance n'est spécifié, la règle mettra en correspondance le trafic sans condition.

action

object (RouteAction)

Obligatoire. Une règle détaillée définissant comment acheminer le trafic. Ce champ est obligatoire.

RouteMatch

Critères de trafic correspondant. Un RouteMatch est considéré comme correspondant lorsque tous les champs fournis correspondent.

Représentation JSON
{
  "headers": [
    {
      object (HeaderMatch)
    }
  ],
  "method": {
    object (MethodMatch)
  }
}
Champs
headers[]

object (HeaderMatch)

Facultatif. Spécifie une collection d'en-têtes à mettre en correspondance.

method

object (MethodMatch)

Facultatif. Méthode gRPC à mettre en correspondance. Si ce champ est vide ou omis, correspondra à toutes les méthodes.

MethodMatch

Spécifie une correspondance avec une méthode.

Représentation JSON
{
  "type": enum (Type),
  "grpcService": string,
  "grpcMethod": string,
  "caseSensitive": boolean
}
Champs
type

enum (Type)

Facultatif. Indique le type de correspondance avec le nom. Si aucune valeur n'est spécifiée, la valeur par défaut "EXACT" est utilisée.

grpcService

string

Obligatoire. Nom du service à mettre en correspondance. Si aucune valeur n'est spécifiée, la correspondance sera établie avec tous les services.

grpcMethod

string

Obligatoire. Nom de la méthode à mettre en correspondance. Si aucune valeur n'est spécifiée, renvoie toutes les méthodes.

caseSensitive

boolean

Facultatif. Indique que les correspondances sont sensibles à la casse. La valeur par défaut est "true". La sensibilité à la casse ne doit pas être utilisée avec un type REGULAR_EXPRESSION.

Type

Type de correspondance.

Enums
TYPE_UNSPECIFIED Non spécifié.
EXACT correspondra uniquement au nom exact fourni.
REGULAR_EXPRESSION Interpréter grpcMethod et grpcService comme des expressions régulières. La syntaxe RE2 est compatible.

HeaderMatch

Une correspondance avec une collection d'en-têtes.

Représentation JSON
{
  "type": enum (Type),
  "key": string,
  "value": string
}
Champs
type

enum (Type)

Facultatif. Spécifie la méthode de mise en correspondance avec la valeur de l'en-tête. Si aucune valeur n'est spécifiée, la valeur par défaut EXACT est utilisée.

key

string

Obligatoire. Clé de l'en-tête.

value

string

Obligatoire. Valeur de l'en-tête.

Type

Type de correspondance.

Enums
TYPE_UNSPECIFIED Non spécifié.
EXACT Ne correspond qu'à la valeur exacte fournie.
REGULAR_EXPRESSION Établir une correspondance avec les chemins conformes au préfixe spécifié par la valeur. La syntaxe RE2 est compatible.

RouteAction

Spécifie comment acheminer le trafic correspondant.

Représentation JSON
{
  "destinations": [
    {
      object (Destination)
    }
  ],
  "faultInjectionPolicy": {
    object (FaultInjectionPolicy)
  },
  "timeout": string,
  "retryPolicy": {
    object (RetryPolicy)
  },
  "statefulSessionAffinity": {
    object (StatefulSessionAffinityPolicy)
  },
  "idleTimeout": string
}
Champs
destinations[]

object (Destination)

Facultatif. Services de destination vers lesquels le trafic doit être transféré. Si plusieurs destinations sont spécifiées, le trafic sera réparti entre les services de backend en fonction du champ de pondération de ces destinations.

faultInjectionPolicy

object (FaultInjectionPolicy)

Facultatif. Spécification d'injection de pannes introduite dans le trafic pour tester la résilience des clients à l'échec du service de destination. Dans le cadre de l'injection de pannes, lorsque les clients envoient des requêtes à une destination, des retards peuvent être introduits sur un pourcentage de requêtes avant de les envoyer au service de destination. De même, les requêtes des clients peuvent être annulées pour un certain pourcentage de requêtes.

Le délai d'expiration et l'objet "RetryPolicy" sont ignorés par les clients configurés avec un paramètre faultInjectionPolicy.

timeout

string (Duration format)

Facultatif. Spécifie le délai avant expiration de la route sélectionnée. Le délai avant expiration est calculé à partir du moment où la requête a été entièrement traitée (c'est-à-dire, la fin du flux) jusqu'au moment où la réponse a été entièrement traitée. Le délai avant expiration inclut l'ensemble des nouvelles tentatives.

Durée en secondes avec neuf chiffres au maximum après la virgule et se terminant par "s". Exemple : "3.5s"

retryPolicy

object (RetryPolicy)

Facultatif. Spécifie la stratégie de nouvelle tentative associée à cette route.

statefulSessionAffinity

object (StatefulSessionAffinityPolicy)

Facultatif. Spécifie l'affinité de session avec état basée sur les cookies.

idleTimeout

string (Duration format)

Facultatif. Spécifie le délai d'inactivité pour la route sélectionnée. Le délai d'inactivité est défini comme la période au cours de laquelle aucun octet n'est envoyé ni reçu sur la connexion en amont ou en aval. Si cette règle n'est pas configurée, le délai d'inactivité par défaut est d'une heure. S'il est défini sur 0 s, le délai avant expiration est désactivé.

Durée en secondes avec neuf chiffres au maximum après la virgule et se terminant par "s". Exemple : "3.5s"

Destination

Destination vers laquelle le trafic sera acheminé.

Représentation JSON
{

  // Union field destination_type can be only one of the following:
  "serviceName": string
  // End of list of possible types for union field destination_type.
  "weight": integer
}
Champs
Champ d'union destination_type. Spécifie le type de destination vers lequel le trafic sera acheminé. destination_type ne peut être qu'un des éléments suivants :
serviceName

string

Obligatoire. URL d'un service de destination vers lequel acheminer le trafic. Doit faire référence à BackendService ou ServiceDirectoryService.

weight

integer

Facultatif. Spécifie la proportion de requêtes transférées au backend référencé par le champ serviceName. Cette valeur est calculée de la façon suivante: - weight/Sum(pondérations dans cette liste de destination). Pour les valeurs non nulles, il peut y avoir une valeur epsilon par rapport à la proportion exacte définie ici, en fonction de la précision acceptée par une implémentation.

Si un seul serviceName est spécifié et que sa pondération est supérieure à 0, la totalité du trafic est transmise à ce backend.

Si des pondérations sont spécifiées pour un nom de service donné, elles doivent l'être pour tous les noms de service.

Si les pondérations ne sont pas spécifiées pour tous les services, le trafic est réparti dans des proportions égales entre tous ces services.

FaultInjectionPolicy

Spécification d'injection de pannes introduite dans le trafic pour tester la résilience des clients à l'échec du service de destination. Dans le cadre de l'injection de pannes, lorsque les clients envoient des requêtes à une destination, des retards peuvent être introduits sur un pourcentage de requêtes avant de les envoyer au service de destination. De même, les requêtes des clients peuvent être annulées pour un certain pourcentage de requêtes.

Représentation JSON
{
  "delay": {
    object (Delay)
  },
  "abort": {
    object (Abort)
  }
}
Champs
delay

object (Delay)

Spécification permettant d'injecter un délai aux requêtes client.

abort

object (Abort)

Spécification permettant d'abandonner des requêtes client.

Délai

Spécification du retard des requêtes client dans le cadre de l'injection de pannes avant d'être envoyées à une destination.

Représentation JSON
{
  "fixedDelay": string,
  "percentage": integer
}
Champs
fixedDelay

string (Duration format)

Spécifiez un délai fixe avant de transmettre la requête.

Durée en secondes avec neuf chiffres au maximum après la virgule et se terminant par "s". Exemple : "3.5s"

percentage

integer

Pourcentage du trafic auquel le retard sera injecté.

La valeur doit être comprise entre 0 et 100

Annuler

Spécification de la manière dont les requêtes client sont annulées dans le cadre de l'injection de pannes avant d'être envoyées à une destination.

Représentation JSON
{
  "httpStatus": integer,
  "percentage": integer
}
Champs
httpStatus

integer

Code d'état HTTP utilisé pour annuler la requête.

La valeur doit être comprise entre 200 et 599 inclus.

percentage

integer

Pourcentage de trafic qui sera abandonné.

La valeur doit être comprise entre 0 et 100

RetryPolicy

Spécifications des nouvelles tentatives

Représentation JSON
{
  "retryConditions": [
    string
  ],
  "numRetries": integer
}
Champs
retryConditions[]

string

  • connect-failure: le routeur effectuera de nouvelles tentatives en cas d'échec de connexion aux services de backend (en raison d'expirations de délai de connexion, par exemple).
  • "Refused-stream" : le routeur effectue une nouvelle tentative si le service de backend réinitialise le flux avec un code d'erreur REFUSED_STREAM. Ce type de réinitialisation indique que vous pouvez réessayer sans risque.
  • annulé: le routeur effectuera une nouvelle tentative si le code d'état gRPC de l'en-tête de réponse est défini sur "cancelled" [annulée].
  • délai dépassé: le routeur effectuera une nouvelle tentative si le code d'état gRPC de l'en-tête de réponse est défini sur "délai dépassé".
  • ressource épuisée: le routeur effectue une nouvelle tentative si le code d'état gRPC de l'en-tête de réponse est défini sur "épuisé des ressources"
  • indisponible: le routeur réessaiera si le code d'état gRPC de l'en-tête de réponse est défini sur "indisponible".
numRetries

integer (uint32 format)

Spécifie le nombre autorisé de tentatives. Ce nombre doit être supérieur à zéro. Si aucune valeur n'est spécifiée, la valeur par défaut est 1.

StatefulSessionAffinityPolicy

Spécification de l'affinité de session avec état basée sur les cookies, où le plan de date fournit un "cookie de session" nommé "GSSA", qui encode un hôte de destination spécifique, et chaque requête contenant ce cookie sera dirigée vers cet hôte tant que l'hôte de destination reste opérationnel et opérationnel.

La bibliothèque de maillages sans proxy gRPC ou le proxy side-car gère le cookie de la session, mais le code de l'application cliente est chargé de copier le cookie de chaque RPC de la session vers le suivant.

Représentation JSON
{
  "cookieTtl": string
}
Champs
cookieTtl

string (Duration format)

Obligatoire. Valeur TTL du cookie pour l'en-tête Set-Cookie généré par le plan de données. La durée de vie du cookie peut être comprise entre 1 et 86 400 secondes (24 heures) inclus.

Durée en secondes avec neuf chiffres au maximum après la virgule et se terminant par "s". Exemple : "3.5s"

Méthodes

create

Crée une nouvelle route GrpcRoute dans un projet et un emplacement donnés.

delete

Supprime une seule GrpcRoute.

get

Récupère les détails d'une seule GrpcRoute.

list

Répertorie les GrpcRoutes dans un projet et un emplacement donnés.

patch

Met à jour les paramètres d'une seule GrpcRoute.