Messwertbereiche mit der API verwalten

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

Wenn Sie ein AWS-Konto mit dem Messwertumfang eines Google Cloud-Projekts verbinden möchten, müssen Sie die Google Cloud Console verwenden. Weitere Informationen finden Sie unter Messwerte für AWS-Konten ansehen.

Vor dem Start

  • Wenn Sie mit den Begriffen Umfang des Messwerts und Bereichsumfang nicht vertraut sind, lesen Sie Umfang der Messwerte.

  • Achten Sie darauf, dass die IAM-Rolle (Identity and Access Management) für das Bereichsprojekt den Messwertbereich des Projekts ändern kann.

  • Achten Sie darauf, dass Sie bei jedem Projekt, das Sie als überwachtes Projekt hinzufügen möchten, den Messwertbereich des Projekts ändern können. Informationen zu den erforderlichen IAM-Rollen finden Sie unter Konfigurationen des Messwertbereichs.

  • Die Methoden für den Umfang der Messwerte der Cloud Monitoring API, die Informationen abrufen, sind synchron Diese APIs, die den Status ändern, sind jedoch asynchron. Informationen dazu, wie Sie feststellen, wann eine asynchrone Methode abgeschlossen ist, und wie Sie ihren Status ermitteln können, finden Sie unter Asynchrone API-Methoden.

curl-Befehlsparameter

Sie können die APIs für Messwertbereiche direkt aufrufen. Auf dieser Seite finden Sie Beispielbefehle, die curl verwenden. 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 Bereichsprojekt eines Messwertbereichs.
  • MONITORED_PROJECT_ID_OR_NUMBER: Speichert die Projekt-ID oder Nummer eines Projekts, das einem Messwertbereich hinzugefügt oder daraus entfernt werden soll.

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, die für die Beispiele erforderlich ist, finden Sie unter curl-Befehl einrichten.

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}

Bei Erfolg ist die Antwort ein MetricsScope-Objekt.

Diese Methode führt nicht dazu, dass ein Eintrag in die Audit-Logs des Bereichs erstellt wird. Damit diese Aktionen im Audit-Log erfasst werden, aktivieren Sie Daten lesen für die Cloud Resource Manager API. Weitere Informationen finden Sie unter Audit-Logs zum Datenzugriff konfigurieren.

Alle Messwertbereiche mit einem Projekt auflisten

Wenn Sie eine Liste mit Messwertbereichen 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 die Abfrage hinzu. einen Parameter für das Projekt.

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

Bei Erfolg ist die Antwort ein Array von MetricsScope-Objekten.

Diese Methode führt nicht dazu, dass ein Eintrag in die Audit-Logs des Bereichs erstellt wird. Damit diese Aktionen im Audit-Log erfasst werden, aktivieren Sie Daten lesen für die Cloud Resource Manager API. Weitere Informationen finden Sie unter Audit-Logs zum Datenzugriff konfigurieren.

Projekt zu einem Messwertbereich hinzufügen

Wenn Sie ein Google Cloud-Projekt einem Messwertbereich hinzufügen möchten, senden Sie eine POST-Anfrage an den Endpunkt locations.global.metricsScopes.projects.create. 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 der Wert des Felds Operation.done true ist. Wenn das Feld Operation.done auf false gesetzt ist, zeigt der Vorgang an. Weitere Informationen finden Sie unter Asynchrone API-Befehle.

Das folgende Beispiel zeigt die Antwort beim Hinzufügen eines überwachten Projekts:

{
  "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 ein MonitoredProject-Objekt. Das Feld response.name enthält die Kennzeichnung des Bereichsprojekts und des überwachten Projekts. Das Feld providerAccountId enthält den Namen des überwachten Projekts.

Durch den Aufruf dieser Methode wird ein Eintrag in den Audit-Logs des Bereichs erstellt. Wenn Sie über die Cloud Console ein Projekt zu einem Messwertbereich hinzufügen, wird diese Aktion nicht in den Audit-Logs aufgezeichnet. Die Cloud Console ruft diese API-Methode nicht auf.

Projekt aus einem Messwertbereich entfernen

Senden Sie eine DELETE-Anfrage an den Endpunkt locations.global.metricsScopes.projects.delete, um ein Google Cloud-Projekt aus einem Messwertbereich zu entfernen:

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 der Wert des Felds Operation.done true ist. Wenn das Feld Operation.done auf false gesetzt ist, zeigt der Vorgang an. Weitere Informationen finden Sie unter Asynchrone API-Befehle.

Das folgende Beispiel zeigt die Antwort, wenn das überwachte Projekt erfolgreich entfernt wurde:

{
  "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.

Durch den Aufruf dieser Methode wird ein Eintrag in den Audit-Logs des Bereichs erstellt. Wenn Sie über die Cloud Console ein Projekt aus einem Messwertbereich entfernen, wird diese Aktion nicht in den Audit-Logs aufgezeichnet. Die Cloud Console ruft diese API-Methode nicht auf.

Asynchrone API-Methoden

Alle Methoden für den Umfang von Messwerten der Cloud Monitoring API, die den Systemstatus ändern, z. B. 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 der Wert des Felds Operation.done true ist:

  • Wenn done den Wert false hat, wird der Vorgang 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, in der der Wert des Felds Operation.name gespeichert wird.

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

    • error: Wenn dieser Wert 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 dieser Wert festgelegt ist, wurde der asynchrone Vorgang erfolgreich abgeschlossen und der Wert entspricht dem Ergebnis.

Einrichtung des Befehls curl

In diesem Abschnitt wird die Einrichtung beschrieben, die zum Erstellen der curl-Befehle in diesem Dokument verwendet wird.

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

  1. Erstellen Sie die Umgebungsvariable zum Speichern der Bereichs-Projekt-ID oder der Bereichsnummer:

    SCOPING_PROJECT_ID_OR_NUMBER=a-sample-project
    
  2. Optional. Wenn Sie überwachte Projekte hinzufügen oder entfernen möchten, 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 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....