使用 APIs Explorer

本指南說明如何使用 APIs Explorer 試用 Cloud Monitoring API 方法。API Explorer 是附加至方法 REST API 參考資料頁面的小工具。這個小工具會以「Try this API」為標題顯示在面板中。下圖顯示，當方法只有一個參數 name 時，面板會顯示如下：

如要試用 Cloud Monitoring API 中的各項方法，但不想編寫任何程式碼，API Explorer 就是絕佳的選擇。小工具會顯示表單，顯示每個方法的參數。填寫表單，按一下「執行」按鈕，即可查看結果。

您也可以按一下 close 按鈕隱藏小工具，或是按一下 fullscreen 按鈕將小工具展開至全螢幕。

「試試看！」按鈕

在說明文件中，您可能會看到類似下方的「試試看」按鈕：

按一下按鈕後，方法參考頁面上的 API Explorer 就會開啟。系統通常會填入與範例相符的部分參數；不過，您可能需要編輯部分參數，以符合您自己的專案，例如 [PROJECT_ID] 的值。

如要瞭解如何避免和修正錯誤，請參閱「疑難排解」一節。

存取 API Explorer

每個 REST API 方法的參考資料頁面都會附上 API Explorer。如要找出小工具，請參閱方法的參考資料頁面，例如 metricDescriptors.list。

執行要求

大多數方法都包含一些必要參數和選用參數。必填欄位會標示紅色橫條，直到填妥為止。您可以為所有必要引數提供值，然後執行要求。

如要執行 metricDescriptors.list 方法，請執行下列操作：

1. 按一下「試試看」
2. 在「name」參數中，使用 projects/[PROJECT_ID] 格式輸入專案 ID。請務必將 [PROJECT_ID] 替換為專案 ID。
3. 按一下 [Execute] (執行)。如要執行這項指令，API Explorer 需要存取您的帳戶。出現提示時，請選取帳戶並按一下「允許」。存取權僅限於一段時間內，且僅限於您執行的 API 方法。

方法叫用結果會顯示在具有綠色或紅色標題的方塊中。要求成功後，方塊會顯示綠色標頭，內含 HTTP 狀態碼 200。喚出的結果會顯示在方塊中：

如果標頭為紅色，則表示包含 HTTP 失敗代碼，而方塊則包含錯誤訊息。如要瞭解如何解決錯誤，請參閱「疑難排解」。

提供其他參數

您看到的參數清單取決於 API Explorer 小工具所附加的方法。舉例來說，metricDescriptors.list 方法除了 name 參數外，還有其他參數，但 name 是唯一必要參數。

如果您只提供專案名稱，系統會提供專案中可用的所有指標描述元，而這些指標描述元非常多。如要將擷取作業限制在較小的集合中，請使用 filter 參數。

舉例來說，如要只列出名稱結尾為 utilization 的指標類型，請執行下列操作：

1. 按一下「試試看」

2. 在「name」參數中，使用 projects/[PROJECT_ID] 格式輸入專案 ID。請務必將 [PROJECT_ID] 替換為專案 ID。

3. 確認 filter 參數的值為 metric.type=ends_with("utilization")

4. 按一下「執行」，並完成授權對話方塊。

標準參數

根據預設，API Explorer 顯示的參數組合會對應至相關聯方法的參數。不過，API Explorer 小工具也包含一組不在方法本身範圍內的額外參數。如要顯示額外參數，請按一下「顯示標準參數」：

如要隱藏顯示畫面上的額外參數，請按一下「隱藏標準參數」。

最實用的標準參數是 fields 參數。這個參數可讓您選取要查看的已傳回輸出內容中的欄位。

舉例來說，列出結尾為 utilization 的指標描述元仍會傳回許多結果。如果您只想知道指標類型名稱及其說明，可以使用 fields 參數指定這項限制。

如要查看設定 fields 參數的結果，請按照下列步驟操作：

1. 按一下「試試看」

2. 在「name」參數中，使用 projects/[PROJECT_ID] 格式輸入專案 ID。請務必將 [PROJECT_ID] 替換為專案 ID。

3. 確認 filter 參數的值為 metric.type=ends_with("utilization")

4. 按一下「顯示標準參數」，確認「fields」參數的值為 metricDescriptors.type,metricDescriptors.description

5. 按一下「執行」，並完成授權對話方塊。

執行這項要求只會傳回每個指標的 type (簡稱) 和 description。

疑難排解

本節說明使用 API Explorer 時的常見問題。

無效的篩選器語法

您複製多行運算式並貼到 API Explorer 中顯示的欄位，但 API Explorer 會顯示錯誤訊息。

做法：請確保字串位於單一行。

"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 方法中視為拼字錯誤：

• 請勿在任何類型的參數值前後加上引號。

• 除非需要保護子字串，否則請勿使用反斜線。

  舉例來說，下列範例適用於 API 方法，您可以將內容以 JSON 格式輸入，而非填寫個別表單參數。由於 filter 的值是字串，因此子字串 k8s_cluster 會受到反斜線保護：

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

• 在篩選器中顯示引號字串。請使用雙引號 (")，而非撇號 (')。如需範例，請參閱「提供其他參數」。

• 請勿在表單中使用網址編碼。如果 API 方法需要網址編碼，小工具會在您執行方法時執行轉換。

傳回的資料過多

如要限制傳回的結果數量，請在 pageSize 參數中輸入值，例如 2。pageSize 參數會定義傳回的結果數量上限，適用於大多數 API 方法。

如要選取要傳回的特定欄位，請使用 fields 參數。詳情請參閱「標準參數」。

驗證

API Explorer 頁面上有「憑證」專區。建議您將這些欄位保留預設值。預設的驗證機制為 Google OAuth 2.0。

如要瞭解方法需要哪些 API 範圍，請按一下「Show scopes」。根據預設，系統會授予所有必要的範圍。

如要進一步瞭解這些概念，請參閱「使用身分與存取權管理功能控管存取權」。