Utiliser l'API Datastream

Présentation

Datastream fournit une API REST pour 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é privée, de profils de connexion et de flux. 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 la forme correcte de la requête, autoriser la requête en tant qu'utilisateur authentifié et traiter les réponses renvoyées. La plupart des tâches de cette documentation fournissent des exemples d'API via 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 appelant l'API dans plusieurs langages de programmation, ainsi qu'un explorateur spécifique à une requête pour vous aider à comprendre ce qu'est une requête bien formée et à savoir à quoi vous attendre dans la réponse.

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

  • SDK Cloud : interface de ligne de commande (CLI) qui vous permet de travailler avec vos instances.

  • Google Cloud Console : interface Web graphique.

L'avantage de ces méthodes, en particulier de Google Cloud Console, est qu'elles peuvent considérablement simplifier 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 par utiliser 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 les suivantes :

  • 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 Google Cloud Console, des méthodes IAM de l'API ou du SDK Google Cloud. 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 spécifier sur la ligne de commande présente un risque en termes de sécurité. Pour renforcer la 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 sur 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 texte entre guillemets simples pour le champ --data.

    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. Étant donné que l'API est asynchrone, l'appel renvoie immédiatement une réponse, même si l'opération est toujours en cours. Si un appel d'API ultérieur utilise l'objet nouvellement créé, vous devez attendre que la première opération se termine avant de continuer.

Vous pouvez utiliser l'API Datastream pour gérer les opérations. Par exemple :

Datastream et 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).