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 une requête au format approprié, l'autoriser en tant qu'utilisateur authentifié et traiter 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 correspondant à la requête dans Documentation de référence de l'API Datastream Chaque page a exemples d'appel de l'API dans plusieurs langages de programmation, ainsi qu'un un explorateur spécifique pour vous aider à comprendre ce qui compose une requête correctement formulée et à quoi vous attendre.

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

Ces méthodes présentent un avantage, en particulier la console Google Cloud, est qu'ils peuvent grandement simplifier l'administration de des configurations de connectivité privée, des profils de connexion et des flux (selon votre cas d'utilisation). Si vous débutez avec Datastream, nous vous recommandons de commencer par 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 commande ligne. Si vous travaillez avec des valeurs sensibles telles que des mots de passe ou des clés de sécurité, les fournir sur la ligne de commande présente un risque de sécurité. Pour une augmentation la sécurité, vous pouvez créer un fichier contenant les données JSON pour l'appel d'API, et indiquez 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 ce qui est entouré de guillemets simples pour le champ --data.

    Incluez les accolades, mais 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

Utiliser des appels d'API de longue durée

Certains appels d'API, comme la création d'objets, peuvent prendre un certain temps. En effet, l'API est 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 l'objet nouvellement créé, 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. Par exemple :

Datastream et service de découverte des API Google

Le service de découverte des API Google permet d'effectuer les tâches suivantes : pour 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).