Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

使用 gcloud CLI 寫入及查詢記錄項目

Google Cloud CLI 可讓您透過指令列在 Cloud Logging 中寫入及查詢記錄項目，以便測試記錄擷取及檢查記錄資料，而不必編寫應用程式程式碼。在本快速入門導覽課程中，您將使用 gcloud CLI 寫入及列出結構化和非結構化記錄項目、使用 Cloud Logging API 列出記錄項目，以及使用 Logs Explorer 查看及查詢記錄。

事前準備

您必須擁有已啟用計費功能的 Google Cloud 專案，才能完成這項快速入門導覽課程。如果您沒有 Google Cloud 專案，或 Google Cloud 專案未啟用計費功能，請按照下列步驟操作：

登入 Google Cloud 帳戶。如果您未曾使用過 Google Cloud，歡迎建立帳戶，親自體驗實際使用我們產品的成效。新客戶還能獲得價值 $300 美元的免費抵免額，用於執行、測試及部署工作負載。

安裝 Google Cloud CLI。

注意：如果您先前已安裝 gcloud CLI，請執行 gcloud components update，確認您使用的是最新版本。

若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

執行下列指令，初始化 gcloud CLI：

gcloud init

建立或選取 Google Cloud 專案。

選取或建立專案所需的角色

選取專案：選取專案時，不需具備特定 IAM 角色，只要您已獲派某個專案的角色，即可選取該專案。
建立專案：如要建立專案，您必須具備專案建立者角色 (roles/resourcemanager.projectCreator)，其中包含 resourcemanager.projects.create 權限。瞭解如何授予角色。

建立 Google Cloud 專案：
```
gcloud projects create PROJECT_ID
```
將 PROJECT_ID 替換為您要建立的 Google Cloud 專案名稱。
選取您建立的 Google Cloud 專案：
```
gcloud config set project PROJECT_ID
```
將 PROJECT_ID 替換為 Google Cloud 專案名稱。

如要使用現有專案進行本指南中的操作，請確認您具有完成本指南所需的權限。如果您建立新專案，則已具備必要權限。

確認 Google Cloud 專案已啟用計費功能。

安裝 Google Cloud CLI。

注意：如果您先前已安裝 gcloud CLI，請執行 gcloud components update，確認您使用的是最新版本。

若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

執行下列指令，初始化 gcloud CLI：

gcloud init

建立或選取 Google Cloud 專案。

選取或建立專案所需的角色

選取專案：選取專案時，不需具備特定 IAM 角色，只要您已獲派某個專案的角色，即可選取該專案。
建立專案：如要建立專案，您必須具備專案建立者角色 (roles/resourcemanager.projectCreator)，其中包含 resourcemanager.projects.create 權限。瞭解如何授予角色。

建立 Google Cloud 專案：
```
gcloud projects create PROJECT_ID
```
將 PROJECT_ID 替換為您要建立的 Google Cloud 專案名稱。
選取您建立的 Google Cloud 專案：
```
gcloud config set project PROJECT_ID
```
將 PROJECT_ID 替換為 Google Cloud 專案名稱。

如要使用現有專案進行本指南中的操作，請確認您具有完成本指南所需的權限。如果您建立新專案，則已具備必要權限。

確認 Google Cloud 專案已啟用計費功能。

必要的角色

如要取得建立、列出及刪除記錄項目所需的權限，請要求管理員授予您專案的 Logging 管理員 (roles/logging.admin) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

記錄寫入者 (roles/logging.logWriter) 和記錄檢視器 (roles/logging.viewer) 角色包含建立及列出記錄項目的權限。如要刪除記錄項目，請授予 Logging 管理員 (roles/logging.admin) 角色，該角色具備建立、列出及刪除記錄項目的權限。請注意，Logging 管理員 (roles/logging.admin) 角色也具備在 Logging 中執行所有動作的權限。

使用 gcloud CLI 寫入記錄項目

Logging 支援含有結構化和非結構化資料的記錄項目。結構化資料由 JSON 資料結構組成，例如 {"weather": "partly cloudy"}。非結構化資料是一串字元，例如 "A simple entry"。

在後續步驟中，您將使用 gcloud CLI 寫入含有非結構化資料的記錄項目，以及含有結構化資料的記錄項目。gcloud CLI 提供 Cloud Logging API 的指令列介面。

