Créer un veilleur

Cette page explique comment créer une ressource "service de veille". Pour en savoir plus sur les services de veille, consultez les principes de base de Runtime Configurator.

Une ressource "service de veille" attend une certaine condition de réussite ou d'échec avant de renvoyer une réponse. Vous devez définir une condition de cardinalité pour la réussite comme pour l'échec. Cela permet d'indiquer au service de veille qu'il doit attendre qu'un certain nombre de variables soient créées sous un préfixe de chemin spécifique. Une fois les variables créées, le service de veille retourne une réponse. Le code de votre application peut ensuite réagir au message de réussite ou d'échec renvoyé. Si l'état actuel de vos variables correspond déjà aux conditions de réussite ou d'échec, le service de veille renvoie immédiatement le message correspondant.

Avant de commencer

Créer un objet de type Service de veille (waiter)

Pour créer un service de veille :

  1. Déterminez la condition de réussite (et éventuellement la condition d'échec) pour le service de veille.

    Par exemple, l'échantillon de code ci-dessous définit les conditions de réussite et d'échec suivantes : le service de veille renvoie un message de réussite si le nombre de chemins sous /status/success est égal à trois et un message d'échec si le nombre de chemins sous /status/failure est égal à deux :

    {
    'name': 'projects/[PROJECT_ID]/configs/[CONFIG_NAME]/waiters/[WAITER_NAME]',
    'timeout': '360s',
    'success': {
       'cardinality': {
          'path': '/status/success',
          'number': 3
       }
    },
    'failure': {
       'cardinality': {
          'path': '/status/failure',
          'number': 2
       }
     }
}

    Bonnes pratiques pour la définition d'un service de veille :

    • Une seule condition de réussite et une seule condition d'échec sont autorisées par service de veille.
    • Il est préférable d'avoir un seul service de veille par chemin.
    • Les conditions d'échec doivent toujours être évaluées avant les conditions de réussite.
    • Prenez garde à ce que les préfixes de chemin ne se chevauchent pas entre les conditions.

  2. Créez le service de veille.

    Deployment Manager

    Pour créer un service de veille dans Deployment Manager, spécifiez le type "waiter" :

    runtimeconfig.v1beta1.waiter

    Dans les propriétés du service de veille, renseignez les champs name, location et timeout, ainsi que les conditions de fin du service :

    - name: [NAME]
  type: runtimeconfig.v1beta1.waiter
  properties:
    parent: $(ref.[CONFIG_NAME].name)
    waiter: [WAITER_NAME]
    timeout: [TIMEOUT_SECS]
    success:
      cardinality:
        path: [SUCCESS_PATH_PREFIX]
        number: [SUCCESS_NUMBER]

    où :

    • [NAME] est le nom de la ressource.
    • [CONFIG_NAME] est la ressource de configuration pour cette requête.
    • [WAITER_NAME] est le nom du service de veille.
    • [TIMEOUT_SECS] est le délai d'expiration (exprimé en secondes) du service de veille. Par exemple, pour 300 secondes, utilisez 300s.
    • [SUCCESS_PATH_PREFIX] est le préfixe de chemin à surveiller pour une condition de réussite.
    • [SUCCESS_NUMBER] est le nombre de variables qui doivent exister sous ce chemin pour que le service renvoie un message de réussite.

    gcloud

    Avec la Google Cloud CLI :

    gcloud beta runtime-config configs waiters create [WAITER_NAME] \
    --config-name [CONFIG_NAME] \
    --success-cardinality-path [SUCCESS_PATH_PREFIX] \
    --success-cardinality-number [SUCCESS_NUMBER] --timeout [TIMEOUT_SECS]

    où :

    • [WAITER_NAME] est le nom du service de veille.
    • [CONFIG_NAME] est la ressource RuntimeConfig pour cette requête.
    • [SUCCESS_PATH_PREFIX] est le préfixe de chemin à surveiller pour une condition de réussite.
    • [SUCCESS_NUMBER] est le nombre de variables qui doivent exister sous ce chemin pour que le service renvoie un message de réussite.

    • [TIMEOUT_SECS] est le délai d'expiration (exprimé en secondes) du service de veille.

      La gcloud CLI renvoie une réponse semblable à celle-ci:

      [https://runtimeconfig.googleapis.com/v1beta1/projects/[PROJECT_ID]/configs/[CONFIG_NAME]/waiters/example-waiter] créé.

      Une fois le service de veille créé, l'outil interroge la ressource Opérations associée jusqu'à ce que le service de veille retourne l'une des réponses applicables.

      Pour en savoir plus sur cette commande gcloud, consultez la documentation de référence sur runtime-config configs waiters.

    API

    Dans l'API, envoyez une demande POST à l'adresse URI suivante :

    https://runtimeconfig.googleapis.com/v1beta1/projects/[PROJECT_ID]/configs/[CONFIG_NAME]/waiters

    où :

    • [PROJECT_ID] est l'ID de projet de cette requête.
    • [CONFIG_NAME] est le nom de la configuration concernée par cette requête.

    La charge utile de la requête doit contenir le nom du service de veille, la condition de réussite et la durée du délai d'expiration :

    {
 'name': 'projects/[PROJECT_ID]/configs/[CONFIG_NAME]/waiters/[WAITER_NAME]',
 'timeout': '[TIMEOUT_SEC]',
 'success': {
    'cardinality': {
       'path': '[SUCCESS_PATH_PREFIX]',
       'number': '[SUCCESS_NUMBER]'
    }
  }
}

    où :

    • [PROJECT_ID] est l'ID de projet de cette requête.
    • [CONFIG_NAME] est le nom de la configuration concernée par cette requête.
    • [WAITER_NAME] est le nom du service de veille à créer.
    • [TIMEOUT_SECS] est le délai d'expiration (exprimé en secondes) du service de veille.
    • [SUCCESS_PATH_PREFIX] est le préfixe de chemin à surveiller pour une condition de réussite.
    • [SUCCESS_NUMBER] est le nombre de variables qui doivent exister sous ce chemin pour que le service renvoie un message de réussite.

    En cas de réussite, la requête renvoie le nom de l'objet Opérations dont vous interrogez l'exécution :

    {
    "name": "projects/[PROJECT_ID]/[CONFIG_NAME]/operations/waiters/[WAITER_NAME]"
}

    Ensuite, interrogez le service de veille régulièrement pour vous assurer qu'il renvoie des réponses.

    Pour en savoir plus sur la méthode, consultez la documentation sur waiters().create.

Interroger un service de veille

Après avoir créé un service de veille, interrogez la ressource Opérations associée pour vérifier si le service a rencontré l'une des conditions de fin. S'il a rencontré une condition de fin ou a expiré, l'opération passe à l'état done et renvoie une réponse en fonction des résultats du service de veille.

Utilisez gcloud ou l'API pour interroger un service de veille.

gcloud

Avec la Google Cloud CLI, lorsque vous demandez la création l'outil interroge automatiquement le serveur et attend que celui-ci retour. L'outil affiche un message de ce type lorsqu'il interroge le service de veille :

Waiting for waiter [WAITER_NAME] to finish...

Si vous ne souhaitez pas que l'outil interroge automatiquement le service de veille après l'avoir créé, ajoutez l'indicateur --async à votre requête de création.

API

Dans l'API REST, envoyez une requête GET à l'adresse URI suivante pour obtenir l'état de l'opération exécutée par le service de veille :

https://runtimeconfig.googleapis.com/v1beta1/projects/[PROJECT_ID]/configs/[CONFIG_NAME]/operations/waiters/[WAITER_NAME]

où :

  • [PROJECT_ID] est l'ID de projet de cette requête.
  • [CONFIG_NAME] est le nom de la configuration concernée par cette requête.
  • [WAITER_NAME] est le nom du service de veille à interroger.

Si l'opération est toujours en cours, l'API renvoie une réponse de ce type, sans préciser l'état de l'opération :

{
  "name": "projects/[PROJECT_NAME]/configs/[CONFIG_NAME]/operations/waiters/[WAITER_NAME]"
}

Si l'opération est achevée, elle est marquée comme done et renvoie l'une des réponses décrites à la section Réponses du service de veille.

Pour en savoir plus sur la méthode, consultez la documentation sur waiters().create.

Réponses du service de veille

Condition de fin "réussite"

Si le service de veille rencontre la condition de fin réussite, l'opération retourne la ressource Service de veille :

{
  "name": "projects/[PROJECT_NAME]/configs/[CONFIG_NAME]/operations/waiters/[WAITER_NAME]",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.runtimeconfig.v1beta1.Waiter",
    "name": "projects/[PROJECT_NAME]/configs/[CONFIG_NAME]/waiters/[WAITER_NAME]",
    "timeout": "360.000s",
    "failure": {
      "cardinality": {
        "path": "[SUCCESS_PATH_PREFIX]",
        "number": "[SUCCESS_NUMBER]"
      }
    },
    "success": {
      "cardinality": {
        "path": "[FAILURE_PATH_PREFIX]",
        "number": [FAILURE_NUMBER]
      }
    },
    "createTime": "2016-04-12T18:02:13.316695490Z",
    "done": true
  }
}

Condition de fin "échec"

Si le service de veille rencontre la condition de fin échec ou expire, l'opération renvoie une erreur.

La condition d'échec est remplie

{
  "name": "projects/[PROJECT_NAME]/configs/[CONFIG_NAME]/operations/waiters/[WAITER_NAME]",
  "done": true,
  "error": {
    "code": 9,
    "message": "Failure condition satisfied."
  }
}

Le service de veille a expiré

{
  "name": "projects/[PROJECT_NAME]/configs/[CONFIG_NAME]/operations/waiters/[WAITER_NAME]",
  "done": true,
  "error": {
    "code": 4,
    "message": "Timeout expired."
  }
}

Étapes suivantes