本頁面由 Cloud Translation API 翻譯而成。

彙整機構和資料夾層級記錄，並將其轉送至支援的目的地

本文說明如何建立匯總接收器。匯總接收器可讓您合併及轉送機構或資料夾中Google Cloud 資源產生的記錄，並集中儲存至同一位置。

事前準備

建立接收器前，請確認下列事項：

您熟悉匯總接收器的行為。如要瞭解這些接收器，請參閱「匯總接收器總覽」。
您擁有 Google Cloud 資料夾或機構，其中包含可在 Logs Explorer 中查看的記錄項目。
您具有下列任一 IAM 角色，可從Google Cloud 機構或資料夾中將記錄檔項目路由傳送出去。
- 擁有者 (roles/owner)
- 記錄管理員 (roles/logging.admin)
- 記錄設定寫入者 (roles/logging.configWriter)
這些角色包含的權限可讓您建立、刪除或修改接收器。如要瞭解如何設定 IAM 角色，請參閱 Logging 存取權控管指南。
匯總接收器的目的地存在，或您有權建立目的地。

如果目的地是 Google Cloud 專案，該專案可以位於任何機構。所有其他目的地可位於任何機構的任何專案中。
Select the tab for how you plan to use the samples on this page:
Console

When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
REST

如要在本機開發環境中使用本頁的 REST API 範例，請使用您提供給 gcloud CLI 的憑證。
詳情請參閱 Google Cloud 驗證說明文件中的「Authenticate for using REST」。

建立匯總接收器

如要設定匯總接收器，請建立接收器，然後授予接收器寫入目的地的權限。本節說明如何建立匯總接收器。如要瞭解如何授予接收器權限，請參閱本頁面「設定目的地權限」一節。

每個資料夾或機構最多可建立 200 個接收器。

控制台

如要為資料夾或機構建立匯總接收器，請按照下列步驟操作：

前往 Google Cloud 控制台的「Log Router」(記錄檔路由器) 頁面：
前往「記錄檔路由器」

如果您是使用搜尋列尋找這個頁面，請選取子標題為「Logging」的結果。
選取現有的資料夾或機構。
選取「建立接收器」。
在「接收器詳細資料」面板中，輸入下列詳細資料：
- 「Sink name」(接收器名稱)：提供接收器的 ID；請注意，建立接收器後就無法重新命名，但可以刪除並建立新的接收器。
- 接收器說明 (選填)：說明接收器的用途或用途。
在「選取接收器服務」選單中，選取目的地類型，然後完成對話方塊以指定目的地。您可以選取現有目的地或建立目的地。
- 如果是攔截用接收器，請選取「Google Cloud 專案」，然後輸入目的地 Google Cloud 專案的完整名稱：
```
logging.googleapis.com/projects/DESTINATION_PROJECT_ID
```
- 如果是非攔截接收器，請選取目的地，然後輸入目的地的完整名稱。系統支援下列目的地：
  - Google Cloud 專案
```
logging.googleapis.com/projects/DESTINATION_PROJECT_ID
```
  - Cloud Logging 值區
```
logging.googleapis.com/projects/DESTINATION_PROJECT_ID/locations/LOCATION/buckets/BUCKET_NAME
```
  - BigQuery 資料集
    
    您必須輸入可寫入資料集的完整名稱。資料集可以是以日期為分片依據的資料表或分區資料表。請勿輸入連結的資料集名稱。連結的資料集為唯讀。
```
bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID
```
  - Cloud Storage bucket
```
storage.googleapis.com/BUCKET_NAME
```
  - Pub/Sub 主題
```
pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_ID
```
  - Splunk
    
    輸入 Splunk 服務的 Pub/Sub 主題。
在「選擇要納入接收器的記錄檔」面板中，選取要納入接收器的資源。
- 如果是攔截接收器，請選取「攔截這個機構和所有子資源擷取的記錄檔」。
- 如果是非攔截接收器，請選取「收錄這個資源和所有子資源擷取的記錄檔」。
在「Build inclusion filter」(建立「包含」篩選器) 欄位中，輸入與要納入的記錄項目相符的篩選器運算式。如未設定篩選器，所選資源的所有記錄項目都會轉送至目的地。

舉例來說，您可能想建立篩選器，將所有資料存取稽核記錄路由至單一記錄儲存空間。這個篩選器如下所示：
```
LOG_ID("cloudaudit.googleapis.com/data_access") OR LOG_ID("externalaudit.googleapis.com/data_access")
```
如需篩選器範例，請參閱本頁的「為匯總接收器建立篩選器」一節。

