APIs Explorer verwenden

In dieser Anleitung wird beschrieben, wie Sie mit APIs Explorer die Methoden der Cloud Monitoring API testen. APIs Explorer ist ein Widget, das an die REST API-Referenzseite für eine Methode angehängt ist. Es wird als Steuerfeld mit dem Titel API testen angezeigt. Der folgende Screenshot zeigt das Steuerfeld wie für eine Methode mit nur einem Parameter, Name, angezeigt wird:

Das APIs Explorer-Widget.

Der APIs Explorer ist eine hervorragende Möglichkeit, Methoden in der Cloud Monitoring API auszuprobieren, ohne Code schreiben zu müssen. Das Widget zeigt ein Formular mit den Parametern für jede Methode an. Füllen Sie das Formular aus, klicken Sie auf die Schaltfläche Ausführen und sehen Sie sich die Ergebnisse an.

Um das Widget auszublenden, klicken Sie auf die Schaltfläche , oder maximieren Sie das Widget auf den Vollbildmodus, indem Sie auf klicken.

Probieren Sie die Schaltflächen aus!

In der Dokumentation werden möglicherweise Schaltflächen Jetzt testen wie diese angezeigt:

Jetzt testen

Wenn Sie auf die Schaltfläche klicken, wird der APIs Explorer auf der Referenzseite der Methode geöffnet. In der Regel werden einige für das Beispiel geeignete Parameter ausgefüllt. Sie müssen jedoch möglicherweise einige Parameter bearbeiten, damit sie Ihrem eigenen Projekt entsprechen, z. B. den Wert für [PROJECT_ID].

Informationen zur Vermeidung und Behebung von Fehlern finden Sie unter Fehlerbehebung.

APIs Explorer aufrufen

Der APIs Explorer ist an die Referenzseite für jede REST API-Methode angehängt. Das Widget finden Sie auf der Referenzseite für eine Methode, z. B. metricDescriptors.list.

Anfrage ausführen

Die meisten Methoden haben einige erforderliche und einige optionale Parameter. Die erforderlichen sind mit einem roten Balken markiert, bis sie ausgefüllt sind. Sie können eine Anfrage ausführen, nachdem Sie Werte für alle erforderlichen Argumente angegeben haben.

Die Methode metricDescriptors.list gibt Deskriptoren für alle verfügbaren Messwerttypen in einem Projekt zurück. Der einzige erforderliche Parameter ist der Parameter name.

So führen Sie die Methode metricDescriptors.list aus:

  1. Klicken Sie auf Jetzt testen.
  2. Geben Sie im Parameter name die ID Ihres Projekts im Format projects/[PROJECT_ID] ein. Ersetzen Sie dabei [PROJECT_ID] durch die ID Ihres Projekts.
  3. Klicken Sie auf Ausführen. Zum Ausführen des Befehls benötigt APIs Explorer Zugriff auf Ihr Konto. Wenn Sie dazu aufgefordert werden, wählen Sie ein Konto aus und klicken Sie auf Zulassen. Der Zugriff gilt für einen begrenzten Zeitraum und ist auf die API-Methode beschränkt, die Sie ausführen.

Die Ergebnisse des Methodenaufrufs werden in einem Feld mit grünem oder rotem Header angezeigt. Wenn die Anfrage erfolgreich ist, enthält das Feld einen grünen Header mit dem HTTP-Statuscode 200. Die Ergebnisse des Aufrufs befinden sich im Feld:

Das Ergebnis eines erfolgreichen Methodenaufrufs.

Wenn der Header rot ist, enthält er einen HTTP-Fehlercode und das Feld enthält die Fehlermeldung. Informationen zum Beheben von Fehlern finden Sie unter Fehlerbehebung.

Zusätzliche Parameter angeben

Die Liste der angezeigten Parameter hängt von der Methode ab, an die das APIs Explorer-Widget angehängt ist. Die Methode metricDescriptors.list hat beispielsweise mehr als den Parameter name, aber name ist der einzige erforderliche Parameter.

Wenn Sie nur den Projektnamen angeben, erhalten Sie alle Messwertdeskriptoren, die in Ihrem Projekt verfügbar sind, und es gibt viele. Verwenden Sie den Parameter filter, um den Abruf auf einen kleineren Satz zu beschränken.

So listen Sie beispielsweise nur die Messwerttypen auf, deren Name mit utilization endet:

  1. Klicken Sie auf Jetzt testen.

  2. Geben Sie im Parameter name die ID Ihres Projekts im Format projects/[PROJECT_ID] ein. Ersetzen Sie dabei [PROJECT_ID] durch die ID Ihres Projekts.

  3. Der Parameter filter muss den Wert metric.type=ends_with("utilization") haben.

  4. Klicken Sie auf Ausführen und füllen Sie die Autorisierungsdialogfelder aus.

Standardparameter

Standardmäßig entspricht der von APIs Explorer angezeigte Satz von Parametern den Parametern der zugehörigen Methode. Das APIs Explorer-Widget verfügt jedoch auch über eine Reihe zusätzlicher Parameter, die nicht Teil der Methode selbst sind. Klicken Sie auf Standardparameter anzeigen, um die zusätzlichen Parameter aufzurufen:

Schalter „Standardparameter anzeigen“

