Messwertbereiche mit der API verwalten

In diesem Dokument wird beschrieben, wie Sie mit den Messwertbereichsmethoden in der Cloud Monitoring API den Messwertbereich eines Google Cloud-Projekts verwalten. Diese Seite richtet sich an Entwickler und Systemadministratoren.

Zum Verbinden eines AWS-Kontos mit dem Messwertbereich eines Google Cloud-Projekts müssen Sie die Google Cloud Console verwenden. Weitere Informationen finden Sie unter Messwerte für AWS-Konten ansehen.

Hinweis

  • Wenn Sie mit den Begriffen Messwertumfang und den Umfang festlegendes Projekt nicht vertraut sind, lesen Sie den Abschnitt Messwertbereiche.

  • Achten Sie darauf, dass Sie mit Ihrer IAM-Rolle (Identity and Access Management) für das den Umfang festlegendes Projekt den Messwertbereich des Projekts ändern können.

  • Für jedes Projekt, das Sie als überwachtes Projekt hinzufügen möchten, muss Ihre IAM-Rolle den Messwertbereich des Projekts ändern können. Informationen zu den erforderlichen IAM-Rollen finden Sie unter Messwertbereichskonfiguration.

  • Die Messwertbereichsmethoden der Cloud Monitoring API, die Informationen abrufen, sind synchron. APIs, die den Zustand ändern, sind jedoch asynchron. Informationen dazu, wie Sie feststellen, wann eine asynchrone Methode abgeschlossen ist, und wie Sie ihren Status ermitteln, finden Sie unter Asynchrone API-Methoden.

  • Informationen zur Verwendung von Google Cloud mit Terraform finden Sie in den folgenden Ressourcen:

curl-Befehlsparameter

Sie können die APIs für Messwertbereiche direkt aufrufen. Auf dieser Seite finden Sie Beispielbefehle mit curl. Jeder curl-Befehl enthält eine Reihe von Argumenten, gefolgt von der URL einer API-Ressource:

curl -H "Authorization: Bearer ${TOKEN}" <other_args> \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/<resource>

Die Beispiele auf dieser Seite basieren auf den folgenden Umgebungsvariablen:

  • TOKEN: Speichert das Authentifizierungstoken.
  • SCOPING_PROJECT_ID_OR_NUMBER: Speichert die Projekt-ID oder Nummer für ein den Umfang festlegendes Projekt eines Messwertbereichs.
  • MONITORED_PROJECT_ID_OR_NUMBER: Speichert die Projekt-ID oder Nummer eines Projekts, das einem Messwertbereich hinzugefügt oder aus diesem entfernt wird.

Möglicherweise müssen Sie auch andere Argumente angeben, um beispielsweise den Typ der HTTP-Anfrage anzugeben (z. B. -X DELETE). Die Standardanfrage ist GET. Daher wird sie in den Beispielen nicht angegeben.

Informationen zur Einrichtung für die Beispiele finden Sie unter Einrichtung des curl-Befehls.

Messwertbereich abrufen

Wenn Sie Informationen zu einem Messwertbereich abrufen möchten, senden Sie eine GET-Anfrage an den Endpunkt locations.global.metricsScopes.get:

curl -H "Authorization: Bearer ${TOKEN}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}

Wenn der Vorgang erfolgreich abgeschlossen wurde, ist die Antwort ein MetricsScope-Objekt.

Diese Methode führt nicht dazu, dass ein Eintrag in die Audit-Logs des den Bereich festlegenden Projekts geschrieben wird. Damit diese Aktionen im Audit-Log aufgezeichnet werden, aktivieren Sie Datenlesevorgänge für die Cloud Resource Manager API. Weitere Informationen finden Sie unter Audit-Logs zum Datenzugriff konfigurieren.

Alle Messwertbereiche auflisten, die ein Projekt enthalten

Wenn Sie eine Liste der Messwertbereiche abrufen möchten, die die Messwerte für ein Projekt aufrufen können, senden Sie eine GET-Anfrage an den Endpunkt locations.global.metricsScopes.listMetricsScopesByMonitoredProject und fügen Sie den Abfrage-Parameter ein, der das Projekt angibt.

