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 ウィジェットには、メソッド自体の一部ではない一連の追加パラメータもあります。追加パラメータを表示するには、[標準パラメータを表示] をクリックします。

標準パラメータを表示の切り替え。

追加パラメータを非表示にするには、[Hide standard parameters] をクリックします。

特に便利な標準パラメータは [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 のトラブルシューティングをご覧ください。

無効なフィルタ構文

複数行の式を、API Explorer に表示されるフィールドにコピーして貼り付けると、API Explorer ではエラーメッセージが表示されます。

推奨事項: 文字列が 1 行に収まるようにする。

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

禁止事項: 行継続文字や改行文字をコピーして貼り付ける。

たとえば、timeSeries.query メソッドに以下を追加すると、API Explorer によりエラーメッセージ「Select an underlined section to see more details」が表示されます。

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

無効なプロジェクト ID

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

この状態を解決するには、テキスト [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 ページには、[認証情報] セクションがあります。これらのフィールドは、デフォルト値のままにすることをおすすめします。デフォルトの認証方法は、Google OAuth 2.0 です。

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

これらのコンセプトの詳細については、Identity and Access Management を使用してアクセスを制御するをご覧ください。