Klicken Sie auf Standardparameter ausblenden, um die zusätzlichen Parameter aus der Anzeige auszublenden.

Der nützlichste Standardparameter ist der Parameter fields. Mit diesem Parameter können Sie die Felder in der zurückgegebenen Ausgabe auswählen, die Sie sehen möchten.

Wenn Sie beispielsweise die Deskriptoren für Messwerte auflisten, die mit utilization enden, erhalten Sie dennoch viele Ergebnisse. Wenn Sie nur den Namen des Messwerttyps und seine Beschreibung wissen möchten, können Sie diese Einschränkung mit dem Parameter fields angeben.

So sehen Sie das Ergebnis des Festlegens des Parameters fields:

  1. Klicken Sie auf Jetzt testen.

  2. Geben Sie im Parameter name die ID Ihres Projekts im Format projects/[PROJECT_ID] ein. Ersetzen Sie dabei [PROJECT_ID] durch die ID Ihres Projekts.

  3. Der Parameter filter muss den Wert metric.type=ends_with("utilization") haben.

  4. Klicken Sie auf Standardparameter anzeigen und prüfen Sie, ob der Parameter fields den Wert metricDescriptors.type,metricDescriptors.description enthält.

  5. Klicken Sie auf Ausführen und füllen Sie die Autorisierungsdialogfelder aus.

Bei der Ausführung dieser Anfrage wird nur der type (Kurzname) jedes Messwerts und dessen description zurückgegeben.

Fehlerbehebung

In diesem Abschnitt werden häufige Probleme bei der Verwendung von APIs Explorer beschrieben.

Weitere Informationen zur Verwendung der Cloud Monitoring API finden Sie unter Fehlerbehebung bei der Cloud Monitoring API.

Ungültige Filtersyntax

Sie kopieren einen mehrzeiligen Ausdruck und fügen ihn in ein Feld im APIs Explorer ein. Daraufhin wird eine Fehlermeldung angezeigt.

Empfohlen: Achten Sie darauf, dass Strings in einer einzigen Zeile stehen.

"query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | within 5m"

Nicht: Kopieren und Einfügen von Zeichen für Zeilenfortsetzungen oder Zeilenumbrüche.

Wenn Sie der Methode timeSeries.query beispielsweise Folgendes hinzufügen, wird im APIs Explorer die Fehlermeldung Select an underlined section to see more details angezeigt:

"query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count
          | within 5m"

Ungültige Projekt-ID

Wenn die Projekt-ID ungültig ist, schlägt die API-Anfrage mit dem HTTP-Fehler 400 fehl.

Um dieses Problem zu beheben, prüfen Sie, ob der Text [PROJECT_ID] durch die ID Ihres Projekts ersetzt wurde.

Ungültige Formularwerte

Wenn Ihre API-Anfrage fehlschlägt oder unerwartete Werte zurückgibt, prüfen Sie alle Formularparameter.

Die APIs Explorer-Parameter erfordern eine bestimmte Formatierung. Formatierungsfehler können andere Fehler verursachen oder können akzeptiert, aber wie Rechtschreibfehler in der API-Methode behandelt werden:

  • Verwenden Sie keine Anführungszeichen um Parameterwerte herum.

  • Verwenden Sie keine umgekehrten Schrägstriche, es sei denn, Sie müssen einen Teilstring schützen.

    Das folgende Beispiel bezieht sich beispielsweise auf eine API-Methode, bei der Sie den Inhalt als JSON eingeben, anstatt einzelne Formularparameter auszufüllen. Da der Wert für filter ein String ist, wird der Teilstring k8s_cluster durch umgekehrte Schrägstriche geschützt:

    {
      "resourceNames": [...],
      "filter": "resource.type = \"k8s_cluster\""
    }
  • Strings in Anführungszeichen werden in Filtern angezeigt. Verwenden Sie doppelte (") und keine einfachen Anführungszeichen ('). Ein Beispiel finden Sie unter Zusätzliche Parameter bereitstellen.
  • Verwenden Sie im Formular keine URL-Codierung. Wenn für eine API-Methode eine URL-Codierung erforderlich ist, führt das Widget die Konvertierung durch, wenn Sie die Methode ausführen.

Es werden zu viele Daten zurückgegeben

Wenn Sie die Anzahl der zurückgegebenen Ergebnisse begrenzen möchten, geben Sie im Parameter pageSize einen Wert wie 2 ein. Der Parameter pageSize definiert die maximale Anzahl von zurückgegebenen Ergebnissen und ist für die meisten API-Methoden verfügbar.

Verwenden Sie den Parameter fields, um bestimmte Felder zurückzugeben. Weitere Informationen finden Sie unter Standardparameter.

Authentifizierung

Auf der Seite „APIs Explorer“ gibt es den Abschnitt Anmeldedaten. Wir empfehlen, für diese Felder die Standardwerte beizubehalten. Der Standardauthentifizierungsmechanismus ist Google OAuth 2.0.

Klicken Sie auf Bereiche anzeigen, um herauszufinden, welche API-Bereiche für die Methode erforderlich sind. Standardmäßig werden alle erforderlichen Bereiche gewährt.

Weitere Informationen zu diesen Konzepten finden Sie unter Zugriff mit Identity and Access Management steuern.