curl -H "Authorization: Bearer ${TOKEN}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes:listMetricsScopesByMonitoredProject?monitored_resource_container=projects/${PROJECT_ID_OR_NUMBER}

Wenn der Vorgang erfolgreich abgeschlossen wurde, ist die Antwort ein Array von MetricsScope-Objekten.

Diese Methode führt nicht dazu, dass ein Eintrag in die Audit-Logs des den Bereich festlegenden Projekts geschrieben wird. Damit diese Aktionen im Audit-Log aufgezeichnet werden, aktivieren Sie Datenlesevorgänge für die Cloud Resource Manager API. Weitere Informationen finden Sie unter Audit-Logs zum Datenzugriff konfigurieren.

Projekt einem Messwertbereich hinzufügen

Senden Sie eine POST-Anfrage an den Endpunkt locations.global.metricsScopes.projects.create, um ein Google Cloud-Projekt zu einem Messwertbereich hinzuzufügen. Im folgenden Beispiel wird das durch die Umgebungsvariable MONITORED_PROJECT_ID_OR_NUMBER identifizierte Projekt als überwachtes Projekt hinzugefügt:

curl -H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" -X POST \
-d "{'name': 'locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects/${MONITORED_PROJECT_ID_OR_NUMBER}'}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects

Die Antwort dieser asynchronen Methode ist ein Operation-Objekt.

Anwendungen, die diese Methode aufrufen, sollten den Endpunkt operation.get abfragen, bis das Feld Operation.done den Wert true hat. Wenn das Feld Operation.done auf false gesetzt ist, bedeutet dies, dass der Vorgang läuft. Weitere Informationen finden Sie unter Asynchrone API-Befehle.

Das folgende Beispiel zeigt die Antwort wenn das Hinzufügen eines überwachten Projekts erfolgreich:

{
  "name": "operations/6915efde-1915-400a-ad49-7b62041d9bd2",
  "metadata": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.OperationMetadata",
    "state": "DONE",
    ...
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.MonitoredProject",
    "name": "locations/global/metricsScopes/012012012012/projects/678678678678",
    "provider": "GCP",
    "providerAccountId": "...",
    ...
  }
}

In der vorherigen Antwort ist das Feld Operation.done auf true gesetzt. Dieser Wert gibt an, dass der Befehl abgeschlossen ist. Da der Befehl erfolgreich ausgeführt wurde, wird das Feld Operation.response festgelegt und sein Wert ist ein MonitoredProject-Objekt. Das Feld response.name enthält die ID des den Bereich festlegenden überwachten Projekts. Im Feld providerAccountId ist der Name des überwachten Projekts aufgeführt.

Der Aufruf dieser Methode führt zu einem Eintrag in den Audit-Logs des den Bereich festlegenden Projekts. Diese API-Methode wird von der Cloud Console nicht aufgerufen. Daher werden Änderungen an einem Messwertbereich, wenn Sie die Google Cloud Console verwenden, nicht in den Audit-Logs aufgezeichnet.

Projekt aus einem Messwertbereich entfernen

Senden Sie zum Entfernen eines Google Cloud-Projekts aus einem Messwertbereich eine DELETE-Anfrage an den Endpunkt locations.global.metricsScopes.projects.delete:

curl -H "Authorization: Bearer ${TOKEN}" -X DELETE \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects/${MONITORED_PROJECT_ID_OR_NUMBER}

Die Antwort auf diese asynchrone Methode ist ein Operation-Objekt.

Anwendungen, die diese Methode aufrufen, sollten den Endpunkt operation.get abfragen, bis das Feld Operation.done den Wert true hat. Wenn das Feld Operation.done auf false gesetzt ist, bedeutet dies, dass der Vorgang läuft. Weitere Informationen finden Sie unter Asynchrone API-Befehle.

Das folgende Beispiel zeigt die Antwort bei erfolgreicher Entfernung eines überwachten Projekts:

