Datastream API verwenden

Überblick

Datastream bietet eine REST API zur programmatischen Verwaltung von Konfigurationen privater Verbindungen, Verbindungsprofilen und Streams. Die REST API wird durch Ressourcen definiert, die mit dem Erstellen und Verwalten von Konfigurationen privater Verbindungen, Verbindungsprofilen und Streams verbunden sind. Weitere Informationen zu allen Ressourcen und zugehörigen Methoden finden Sie in der Referenz zur Datastream API.

Wenn Sie Anfragen direkt an die Datastream REST API senden, müssen Sie die richtige Form der Anfrage erstellen, die Anfrage als authentifizierten Nutzer autorisieren und alle zurückgegebenen Antworten verarbeiten. Viele Aufgaben in dieser Dokumentation enthalten API-Beispiele mit cURL.

Weitere Beispiele zur Verwendung der APIs finden Sie auf der Seite für die Anfrage in der Referenz zur Datastream API. Jede Seite enthält Beispiele zum Aufrufen der API in mehreren Programmiersprachen sowie einen anfragespezifischen Explorer, mit dem Sie sehen können, was in einer wohlgeformte Anfrage enthalten ist und was in der Antwort zu erwarten ist.

Sie nutzen die Datastream API auch indirekt, wenn Sie eine der folgenden Methoden zur Verwaltung von Instanzen nutzen:

Google Cloud CLI: Eine Befehlszeilenschnittstelle, die Sie für die Arbeit mit Ihren Instanzen verwenden können.
Google Cloud Console: Eine grafische Weboberfläche.

Der Vorteil dieser Methoden, insbesondere der Google Cloud Console, besteht darin, dass sie die Verwaltung Ihrer Konfigurationen für private Verbindungen, Verbindungsprofile und Streams je nach Anwendungsfall erheblich vereinfachen können. Wenn Sie noch nicht mit Datastream vertraut sind, sollten Sie zuerst eines dieser Tools verwenden, bevor Sie direkt mit der REST API arbeiten.

API aktivieren

Damit Sie die Datastream API verwenden können, müssen Sie sie aktivieren:

Console

Aktivieren Sie die Datastream API.
Wählen Sie Ihr Projekt aus.
Klicken Sie dann auf Weiter.

gcloud

Geben Sie Folgendes ein, um sich die Projekt-IDs für Ihre Google Cloud-Projekte anzeigen zu lassen:
```
gcloud projects list
```

Legen Sie ein Standardprojekt fest:

gcloud config set project YOUR_PROJECT_ID

Aktivieren Sie die Datastream API:

gcloud services enable datastream.googleapis.com

Berechtigungen

Sie müssen die erforderlichen Berechtigungen haben, um die Datastream API verwenden zu können. Zu diesen Berechtigungen gehören:

Datastream-Administrator: Mit dieser Berechtigung erhält ein Nutzer Zugriff auf alle Datastreams, die zum Verwalten von Konfigurationen privater Verbindungen, Verbindungsprofile und Streams verwendet werden.
Datastream-Betrachter: Mit dieser Berechtigung hat ein Nutzer Lesezugriff auf Konfigurationen von privaten Verbindungen, Verbindungsprofilen und Streams in Datastream.

Google Cloud bietet mit der Identitäts- und Zugriffsverwaltung (Identity and Access Management, IAM) die Möglichkeit, bestimmten Google Cloud-Ressourcen detaillierte Zugriffsrechte zuzuweisen und unerwünschten Zugriff auf andere Ressourcen zu verhindern. Sie können Berechtigungen für Datastream mit der Google Cloud Console, den IAM-Methoden der API oder dem Google Cloud SDK abrufen und festlegen. Weitere Informationen finden Sie unter Zugriff auf Ressourcen erteilen, ändern und entziehen.

API-Beispiele

Auf den folgenden Seiten der Datastream-Dokumentation finden Sie Beispiele für die Verwendung der Datastream API mit cURL:

JSON-Daten aus einer Datei bereitstellen

Wenn Sie die API mit cURL verwenden, geben Sie Eigenschaftswerte über die Befehlszeile an. Wenn Sie mit vertraulichen Werten wie Passwörtern oder Sicherheitsschlüsseln arbeiten, stellt die Eingabe dieser Werte in der Befehlszeile ein Sicherheitsrisiko dar. Zur Erhöhung der Sicherheit können Sie eine Datei mit den JSON-Daten für den API-Aufruf erstellen und den Pfad zur Datei in der Befehlszeile angeben.

So stellen Sie JSON-Daten für Ihren cURL API-Aufruf aus einer Datei bereit:

Erstellen Sie eine Datei, die alles enthält, was in einfachen Anführungszeichen für das Feld --data steht.

Verwenden Sie geschweifte Klammern, aber keine einfachen Anführungszeichen.

Geben Sie in der Befehlszeile den Pfad zur Datei mit dem vorangestellten @-Zeichen als --data-Parameter an:

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

Um beispielsweise ein Verbindungsprofil für eine MySQL-Quelle zu erstellen, können Sie eine Datei namens request.json mit folgendem Inhalt erstellen:

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

Dann verwenden Sie den folgenden cURL-Befehl in der Befehlszeile:

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

Mit lang andauernden API-Aufrufen arbeiten

Einige API-Aufrufe wie die Objekterstellung können einige Zeit in Anspruch nehmen. Da die API asynchron ist, wird der Aufruf sofort zurückgegeben, auch wenn der Vorgang noch läuft. Wenn ein nachfolgender API-Aufruf das neu erstellte Objekt verwendet, müssen Sie warten, bis der erste Vorgang abgeschlossen ist, bevor Sie fortfahren.

Mit der Datastream API können Sie Vorgänge verwalten. Dazu zählen:

Datastream und Google APIs Discovery Service

Google APIs Discovery Service ist ein Dienst, mit dem Sie Google APIs ermitteln können. Wenn Sie beispielsweise das Tool Google APIs Explorer verwenden, verwenden Sie den Discovery Service.

Im Discovery Service wird Datastream als „datastream“ dargestellt (z. B. https://datastream.googleapis.com/$discovery/rest?version=v1).