請注意，篩選器的長度不得超過 20,000 個字元。
選用步驟：如要確認輸入的篩選器是否正確，請選取「預覽記錄」。系統會在新的分頁中開啟記錄檔探索工具，並預先填入篩選條件。
選用：在「選擇要從接收器排除的記錄檔」面板中，執行下列操作：
1. 在「排除條件篩選器名稱」欄位中輸入名稱。
2. 在「Build an exclusion filter」(建立排除篩選器) 欄位中，輸入與您想排除的記錄項目相符的篩選器運算式。您也可以使用 sample 函式選取要排除的記錄項目部分。
  
  重要事項： 如要在建立接收器時停用排除篩選器，請輸入篩選器運算式，然後選取「停用」。您可以稍後更新接收器，啟用排除篩選器。
  
  舉例來說，如要排除特定專案的記錄項目，避免這些項目傳送至目的地，請新增下列排除篩選器：
```
logName:projects/PROJECT_ID
```
  如要排除多個專案的記錄項目，請使用邏輯 OR 運算子來聯結 logName 子句。
每個接收器最多可建立 50 個排除篩選器。請注意，篩選器的長度不得超過 20,000 個字元。
選取「建立接收器」。
如要完成匯總接收器的設定，請將記錄項目寫入接收器目的地的權限，授予接收器的服務帳戶。詳情請參閱「設定目的地權限」。

gcloud

如要建立匯總接收器，請使用 logging sinks create 指令：

如要建立接收器，請呼叫 gcloud logging sinks create 指令，並務必加入 --include-children 選項。

使用下列指令之前，請先替換以下項目：
- SINK_NAME：記錄接收器的名稱。水槽名稱一經建立即無法變更。
- SINK_DESTINATION：要將記錄項目轉送至的服務或專案。如要瞭解這些目的地的格式，請參閱「目的地路徑格式」。
- INCLUSION_FILTER：接收器的納入篩選器。如需篩選器範例，請參閱「為匯總接收器建立篩選器」。
- FOLDER_ID：資料夾的 ID。如要在機構層級建立接收器，請將 --folder=FOLDER_ID 替換為 -- organization=ORGANIZATION_ID。
執行 gcloud logging sinks create 指令：
```
gcloud logging sinks create SINK_NAME \
  SINK_DESTINATION  --include-children \
  --folder=FOLDER_ID --log-filter="INCLUSION_FILTER"
```
你也可以提供下列選項：
- 如要建立攔截接收器，請加入 --intercept-children 選項。
舉例來說，如果您要在資料夾層級建立匯總接收器，且目的地為 Pub/Sub 主題，則指令可能如下所示：
```
gcloud logging sinks create SINK_NAME \
  pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_ID --include-children \
  --folder=FOLDER_ID --log-filter="logName:activity"
```
授予接收器服務帳戶寫入接收器目的地的權限。詳情請參閱「設定目的地權限」。

REST

如要建立匯總接收器，請使用 organizations.sinks.create 或 folders.sinks.create Logging API 方法。如下準備方法的引數：

將 parent 欄位設為要在其中建立接收器的 Google Cloud 機構或資料夾。父項必須是下列其中一項：
- organizations/ORGANIZATION_ID
- folders/FOLDER_ID
在方法要求主體的 LogSink 物件中，執行下列其中一項操作：
- 將 includeChildren 設為 True。
- 如要建立攔截接收器，請將 interceptChildren 欄位設為 True。
設定 filter 欄位，比對要納入的記錄項目。

如需篩選器範例，請參閱「為匯總接收器建立篩選器」。

篩選條件長度不得超過 20,000 個字元。
設定剩餘的 LogSink 欄位，方法與為任何接收器設定時相同。詳情請參閱「將記錄檔傳送至支援的目的地」。
呼叫 organizations.sinks.create 或 folders.sinks.create 以建立接收器。
授予接收器服務帳戶寫入接收器目的地的權限。詳情請參閱「設定目的地權限」。

對接收器所做的任何變更，可能需要幾分鐘才會套用。

匯總接收器的篩選器

本節提供您可能在匯總接收器中使用的篩選器範例。如需更多範例，請參閱「使用記錄檔探索工具的查詢範例」。

有一些範例使用了下列標記法：

: 是子字串運算子。請勿替換 = 運算子。
... 代表其他任何篩選器比較。
變數會以彩色文字表示，以有效的值取代。

篩選條件長度不得超過 20,000 個字元。

如要進一步瞭解篩選語法，請參閱「Logging 查詢語言」。

選取記錄來源

如要轉送所有子資源的記錄項目，請勿在接收器的「包含」和「排除」篩選器中指定專案、資料夾或機構。舉例來說，假設您為機構設定匯總接收器，並使用下列篩選器：

resource.type="gce_instance"