如要將含有非結構化資料的記錄項目寫入記錄 my-test-log，請執行 gcloud logging write 指令：
```
gcloud logging write my-test-log "A simple entry."
```
指令執行完畢後，您會看到以下訊息：Created log entry。
將含有結構化資料的記錄項目寫入記錄 my-test-log：
```
gcloud logging write --payload-type=json my-test-log '{ "message": "My second entry", "weather": "partly cloudy"}'
```
使用結構化資料寫入記錄項目時，必須包含 --payload-type=json。如果省略這個欄位，Logging 會將酬載解讀為非結構化資料。

如果記錄 my-test-log 不存在，Logging 會在收到記錄項目時建立記錄。

使用 gcloud CLI 列出記錄項目

您可以使用 gcloud CLI 從 Logging 擷取記錄項目並顯示。舉例來說，如要擷取並顯示資源類型為 global 的記錄項目，請執行下列指令：

gcloud logging read "resource.type=global"

指令會傳回類似以下的結果：

---
insertId: jpj9zjf73t1mn
jsonPayload:
  message: My second entry
  weather: partly cloudy
logName: projects/myloggingproject/logs/my-test-log
receiveTimestamp: '2018-11-01T18:39:31.114507977Z'
resource:
  labels:
    project_id: myloggingproject
  type: global
timestamp: '2018-11-01T18:39:31.114507977Z'
---
insertId: vd4m1if7h7u1a
logName: projects/myloggingproject/logs/my-test-log
receiveTimestamp: '2018-11-01T18:39:19.718100792Z'
resource:
  labels:
    project_id: myloggingproject
  type: global
textPayload: A simple entry
timestamp: '2018-11-01T18:39:19.718100792Z'

如要瞭解如何讀取記錄，請參閱 gcloud logging read 參考文件。

使用 APIs Explorer 列出記錄項目

如要執行 Logging API 方法，而不編寫任何程式碼，請參閱「使用 APIs Explorer」。如要讀取 Logging 的記錄項目清單，請按照下列步驟操作：

前往 entries.list API 方法的 API 參考資料頁面：

前往 entries.list API 頁面

設定並執行 API 指令：

請替換下列文字中的 PROJECT_ID：

"resourceNames": [
"projects/PROJECT_ID"
],
"filter": "resource.type=global",
"orderBy": "timestamp desc"

複製上一個步驟中更新的文字，然後貼到 APIs Explorer 的「Request body」(要求主體) 欄位。
點選「Execute」。

方法會傳回類似以下的回應：

{
  "entries": [
    {
      "textPayload": "A simple entry",
      "insertId": "vd4m1if7h7u1a",
      "resource": {
        "type": "global",
        "labels": {
          "project_id": "myloggingproject"
        }
      },
      "timestamp": "2018-11-01T18:39:19.718100792Z",
      "logName": "projects/myloggingproject/logs/my-test-log",
      "receiveTimestamp": "2018-11-01T18:39:19.718100792Z"
    },
    {
      "insertId": "jpj9zjf73t1mn",
      "jsonPayload": {
        "message": "My second entry",
        "weather": "partly cloudy"
      },
      "resource": {
        "type": "global",
        "labels": {
          "project_id": "myloggingproject"
        }
      },
      "timestamp": "2018-11-01T18:39:31.114507977Z",
      "logName": "projects/myloggingproject/logs/my-test-log",
      "receiveTimestamp": "2018-11-01T18:39:31.114507977Z"
    }
  ]
}

在 Logs Explorer 中查看記錄項目

如要在 Google Cloud 控制台查看記錄項目，可以使用 Logs Explorer。大多數 Google Cloud 專案都會儲存大量記錄，您可以撰寫查詢來選取特定記錄項目。

如要使用 Logs Explorer 查看您寫入的記錄項目，請按照下列步驟操作：

前往 Google Cloud 控制台的「Logs Explorer」頁面：
前往「Logs Explorer」(記錄檔探索工具)

如果您是使用搜尋列尋找這個頁面，請選取子標題為「Logging」的結果。

確認已在 Google Cloud導覽列中選取 Google Cloud 專案。如有需要，請使用 Google Cloud 專案下拉式選單選取 Google Cloud 專案。
在「Resource」(資源) 選單中，選取「Global」(全域)。

如果沒有看到「Global」(全域) 選單選項或記錄項目，請稍候幾分鐘，然後重新整理頁面。Logging 可能需要幾分鐘的時間才能接收記錄項目。
如要查看記錄項目的詳細資料，請按一下「Menu」(選單) 圖示。

第一個記錄項目的資料儲存在 textPayload 中。第二個記錄項目包含儲存在 jsonPayload 中的結構化資料。結構化酬載包含 message 和 weather 鍵。

注意： 如果 message 是結構化記錄項目的索引鍵，Logging 會在項目未展開時，將其做為記錄項目的摘要。

