Utiliser l'API Datastream

Présentation

Datastream fournit une API REST qui vous permet d'administrer vos configurations de connectivité privée, vos profils de connexion et vos flux de manière automatisée. L'API REST est définie par les ressources associées à la création et à la gestion de configurations de connectivité, de profils de connexion et de flux privés. Pour en savoir plus sur toutes les ressources et leurs méthodes, consultez la documentation de référence de l'API Datastream.

Lorsque vous envoyez des requêtes directement à l'API REST Datastream, vous devez créer le formulaire approprié, autoriser la requête en tant qu'utilisateur authentifié et traiter toutes les réponses renvoyées. De nombreuses tâches de cette documentation fournissent des exemples d'API utilisant cURL.

Pour plus d'exemples d'utilisation des API, consultez la page de la requête dans la documentation de référence de l'API Datastream. Chaque page contient des exemples d'appels de l'API dans plusieurs langages de programmation, ainsi qu'un explorateur spécifique à la requête pour vous aider à déterminer le contenu d'une requête correctement formulée et le résultat de la réponse.

Vous utilisez également l'API Datastream, indirectement, lorsque vous utilisez l'une des méthodes suivantes d'administration des instances :

Ces méthodes, en particulier la console Google Cloud, présentent l'avantage de simplifier considérablement l'administration de vos configurations de connectivité privée, de vos profils de connexion et de vos flux (selon votre cas d'utilisation). Si vous débutez avec Datastream, nous vous recommandons de commencer avec l'un de ces outils avant de travailler directement avec l'API REST.

Activer l'API

Pour utiliser l'API Datastream, vous devez l'activer :

Console

  1. Activez l'API Datastream.
  2. Sélectionnez votre projet.
  3. Cliquez sur Continuer.

gcloud

  1. Saisissez la commande suivante pour afficher les ID de vos projets Google Cloud :
    gcloud projects list
  2. Définissez le projet par défaut :
    gcloud config set project YOUR_PROJECT_ID
  3. Activez l'API Datastream :
    gcloud services enable datastream.googleapis.com

Autorisations

Vous devez disposer des autorisations requises pour utiliser l'API Datastream. Ces autorisations incluent:

  • Administrateur Datastream : avec cette autorisation, un utilisateur a accès à toutes les ressources de Datastream utilisées pour gérer les configurations de connectivité privée, les profils de connexion et les flux.
  • Lecteur DataStream : avec cette autorisation, un utilisateur dispose d'un accès en lecture seule aux configurations de connectivité privée, aux profils de connexion et aux flux dans Datastream.

Google Cloud propose Identity and Access Management (IAM), qui vous permet de définir de manière plus précise l'accès à des ressources spécifiques de Google Cloud et d'empêcher tout accès indésirable à d'autres ressources. Vous pouvez obtenir et définir des autorisations pour Datastream à l'aide de la Google Cloud Console, des méthodes IAM de l'API ou de Google Cloud SDK. Pour en savoir plus, consultez la page Accorder, modifier et révoquer les accès à des ressources.

Exemples d'API

Vous trouverez des exemples d'utilisation de l'API Datastream avec cURL sur les pages suivantes de la documentation Datastream :

Fournir des données JSON à partir d'un fichier

Lorsque vous utilisez l'API avec cURL, vous fournissez des valeurs de propriété à l'aide de la ligne de commande. Si vous utilisez des valeurs sensibles telles que des mots de passe ou des clés de sécurité, les fournir via la ligne de commande présente un risque de sécurité. Pour plus de sécurité, vous pouvez créer un fichier contenant les données JSON pour l'appel d'API et fournir le chemin d'accès au fichier dans la ligne de commande.

Pour fournir des données JSON à votre appel d'API cURL à partir d'un fichier :

  1. Créez un fichier contenant tout le contenu du champ --data entre guillemets simples.

    Incluez les accolades, mais n'incluez pas les guillemets simples.

  2. Sur la ligne de commande, indiquez le chemin d'accès au fichier, précédé du caractère @, en tant que paramètre --data :

    --data @<path-to-file>/<filename>
    

    Par exemple, pour créer un profil de connexion pour une source MySQL, vous pouvez créer un fichier nommé request.json avec le contenu suivant :

    {
      "displayName": "my MySQL connection profile",
      "mysql": {
        "host": "10.11.12.13",
        "port": 3306,
        "username": "myusername",
        "password": "mypassword"
      }
    }
    

    Vous devez ensuite utiliser la commande cURL suivante sur la ligne de commande :

    curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
         --header 'Content-Type: application/json' \
         --data @./request.json \
         -X POST \
         https://datastream.googleapis.com/v1/projects/myProject/locations/myLocation/connectionProfiles?connectionProfileId=myMySQLconnectionprofile
    

Travailler avec des appels d'API de longue durée

Certains appels d'API, tels que la création d'objets, peuvent prendre un certain temps. L'API étant asynchrone, l'appel est immédiatement renvoyé, même si l'opération est toujours en cours. Si un appel d'API ultérieur utilise le nouvel objet, vous devez attendre la fin de la première opération avant de continuer.

Vous pouvez utiliser l'API Datastream pour gérer les opérations. Ce bloc inclut les éléments suivants :

Datastream et le service de découverte des API Google

Le service de découverte des API Google vous permet de découvrir les API Google. Par exemple, lorsque vous utilisez l'outil Google APIs Explorer , vous utilisez le service de découverte.

Dans le service de découverte, Datastream est représenté par "datastream" (par exempl : https://datastream.googleapis.com/$discovery/rest?version=v1).