匯出記錄的 BigQuery 結構定義

已匯出記錄的 BigQuery 表格結構定義是以 LogEntry 類型的結構和記錄酬載的內容為基礎。Stackdriver Logging 也會運用一些特殊規則,縮短稽核記錄的 BigQuery 結構定義欄位名稱。您可以在 BigQuery 網頁版 UI 中選取具有已匯出記錄項目的資料表,查看資料表結構定義。

欄位命名慣例

以下提供了幾個適用於記錄項目欄位的命名慣例:

  • 如果是屬於 LogEntry 類型中的記錄項目欄位,則對應的 BigQuery 欄位名稱與記錄項目欄位完全相同。
  • 如果是使用者提供的欄位,則會將字母大小寫標準化為小寫,但仍保留命名。

    • 如果是結構化酬載中的欄位,只要當中沒有 @type 指定碼,則會將字母大小寫標準化為小寫,但仍保留命名。

      如要瞭解內含 @type 指定碼的結構化酬載,請參閱具有 @type 的酬載欄位一節。

以下範例說明如何運用這些命名慣例:

記錄項目欄位 LogEntry 類型對應 BigQuery 欄位名稱
insertId insertId insertId
textPayload textPayload textPayload
httpRequest.status httpRequest.status httpRequest.status
httpRequest.requestMethod.GET httpRequest.requestMethod.[ABC] httpRequest.requestMethod.get
resource.labels.moduleid resource.labels.[ABC] resource.labels.moduleid
jsonPayload.MESSAGE jsonPayload.[ABC] jsonPayload.message
jsonPayload.myField.mySubfield jsonPayload.[ABC].[XYZ] jsonPayload.myfield.mysubfield

如果結構化欄位包含 @type 指定碼,結構化酬載欄位與 BigQuery 欄位名稱的對應會比較複雜。我們會在下面的章節中討論。

具有 @type 的酬載欄位

本節將探討酬載中含有類型指定碼 (@type 欄位) 的記錄項目所對應的特殊 BigQuery 結構定義欄位名稱,這也包括儲存在 BigQuery 中的已匯出稽核記錄項目。本節將以稽核記錄項目的 protoPayload 欄位為例,說明為什麼該欄位可能會對應到 BigQuery 結構定義欄位 protopayload_auditlog

結構定義命名規則

記錄項目中的酬載可包含結構化資料,而結構化資料可擁有巢狀結構化欄位。任何結構化欄位都可以包含下列格式的選用類型指定碼

@type: type.googleapis.com/[TYPE]

系統通常會為具有類型指定碼的結構化欄位指定 BigQuery 欄位名稱,且會在欄位名稱後附加 [TYPE]。

例如,下表顯示頂層結構化酬載欄位與 BigQuery 欄位名稱的對應:

酬載 酬載 @type 酬載欄位 BigQuery 欄位名稱
jsonPayload (無) statusCode jsonPayload.statusCode
jsonPayload type.googleapis.com/abc.Xyz statusCode jsonPayload_abc_xyz.statuscode
protoPayload (無) statusCode protoPayload.statuscode
protoPayload type.googleapis.com/abc.Xyz statusCode protopayload_abc_xyz.statuscode

如果 jsonPayloadprotoPayload 包含其他結構化欄位,則這些內部欄位的對應方式如下:

  • 如果巢狀結構化欄位沒有 @type 指定碼,其 BigQuery 欄位名稱會與原始欄位名稱相同,但會標準化為小寫字母。
  • 如果巢狀結構化欄位含有 @type 指定碼,其 BigQuery 欄位名稱則為欄位名稱後附加上 [TYPE] (重新拼寫),且會標準化為小寫字母。

如果是含有類型指定碼的欄位,上述規則會有一些例外:

  • 在 App Engine 要求記錄中,即使酬載具有類型指定碼,匯出到 BigQuery 的記錄酬載名稱也會是 protoPayload,如查詢的 App Engine 範例記錄查詢所示。

  • Stackdriver Logging 會運用一些特殊規則,縮短稽核記錄的 BigQuery 結構定義欄位名稱。我們將在本頁面的匯出的稽核記錄結構定義欄位一節中討論。

範例

這個範例顯示結構化酬載欄位在匯出至 BigQuery 時的命名與使用方式。

假設記錄項目酬載的結構化方式如下:

jsonPayload: {
  name_a: {
    sub_a: "A value"
  }
  name_b: {
    @type: "type.googleapis.com/google.cloud.v1.SubType"
    sub_b: 22
  }
}

BigQuery 欄位的對應如下:

  • jsonPayloadname_a 欄位會結構化,但這兩個欄位沒有 @type 指定碼,其 BigQuery 名稱將分別為 jsonPayloadname_a

  • sub_asub_b 欄位不會結構化,因此,其 BigQuery 名稱分別為 sub_asub_b

  • name_b 欄位有 @type 指定碼,且指定碼的 [TYPE] 為 google.cloud.v1.SubType。因此,這個欄位的 BigQuery 名稱為 name_b_google_cloud_v1_subtype

簡單來說,記錄項目的酬載具有以下 5 種 BigQuery 名稱定義:

jsonPayload
jsonPayload.name_a
jsonPayload.name_a.sub_a
jsonPayload.name_b_google_cloud_v1_subtype
jsonPayload.name_b_google_cloud_v1_subtype.sub_b

匯出的稽核記錄結構定義欄位

如果您未使用已匯出到 BigQuery 的稽核記錄,可跳過這一節。

稽核記錄酬載欄位 protoPayload.requestprotoPayload.responseprotoPayload.metadata 都有 @type 指定碼,不過系統會將這些欄位視為 JSON 資料。也就是說,這些欄位的 BigQuery 結構定義名稱為附加 Json 的欄位名稱,且名稱中包含 JSON 格式的字串資料。

這兩組稽核記錄酬載欄位名稱如下表所示:

記錄項目欄位 BigQuery 欄位名稱
protoPayload protopayload_auditlog
protopayload.metadata protopayload_auditlog.metadataJson
protoPayload.serviceData protopayload_auditlog.servicedata_v1_bigquery
範例:protopayload_auditlog.servicedata_v1_bigquery.tableInsertRequest
protoPayload.request protopayload_auditlog.requestJson
protoPayload.response protopayload_auditlog.responseJson

請注意,serviceData 命名慣例僅適用於由 BigQuery 產生、且接著從 Stackdriver Logging 匯出到 BigQuery 的稽核記錄。這些稽核記錄項目包含的 serviceData 欄位都含有以下 @type 指定碼:type.googleapis.com/google.cloud.bigquery.logging.v1.auditdata

範例

由 BigQuery 產生一個名稱如下的稽核記錄項目:

protoPayload.serviceData.tableInsertRequest

如果這個記錄項目接著匯出至 BigQuery,將會如何參照 tableInsertRequest 欄位?縮短名稱之前,對應的匯出欄位名稱為:

protopayload_google_cloud_audit_auditlog.servicedata_google_cloud_bigquery_logging_v1_auditdata.tableInsertRequest

名稱縮短後,系統會參照 BigQuery 資料表中的相同欄位,如下所示:

protopayload_auditlog.servicedata_v1_bigquery.tableInsertRequest

查看稽核記錄

如要使用 BigQuery 網頁版 UI 查看稽核記錄,請選取具有已匯出記錄項目的資料表。