如要瞭解記錄項目的資料格式，請參閱 LogEntry 類型。

在 Logs Explorer 中查詢記錄項目

您可以使用查詢編輯器查詢記錄項目，如果是結構化記錄，則可依鍵和值查詢。舉例來說，如要顯示含有 simple 文字的所有記錄項目，請執行下列操作：

前往 Google Cloud 控制台的「Logs Explorer」頁面：
前往「Logs Explorer」(記錄檔探索工具)

如果您是使用搜尋列尋找這個頁面，請選取子標題為「Logging」的結果。
在「Resource」(資源) 選單中，選取「Global」(全域)。
在查詢編輯器中，輸入以引號括住的字串 simple。記錄檔顯示畫面只會顯示記錄項目 A simple entry.
查看記錄後，請移除新增的查詢字串，然後點選「執行查詢」。兩個記錄項目都會重新顯示在顯示畫面中。

如要顯示含有結構化資料的所有記錄項目，且這些資料的索引鍵為 weather，而 value 欄位包含 partly，請執行下列操作：

查詢編輯器包含 resource.type="global" 這一行。輸入下列指令：
```
jsonPayload.weather:partly
```
按一下「Run query」(執行查詢)。結果會是單一記錄項目 My second entry。

Logs Explorer 也提供已儲存、建議和近期的查詢。如要進一步瞭解查詢，請參閱「透過 Logs Explorer 建構查詢」。

如需查詢範例，請參閱「使用記錄檔探索工具的查詢範例」。

疑難排解

如果輸入錯誤和欄位名稱不明，gcloud CLI 指令會顯示「invalid argument」(引數無效) 訊息。舉例來說，如果忘記在 resource.type 中加上句號，就會發生錯誤：
```
 ERROR: (gcloud.logging.read) INVALID_ARGUMENT: Field not found: 'resourcetype'.
```
如果 Cloud Logging 未取得必要的存取權限，gcloud CLI 指令會完成，並顯示「permission denied」(權限遭拒) 訊息。舉例來說，如果 Compute Engine VM 執行個體採用預設 API 設定，list 指令會因權限遭拒錯誤而無法完成：
```
 ERROR: (gcloud.logging.read) PERMISSION_DENIED: Request had insufficient authentication scopes.
```
如要修正這個問題，請修改 Compute Engine VM 執行個體權限，授予 Cloud Logging 讀取的權限，步驟如下：
1. 前往 VM 執行個體的「VM instance details」(VM 執行個體詳細資料) 頁面。按一下「停止」。這個動作可能需要一兩分鐘的時間才能完成。
2. 如要修改設定，請按一下 [Edit] (編輯)。
3. 搜尋「Cloud API access scopes」(Cloud API 存取權範圍) 標題，然後按一下「Details」(詳細資料)，即可顯示各個 API 的設定。將 Cloud Logging API 的項目變更為「Full」(完整)。然後按一下 [儲存]。
4. 如要重新啟動您的 VM 執行個體，請按一下 [Start] (啟動)。經過一段時間後，您的 VM 即準備好可供使用。

如果 APIs Explorer 無法完成指令，或需要額外授權，就會顯示訊息或錯誤代碼：
- 200 回應代碼且沒有項目：如果顯示 nextPageToken 訊息，表示 APIs Explorer 沒有時間完成搜尋。在要求中新增 pageToken，並將值設為與 nextPageToken 鍵相同的值，然後重試指令。
- 400 回應代碼：查詢值無效。舉例來說，如果您將 global 誤拼為 gloobal，則訊息為 Unsupported resource type: gloobal。
- 404 回應代碼：專案 ID 無效。檢查專案 ID 的拼寫。
- 系統可能會要求您登入Google Cloud 專案，並允許 APIs Explorer 存取您的帳戶。

清除所用資源

為了避免系統向您的 Google Cloud 帳戶收取本頁面所用資源的費用，請刪除含有這些資源的 Google Cloud 專案。

(選用) 如要刪除建立的記錄項目，請執行下列 gcloud 指令：
```
gcloud logging logs delete my-test-log
```
如果您未刪除記錄項目，這些項目就會過期並遭到移除。如要瞭解保留資訊，請參閱「配額與限制」。

後續步驟

如要進一步瞭解 Logging 指令列介面，請參閱 gcloud logging 指令群組的參考頁面。
如需 Logging API 的說明文件，請參閱「Cloud Logging API」。
如要進一步瞭解記錄檔探索工具，請參閱「使用記錄檔探索工具」。

如要瞭解如何在 Logging 中收集 VM 執行個體的記錄項目，請參閱「Google Cloud Observability 代理程式」。