使用先前的篩選器時，如果記錄項目具有 Compute Engine 執行個體的資源類型，且寫入該機構的任何子項，匯總接收器就會將這些項目傳送至目的地。

不過，在某些情況下，您可能會想使用匯總接收器，只從特定子項資源傳送記錄檔項目。舉例來說，基於法規遵循考量，您可能想將特定資料夾或專案的稽核記錄儲存在專屬的 Cloud Storage bucket 中。在這些情況下，請設定納入篩選器，指定要將記錄項目傳送至每個子項資源。如要從資料夾和該資料夾內的所有專案轉送記錄項目，篩選器必須列出資料夾和該資料夾內含的每個專案，並以 OR 子句聯結陳述式。

下列篩選器會將記錄項目限制為特定 Google Cloud 專案、資料夾或機構：

logName:"projects/PROJECT_ID/logs/" AND ...

logName:("projects/PROJECT_A_ID/logs/" OR "projects/PROJECT_B_ID/logs/") AND ...

logName:"folders/FOLDER_ID/logs/" AND ...

logName:"organizations/ORGANIZATION_ID/logs/" AND ...

舉例來說，如要只將寫入資料夾 my-folder 的 Compute Engine 執行個體記錄項目傳送至 Cloud Logging，請使用下列篩選器：

logName:"folders/my-folder/logs/" AND resource.type="gce_instance"

使用先前的篩選器時，系統不會將寫入 my-folder 以外任何資源的記錄項目 (包括寫入 my-folder 子項專案的記錄項目) 轉送至目的地。 Google Cloud

選取受監控的資源

如要僅從Google Cloud 專案中的特定受監控資源，將記錄項目傳送至接收器，請使用多個比較條件精確指定資源：

logName:"projects/PROJECT_ID/logs" AND
resource.type=RESOURCE_TYPE AND
resource.labels.instance_id=INSTANCE_ID

如需資源類型清單，請參閱受控資源類型。

選取記錄項目樣本

如要將記錄項目隨機樣本傳送至特定目的地，請新增 sample 內建函式。舉例來說，如果只是要將符合目前篩選器的記錄項目的 10% 傳送至接收器，請加上以下這一行：

sample(insertId, 0.10) AND ...

詳情請參閱 sample 函式。

如要進一步瞭解 Cloud Logging 篩選器，請參閱「Logging 查詢語言」。

設定目的地權限

本節說明如何授予 Logging Identity and Access Management 權限，將記錄檔項目寫入接收器的目的地。如需 Logging 角色和權限的完整清單，請參閱存取權控管。

建立或更新接收器時，如果接收器會將記錄項目轉送至目前專案中的記錄 bucket 以外的任何目的地，則必須使用該接收器的服務帳戶。Logging 會自動為您建立及管理服務帳戶：

自 2023 年 5 月 22 日起，如果您建立接收器，但基礎資源沒有服務帳戶，Logging 會建立服務帳戶。Logging 會為基礎資源中的所有接收器使用相同的服務帳戶。資源可以是 Google Cloud 專案、機構、資料夾或帳單帳戶。
2023 年 5 月 22 日前，Logging 會為每個接收器建立服務帳戶。自 2023 年 5 月 22 日起，記錄功能會為基礎資源中的所有接收器使用共用服務帳戶。

接收器的寫入者身分是與該接收器相關聯的服務帳戶 ID。除非接收器寫入目前 Google Cloud 專案中的記錄檔 bucket，否則所有接收器都會有寫入者身分。寫入者身分中的電子郵件地址會識別主體，該主體必須有權將資料寫入目的地。

如要將記錄檔項目傳送至受服務範圍保護的資源，您必須將該接收器的服務帳戶新增至存取層級，然後指派至目標服務範圍。非匯總接收器則不需要。詳情請參閱 VPC Service Controls：Cloud Logging。

如要設定接收器權限，將資料流向目的地，請按照下列步驟操作：

控制台

如要取得接收器的服務帳戶資訊，請按照下列步驟操作：
1. 前往 Google Cloud 控制台的「Log Router」(記錄檔路由器) 頁面：
  前往「記錄檔路由器」
  
  如果您是使用搜尋列尋找這個頁面，請選取子標題為「Logging」的結果。
2. 選取「選單」，然後選取「查看接收器詳細資料」。寫入者身分會顯示在「接收器詳細資料」面板中。
3. 如果 writerIdentity 欄位的值包含電子郵件地址，請繼續下一個步驟。如果值為 None，則不需要設定目的地權限。
4. 將接收器的寫入者身分複製到剪貼簿。Writer Identity 可能會因接收器所屬的資源而異，但一律以 serviceAccount: 為前置字元。以下是寫入者身分的範例：
```
serviceAccount:service-123456789012@gcp-sa-logging.iam.gserviceaccount.com
```
將記錄資料寫入目標位置的權限授予接收器寫入者身分指定的主體：
1. 前往 Google Cloud 控制台的「IAM」(身分與存取權管理) 頁面：
  前往 IAM
  
  如果您是使用搜尋列尋找這個頁面，請選取子標題為「IAM & Admin」(IAM 與管理) 的結果。