{
  "name": "operations/4367ff34-0ff0-4767-b8d3-0638e30f077c",
  "metadata": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.OperationMetadata",
    "state": "DONE",
    ...
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.protobuf.Empty"
  }
}

In der vorherigen Antwort ist das Feld Operation.done auf true gesetzt. Dieser Wert gibt an, dass der Befehl abgeschlossen ist. Da der Befehl erfolgreich ausgeführt wurde, ist das Feld Operation.response festgelegt und enthält das Feld @type.

Der Aufruf dieser Methode führt zu einem Eintrag in den Audit-Logs des den Bereich festlegenden Projekts. Diese API-Methode wird von der Cloud Console nicht aufgerufen. Daher werden Änderungen an einem Messwertbereich, wenn Sie die Google Cloud Console verwenden, nicht in den Audit-Logs aufgezeichnet.

Asynchrone API-Methoden

Alle Messwertbereichsmethoden der Cloud Monitoring API, die den Systemzustand ändern, beispielsweise der Befehl zum Hinzufügen eines überwachten Projekts zu einem Messwertbereich, sind asynchron. Bei diesen Befehlen ist die Befehlsantwort ein Operation-Objekt.

Anwendungen, die eine asynchrone API-Methode aufrufen, sollten den Endpunkt operation.get abfragen, bis das Feld Operation.done den Wert true hat:

  • Wenn done den Wert false hat, wird der Vorgang noch ausgeführt.

    Senden Sie zum Aktualisieren der Statusinformationen eine GET-Anfrage an den Endpunkt operation.get:

    curl -H "Authorization: Bearer ${TOKEN}" \
    https://monitoring.googleapis.com/v1/${OPERATION_NAME}
    

    Im vorherigen Befehl ist OPERATION_NAME eine Umgebungsvariable, die den Wert des Felds Operation.name speichert.

  • Wenn done den Wert true hat, ist der Vorgang abgeschlossen und entweder das Feld error oder response ist festgelegt:

    • error: Wenn dies festgelegt ist, ist der asynchrone Vorgang fehlgeschlagen. Der Wert dieses Felds ist ein Status-Objekt, das einen gRPC-Fehlercode und eine Fehlermeldung enthält.
    • response: Wenn dies festgelegt ist, wurde der asynchrone Vorgang erfolgreich abgeschlossen und der Wert spiegelt das Ergebnis wider.

Einrichtung des curl-Befehls

In diesem Abschnitt wird die Einrichtung beschrieben, mit der die curl-Befehle in diesem Dokument erstellt wurden.

Legen Sie die folgenden Umgebungsvariablen fest, um die Erstellung der curl-Befehle zu vereinfachen:

  1. Erstellen Sie die Umgebungsvariable, um die ID oder Nummer des den Umfang festlegenden Projekts zu speichern:

    SCOPING_PROJECT_ID_OR_NUMBER=a-sample-project
    
  2. Optional. Wenn Sie beabsichtigen, überwachte Projekte hinzuzufügen oder zu entfernen, konfigurieren Sie die Umgebungsvariable mit der ID oder Nummer des überwachten Projekts:

    MONITORED_PROJECT_ID_OR_NUMBER=a-monitored-project
    
  3. Authentifizieren Sie sich beim Cloud SDK:

    gcloud auth login
    
  4. Optional Damit Sie nicht bei jedem gcloud-Befehl Ihre Projekt-ID angeben müssen, legen Sie Ihre Projekt-ID mithilfe des Cloud SDK als Standard fest:

    gcloud config set project ${SCOPING_PROJECT_ID_OR_NUMBER}
    
  5. Erstellen Sie ein Autorisierungstoken und erfassen Sie es in einer Umgebungsvariablen.

    TOKEN=`gcloud auth print-access-token`
    

    Tokens sind für eine begrenzte Zeit gültig. Wenn zuvor funktionierende Befehle plötzlich melden, dass Sie nicht authentifiziert sind, führen Sie diesen Befehl noch einmal aus.

  6. Bestätigen Sie, dass Sie ein Zugriffstoken erhalten haben. Geben Sie dazu die Variable TOKEN zurück:

    echo ${TOKEN}
    ya29.GluiBj8o....