Utilizzo dell'API Datastream

Panoramica

Datastream fornisce un'API REST per amministrare in modo programmatico le configurazioni di connettività privata, i profili di connessione e i flussi. L'API REST è definita dalle risorse associate alla creazione e alla gestione di configurazioni di connettività privata, profili di connessione e flussi. Per maggiori dettagli su tutte le risorse e i relativi metodi, consulta la documentazione di riferimento sull'API Datastream.

Quando invii le richieste direttamente all'API REST di Datastream, devi creare la forma corretta della richiesta, autorizzarla come utente autenticato ed elaborare le risposte restituite. Molte delle attività in questa documentazione forniscono esempi di API che utilizzano cURL.

Per altri esempi sull'utilizzo delle API, consulta la pagina relativa alla richiesta nel riferimento API Datastream. Ogni pagina include esempi di chiamata all'API in diversi linguaggi di programmazione, nonché un Explorer specifico per la richiesta per aiutarti a vedere cosa viene inserito in una richiesta ben strutturata e cosa aspettarti nella risposta.

Inoltre, utilizzi indirettamente l'API Datastream anche quando adotti uno dei seguenti modi per amministrare le istanze:

Google Cloud CLI: un'interfaccia a riga di comando (CLI) che puoi utilizzare per lavorare con le tue istanze.
Console Google Cloud: una Graphic User Interface.

Il vantaggio di utilizzare questi metodi, in particolare la console Google Cloud, è che possono semplificare notevolmente l'amministrazione delle configurazioni di connettività privata, dei profili di connessione e dei flussi (a seconda del caso d'uso). Se hai appena iniziato a utilizzare Datastream, ti consigliamo di iniziare con uno di questi strumenti prima di lavorare direttamente con l'API REST.

Abilita l'API

Per utilizzare l'API Datastream, devi abilitarla:

Console

Abilita l'API Datastream.
Seleziona il progetto.
Seleziona Continua.

gcloud

Inserisci quanto segue per visualizzare gli ID dei tuoi progetti Google Cloud:
```
gcloud projects list
```

Imposta il progetto predefinito:

gcloud config set project YOUR_PROJECT_ID

Abilita l'API Datastream:

gcloud services enable datastream.googleapis.com

Autorizzazioni

Devi disporre delle autorizzazioni necessarie per utilizzare l'API Datastream. Queste autorizzazioni includono:

Amministratore Datastream: con questa autorizzazione, un utente può accedere a tutte le risorse di Datastream utilizzate per gestire le configurazioni di connettività privata, i profili di connessione e gli stream.
Visualizzatore Datastream: con questa autorizzazione, un utente ha accesso di sola lettura alle configurazioni di connettività privata, ai profili di connessione e ai flussi di dati in Datastream.

Google Cloud offre Identity and Access Management (IAM), che consente di concedere un accesso più granulare a risorse Google Cloud specifiche e impedisce l'accesso indesiderato ad altre risorse. Puoi ottenere e impostare le autorizzazioni per Datastream utilizzando la Google Cloud Console, i metodi IAM dell'API o Google Cloud SDK. Per saperne di più, vedi Concessione, modifica e revoca dell'accesso alle risorse.

Esempi di API

Puoi vedere alcuni esempi di utilizzo dell'API Datastream con cURL nelle seguenti pagine della documentazione di Datastream:

Fornire dati JSON da un file

Quando utilizzi l'API con cURL, fornisci i valori delle proprietà utilizzando la riga di comando. Se utilizzi valori sensibili come password o token di sicurezza, fornirli nella riga di comando comporta un rischio per la sicurezza. Per maggiore sicurezza, puoi creare un file contenente i dati JSON per la chiamata API e fornire il percorso del file nella riga di comando.

Per fornire dati JSON alla tua chiamata API cURL da un file:

Crea un file contenente tutto ciò che è racchiuso tra virgolette singole per il campo --data.

Includi le parentesi graffe, ma non le virgolette singole.

Nella riga di comando, specifica il percorso del file, preceduto dal carattere @, come parametro --data:

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

Ad esempio, per creare un profilo di connessione per un'origine MySQL, puoi creare un file denominato request.json con i seguenti contenuti:

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

Quindi, devi utilizzare il seguente comando cURL nella riga di comando:

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

Utilizzo di chiamate API a lunga esecuzione

Il completamento di alcune chiamate API, ad esempio la creazione di oggetti, può richiedere del tempo. Poiché l'API è asincrona, la chiamata restituisce immediatamente, anche se l'operazione è ancora in corso. Se una chiamata API successiva utilizza l'oggetto appena creato, devi attendere il completamento della prima operazione prima di procedere.

Puoi utilizzare l'API Datastream per gestire le operazioni. Ciò include:

Datastream e Google API Discovery Service

Google APIs Discovery Service è un servizio che puoi utilizzare per scoprire le API di Google. Ad esempio, se utilizzi lo strumento Explorer API di Google , usi il servizio Discovery.

In Discovery Service, Datastream è rappresentato come "datastream" (ad esempio: https://datastream.googleapis.com/$discovery/rest?version=v1).