2. 在 Google Cloud 控制台的工具列中，選取儲存匯總接收器目的地的專案。如果目的地是專案，請選取該專案。
3. 按一下「授予存取權」。
4. 輸入接收器寫入者身分指定的主體，然後授予 IAM 角色：
  - Google Cloud 專案：授予記錄寫入者角色 (roles/logging.logWriter)。具體來說，主體需要 logging.logEntries.route 權限。
  - 記錄檔值區：授予記錄檔值區寫入者角色 (roles/logging.bucketWriter)。
  - Cloud Storage 值區：授予Storage 物件建立者角色 (roles/storage.objectCreator)。
  - BigQuery 資料集：授予 BigQuery 資料編輯者角色 (roles/bigquery.dataEditor)。
  - Pub/Sub 主題 (包括 Splunk)：授予 Pub/Sub 發布者角色 (roles/pubsub.publisher)。

gcloud

確認您在包含目的地的Google Cloud 專案中具有「擁有者」存取權。如果您不具有接收器目的地位置的擁有者存取權，請要求專案擁有者將寫入者身分新增為主體。
如要取得接收器的服務帳戶相關資訊，請呼叫 gcloud logging sinks describe 方法。

使用下列指令之前，請先替換以下項目：
- SINK_NAME：記錄接收器的名稱。水槽名稱一經建立即無法變更。
執行 gcloud logging sinks describe 指令：
```
gcloud logging sinks describe SINK_NAME
```
如果接收器詳細資料包含標示為 writerIdentity 的欄位，請繼續下一個步驟。如果詳細資料不包含writerIdentity欄位，您就不需要為接收器設定目的地權限。
將接收器的寫入者身分複製到剪貼簿。以下說明寫入者身分：
```
serviceAccount:service-123456789012@gcp-sa-logging.iam.gserviceaccount.com
```
呼叫 gcloud projects add-iam-policy-binding 指令，將記錄資料寫入目的地的權限授予接收器的寫入者身分。

使用下列指令之前，請先替換以下項目：
- PROJECT_ID：專案的 ID。選取儲存匯總接收器目的地的專案。如果目的地是專案，請選取該專案。
- PRINCIPAL：要授予角色的主體 ID。主體 ID 通常採用以下格式： PRINCIPAL-TYPE:ID。例如：user:my-user@example.com。如需 PRINCIPAL 可使用的完整格式清單，請參閱「主要 ID」。
- ROLE：IAM 角色。根據記錄接收器的目的地，將 IAM 角色授予接收器的寫入者身分：
  - Google Cloud 專案：授予記錄寫入者角色 (roles/logging.logWriter)。具體來說，主體需要 logging.logEntries.route 權限。
  - 記錄檔值區：授予記錄檔值區寫入者角色 (roles/logging.bucketWriter)。
  - Cloud Storage 值區：授予Storage 物件建立者角色 (roles/storage.objectCreator)。
  - BigQuery 資料集：授予 BigQuery 資料編輯者角色 (roles/bigquery.dataEditor)。
  - Pub/Sub 主題 (包括 Splunk)：授予 Pub/Sub 發布者角色 (roles/pubsub.publisher)。
執行 gcloud projects add-iam-policy-binding 指令：
```
gcloud projects add-iam-policy-binding PROJECT_ID --member=PRINCIPAL --role=ROLE
```

REST

建議您使用 Google Cloud 控制台或 Google Cloud CLI，將角色授予服務帳戶。

後續步驟

瞭解如何在記錄值區中建立記錄檢視畫面。您可以透過記錄檢視畫面，授予主體唯讀存取權，存取記錄檔值區中儲存的部分記錄項目。
如要瞭解如何管理現有接收器，請參閱「將記錄檔傳送至支援的目的地：管理接收器」。
如果使用接收器轉送記錄時遇到問題，請參閱「轉送和接收器疑難排解」。
如要瞭解如何在目的地中查看記錄，以及記錄的格式和組織方式，請參閱「查看接收器目的地中的記錄檔」一文。

彙整機構和資料夾層級記錄，並將其轉送至支援的目的地

事前準備

Console

gcloud

REST

建立匯總接收器

控制台

gcloud

REST

匯總接收器的篩選器

選取記錄來源

選取受監控的資源

選取記錄項目樣本

設定目的地權限

控制台

gcloud

REST

後續步驟