Configurer Cloud Endpoints

Cette page décrit les fichiers de configuration nécessaires à la création d'un service gRPC géré par Endpoints.

Prérequis

Pour commencer, cette page suppose que vous avez :

Choisir le nom du service

Cloud Endpoints utilise comme nom de service le nom que vous avez défini dans le fichier YAML de configuration de votre API gRPC.

Le nom de votre service API doit être unique sur Google Cloud. Endpoints utilise des noms compatibles avec DNS pour identifier les services. Nous vous recommandons donc d'utiliser le nom de domaine ou le nom de sous-domaine de votre API en tant que nom de service. De cette manière, le nom du service qui apparaît sur la page Services Endpoints correspond au nom utilisé dans les requêtes adressées à votre API. De plus, si le nom du service est identique au nom du domaine, vous pouvez créer un portail Cloud Endpoints pour les utilisateurs de l'API. Endpoints doit répondre aux exigences suivantes concernant le nom du service :

  • La longueur maximale du nom de domaine est de 253 caractères.
  • Le nom de domaine doit commencer par une lettre minuscule.
  • Chaque section du nom de domaine, délimitée par des points, doit répondre aux exigences suivantes :
    • Doit commencer par une lettre minuscule.
    • Ne doit pas se terminer par un tiret.
    • Les caractères restants peuvent être des lettres minuscules, des chiffres ou des tirets.
    • La longueur ne doit pas dépasser 63 caractères.

Vous pouvez enregistrer votre propre domaine personnalisé (par exemple, example.com) ou utiliser un domaine géré par Google.

Utiliser un domaine géré par Google

Google possède et gère le domaine cloud.goog. Si vous souhaitez utiliser un domaine géré par Google, vous devez utiliser votre ID de projet Google Cloud dans le nom du service. Étant donné que les projets Google Cloud ont un ID de projet unique, cette exigence garantit que vous disposez d'un nom de service unique. Si vous souhaitez utiliser le domaine cloud.goog, le nom du service doit être au format suivant, où YOUR_API_NAME est le nom de l'API et YOUR_PROJECT_ID est l'ID de votre projet Google Cloud :

YOUR_API_NAME.endpoints.YOUR_PROJECT_ID.cloud.goog`

Pour l'utiliser comme nom de domaine de l'API, consultez la page Configurer un DNS sur le domaine cloud.goog.

Utiliser un domaine personnalisé

Si vous ne souhaitez pas utiliser un domaine géré par Google, vous pouvez utiliser un domaine personnalisé (par exemple, myapi.mycompany.com) que vous êtes autorisé à utiliser. Avant de déployer la configuration de l'API, suivez les étapes décrites sur la page Valider la propriété du domaine.

Configurer le tampon de protocole

  1. Créez un fichier .proto pour votre service. Consultez le guide du développeur
    pour en savoir plus.

  2. Compilez vos tampons de protocole à l'aide du compilateur protoc correspondant à votre langage. Exemple :

    protoc
  --proto_path=. \
  --include_imports \
  --include_source_info \
  --descriptor_set_out=api_descriptor.pb \
  bookstore.proto

    Dans la commande ci-dessus, --proto_path est défini sur le répertoire de travail actuel. Dans votre environnement de compilation gRPC, si vous utilisez un autre répertoire pour les fichiers d'entrée .proto, modifiez --proto_path pour que le compilateur recherche le répertoire dans lequel vous avez enregistré votre fichier .proto.

    Si la commande protoc permettant de générer votre fichier descripteur échoue, assurez-vous que :

    • votre version protoc est à jour ;
    • vous avez spécifié --proto_path ou sa forme abrégée -I pour les répertoires racine des fichiers .proto importés. Pour en savoir plus, consultez la documentation sur les tampons de protocole ;
    • vous avez spécifié --include_imports.

    Si vous souhaitez que vos clients accèdent à votre service gRPC en HTTP/JSON, vous devez spécifier le mode de conversion des données HTTP/JSON vers gRPC. Nous vous recommandons d'annoter les API définies dans votre fichier .proto. Pour en savoir plus, consultez la page Transcoder du contenu HTTP/JSON en gRPC.

Créer le fichier de configuration du service gRPC

Vous devez créer un fichier YAML de configuration du service gRPC. Spécifiez le nom du service et les restrictions d'utilisation, telles que la nécessité de définir une clé API dans ce fichier. Vous pouvez utiliser le fichier api_config.yaml de l'exemple Bookstore comme modèle.

  1. Enregistrez une copie du fichier api_config.yaml.

  2. Saisissez le nom de votre service dans le champ name. Exemple :

    name: bookstore.endpoints.example-project-12345.cloud.goog

  3. Saisissez le titre affiché sur la page Endpoints > Services de la console Google Cloud. Exemple :

    title: Bookstore gRPC API

  4. Saisissez le nom de l'API dans le champ apis:name. Le texte que vous saisissez doit correspondre exactement au nom complet de l'API de votre fichier .proto. Exemple :

    apis:
  - name: endpoints.examples.bookstore.Bookstore

  5. Configurez le reste du fichier. Exemple :

    #
# API usage restrictions.
#
usage:
  rules:
  # ListShelves methods can be called without an API Key.
  - selector: endpoints.examples.bookstore.Bookstore.ListShelves
    allow_unregistered_calls: true

    Pour plus de précisions, consultez les Règles et sélecteurs.

Étapes suivantes

Autres exemples de gRPC