API Explorer の使用

このガイドでは、API Explorer を使用して Cloud Monitoring API メソッドを試す方法について説明します。API Explorer は、メソッドの REST API リファレンスページにアタッチされたウィジェットです。[この API を試す] というタイトルのパネルとして表示されます。次のスクリーンショットは、1 つのパラメータのみ（name）があるメソッドに対して表示されるパネルを示しています。

API Explorer を使用すると、コードを記述することなく Cloud Monitoring API でメソッドを試すことができます。ウィジェットには、各メソッドのパラメータを示すフォームが表示されます。フォームに入力し、[実行] ボタンをクリックして結果を確認します。

ボタンをクリックしてウィジェットを非表示にすることや、ボタンをクリックしてウィジェットを全画面表示することも可能です。

[試してみましょう] ボタン

ドキュメントには、次のような [試してみる] ボタンが表示されます。

試してみる

ボタンをクリックすると、API Explorer がメソッドのリファレンスページで開きます。通常、この例に適したパラメータにデータが入力されますが、実際のプロジェクトに合わせて [PROJECT_ID] の値など、いくつかのパラメータを編集しなければならない場合もあります。

エラーの回避と修正の詳細については、トラブルシューティングをご覧ください。

API Explorer にアクセスする

API Explorer は、各 REST API メソッドのリファレンスページにアタッチされています。ウィジェットを見つけるには、メソッドのリファレンスページをご覧ください（例: metricDescriptors.list）。

リクエストを実行する

ほとんどのメソッドには、必須のパラメータとオプションのパラメータがあります。必須のパラメータは、入力されるまで赤色のバーでマークされています。リクエストは、必須の引数の値をすべて指定した後に実行できます。

metricDescriptors.list メソッドは、プロジェクトで使用可能な指標タイプすべての記述子を返します。唯一の必須パラメータは name パラメータです。

metricDescriptors.list メソッドを実行するには、次のようにします。

[試してみる] をクリックします。
[name] パラメータにプロジェクトの ID を projects/[PROJECT_ID] の形式で入力します。必ず [PROJECT_ID] は、プロジェクトの ID に置き換えてください。
[実行] をクリックします。このコマンドを実行するには、API Explorer がアカウントにアクセスする必要があります。メッセージが表示されたら、アカウントを選択して [許可] をクリックします。アクセスは、限られた期間かつ実行している API メソッドに限定されます。

メソッドの呼び出しの結果は、緑色または赤色のヘッダーのボックスに表示されます。リクエストが成功すると、緑色のヘッダーに HTTP ステータスコード 200 が表示されたボックスになります。ボックス内には、呼び出しの結果が表示されます。

ヘッダーが赤色の場合は、そこに HTTP 障害コードが表示され、ボックスにはエラーメッセージが出力されます。エラーの解決については、トラブルシューティングをご覧ください。

追加のパラメータを指定する

表示されるパラメータのリストは、API Explorer ウィジェットがアタッチされているメソッドによって異なります。たとえば、metricDescriptors.list メソッドにはパラメータが name 以外にもありますが、必須のパラメータは name のみです。

プロジェクト名だけを指定すると、プロジェクトで使用可能なすべての指標記述子が取得されます。指標記述子は数多くあります。取得範囲を限定するには、filter パラメータを使用します。

たとえば、名前が utilization で終わる指標タイプだけを一覧表示するには、次のようにします。

[試してみる] をクリックします。
[name] パラメータにプロジェクトの ID を projects/[PROJECT_ID] の形式で入力します。必ず [PROJECT_ID] は、プロジェクトの ID に置き換えてください。
[filter] パラメータの値が metric.type=ends_with("utilization") であることを確認します。
[EXECUTE] をクリックし、承認ダイアログを完了します。

標準パラメータ

デフォルトでは、API Explorer によって表示されるパラメータのセットは関連するメソッドのパラメータに対応しています。ただし、API Explorer ウィジェットには、メソッド自体の一部ではない一連の追加パラメータもあります。追加パラメータを表示するには、[標準パラメータを表示] をクリックします。

[標準パラメータを表示する] の切り替えボタン。

余分なパラメータを非表示にするには、[標準パラメータを非表示] をクリックします。

特に便利な標準パラメータは [fields] パラメータです。このパラメータを使用すると、返された出力から項目を選択して表示できます。

たとえば、utilization で終わる指標の記述子をリスト出力すると、多くの結果が返されます。指標タイプの名前とその説明のみを知りたい場合は、[fields] パラメータを使用してこの制限を指定できます。

[fields] パラメータに設定した結果を確認するには、次のようにします。

[試してみる] をクリックします。
[name] パラメータにプロジェクトの ID を projects/[PROJECT_ID] の形式で入力します。必ず [PROJECT_ID] は、プロジェクトの ID に置き換えてください。
[filter] パラメータの値が metric.type=ends_with("utilization") であることを確認します。
[標準パラメータを表示] をクリックし、[fields] パラメータの値が metricDescriptors.type,metricDescriptors.description になっていることを確認します。
[EXECUTE] をクリックし、承認ダイアログを完了します。

このリクエストを実行すると、各指標とその description の type（短縮名）のみが返されます。

トラブルシューティング

このセクションでは、API Explorer を使用する際の一般的な問題について説明します。

Cloud Monitoring API の使用方法について詳しくは、Cloud Monitoring API のトラブルシューティングをご覧ください。

プロジェクト ID が無効です

プロジェクト ID が無効な場合、API リクエストは 400 の HTTP エラーで失敗します。

この状態を解決するには、テキスト [PROJECT_ID] がプロジェクトの ID に置き換えられていることを確認します。

フォームの値が無効です

API リクエストが失敗したか、予期しない値が返された場合は、すべてのフォームパラメータを確認してください。

API Explorer のパラメータには、決まった形式があります。形式に誤りがあると、エラーが発生する可能性があります。また、入力できても API メソッドでスペルミスとして扱われることがあります。

どのタイプのパラメータ値も、それを引用符で囲まないようにしてください。
部分文字列を保護する必要がある場合を除き、バックスラッシュは使用しないでください。

たとえば、次のサンプルは、個々のフォームパラメータの入力ではなく、コンテンツを JSON として入力する API メソッドに対するものです。filter の値は文字列のため、部分文字列 k8s_cluster はバックスラッシュで保護されます。

    {
      "resourceNames": [...],
      "filter": "resource.type = \"k8s_cluster\""
    }

フィルタ内の文字列は、引用符で囲みます。アポストロフィ（'）ではなく、二重引用符（"）を使用します。追加のパラメータを指定するの例をご覧ください。

フォームでは URL エンコードを使用しないでください。API メソッドで URL エンコードが必要な場合、ウィジェットによりメソッドの実行時に変換が実行されます。

返されるデータが多すぎます

返される結果の数を制限するには、pageSize パラメータに値（2 など）を入力します。pageSize パラメータは、返される結果の最大数を定義します。このパラメータは、ほとんどの API メソッドで使用できます。

返す特定のフィールドを選択するには、fields パラメータを使用します。詳細については、標準パラメータをご覧ください。

認証

API Explorer ページには、[Credentials] セクションがあります。これらのフィールドはデフォルト値のままにすることをおすすめします。デフォルトの認証メカニズムは Google OAuth 2.0 です。

メソッドに必要な API スコープを確認するには、[Show scopes] をクリックします。デフォルトでは、必要なスコープがすべて付与されます。

こうしたコンセプトの詳細については、アクセス制御をご覧ください。