APIs Explorer verwenden

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

APIs Explorer-Widget

APIs Explorer ist eine hervorragende Möglichkeit, um Methoden in der Cloud Monitoring API auszuprobieren, ohne Code zu schreiben. 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.

Du kannst das Widget auch ausblenden, indem du auf die Schaltfläche klickst. Wenn du das Widget im Vollbildmodus öffnen möchtest, klicke auf die Schaltfläche .

Probieren Sie die Schaltflächen aus!

Die Dokumentation enthält möglicherweise Schaltflächen wie Jetzt testen, die in etwa so aussehen:

Jetzt ausprobieren

Wenn Sie auf die Schaltfläche klicken, wird der APIs Explorer auf der Referenzseite der Methode geöffnet. In der Regel werden einige Parameter aus dem Beispiel übernommen. Unter Umständen müssen Sie jedoch einige Parameter bearbeiten, damit sie mit Ihrem eigenen Projekt übereinstimmen, z. B. der Wert für [PROJECT_ID].

Informationen zum Vermeiden und Beheben von Fehlern finden Sie unter Fehlerbehebung.

APIs Explorer aufrufen

Der APIs Explorer ist für jede REST API-Methode an die Referenzseite angehängt. Informationen zum Suchen des Widgets finden Sie auf der Referenzseite für eine Methode, wie beispielsweise 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 Projekt-ID im Format projects/[PROJECT_ID] ein. Ersetzen Sie dabei [PROJECT_ID] durch die ID Ihres Projekts.
  3. Klicken Sie auf Ausführen. Damit der Befehl ausgeführt werden kann, 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 ist für einen begrenzten Zeitraum und auf die API-Methode beschränkt, die Sie ausführen.

Die Ergebnisse des Methodenaufrufs werden in einem Feld mit einem grünen oder roten Header angezeigt. Wenn die Anfrage erfolgreich ist, enthält das Feld einen grünen Header mit dem HTTP-Statuscode 200. Das Ergebnis des Aufrufs befindet 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 Parameter hängt von der Methode ab, mit der das APIs Explorer-Widget verknüpft 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 im Projekt verfügbaren Messwertdeskriptoren, von denen es viele gibt. 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 Projekt-ID im Format projects/[PROJECT_ID] ein. Ersetzen Sie dabei [PROJECT_ID] durch die ID Ihres Projekts.

  3. Achten Sie darauf, dass der Parameter filter den Wert metric.type=ends_with("utilization") hat.

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

Standardparameter

Standardmäßig entspricht der Satz von Parametern, die APIs Explorer zeigt, 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 anzuzeigen:

"Standardparameter anzeigen".

Klicken Sie auf Standardparameter ausblenden, um die zusätzlichen Parameter 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 enden, die auf utilization enden, werden weiterhin viele Ergebnisse zurückgegeben. Wenn Sie nur den Namen des Messwerttyps und seine Beschreibung kennen möchten, können Sie diese Einschränkung mit dem Parameter fields festlegen.

So sehen Sie sich das Ergebnis der Einstellung des Parameters fields an:

  1. Klicken Sie auf Jetzt testen.

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

  3. Achten Sie darauf, dass der Parameter filter den Wert metric.type=ends_with("utilization") hat.

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

  5. Klicken Sie auf Ausführen und führen 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 Projekt-ID

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

Prüfen Sie zur Behebung dieser Bedingung, ob der Text [PROJECT_ID] durch die ID Ihres Projekts ersetzt wurde.

Ungültige Formularwerte

Wenn die API-Anfrage fehlschlägt oder unerwartete Werte zurückgegeben werden, prüfen Sie alle Formularparameter.

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

  • Setzen Sie Parameterwerte nicht in Anführungszeichen.
  • Verwenden Sie keine umgekehrten Schrägstriche, außer wenn Sie einen Teilstring schützen müssen.

    Das folgende Beispiel zeigt beispielsweise 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 Anführungszeichen (") und keine Apostrophe ('). Ein Beispiel finden Sie unter Zusätzliche Parameter bereitstellen.
  • Verwende im Formular keine URL-Codierung. Wenn eine API-Methode eine URL-Codierung erfordert, führt das Widget die Konvertierung aus, 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 ein, z. B. 2. Der Parameter pageSize definiert die maximale Anzahl von Ergebnissen, die zurückgegeben wird, 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 APIsAPIs Explorer“ finden Sie den Abschnitt Anmeldedaten. Wir empfehlen, für diese Felder die Standardwerte beizubehalten. Der Standardmechanismus für die Authentifizierung ist Google OAuth 2.0.

Klicken Sie auf Bereiche anzeigen, um zu ermitteln, 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 Zugriffssteuerung.