對於使用 Cloud Datastore 代管的匯入與匯出服務建立的 Cloud Datastore 匯出檔案，Google BigQuery 支援這類檔案的載入資料。您可以使用代管的匯入與匯出服務，將 Cloud Datastore 實體匯出至 Cloud Storage 值區，然後在 BigQuery 中以資料表的形式載入匯出檔案。
如要瞭解如何建立 Cloud Datastore 匯出檔案，請參閱 Cloud Datastore 說明文件中的匯出與匯入實體一節。如要瞭解如何排定匯出時程，請參閱排定匯出時程一文。
您可以在 API 中設定 projectionFields 屬性或在 CLI 中使用 --projection_fields 標記，以決定 BigQuery 要載入的屬性。
如果您想略過載入程序，可以將匯出檔案設為外部資料來源，直接查詢匯出檔案。詳情請參閱外部資料來源一文。
將資料從 Cloud Storage 載入至 BigQuery 資料表時，包含該資料表的資料集必須位於與 Cloud Storage 值區相同的地區或多地區位置。
所需權限
如果您要將資料載入至 BigQuery，您必須擁有專案或資料集層級的權限，才能將資料載入至新的或現有的 BigQuery 資料表與分區。如果是從 Cloud Storage 載入檔案，您還需要擁有包含您的資料的值區存取權。
BigQuery 權限
如果您要將資料從 Cloud Storage 載入至 BigQuery，您必須獲得專案層級或資料集層級的 bigquery.dataOwner 或 bigquery.dataEditor 角色授權。這兩種角色授予使用者與群組將資料載入至新資料表或將資料附加至現有資料表或覆寫現有資料表的權限。
授予專案層級的角色可讓使用者或群組有權將資料載入至專案中任何資料集的資料表。授予資料集層級的角色可讓使用者或群組只能將資料載入至該資料集的資料表。
如需設定資料集存取權的詳細資訊，請參閱控管資料集存取權。如要進一步瞭解 BigQuery 中的身分與存取權管理 (IAM) 角色，請參閱存取權控管。
Cloud Storage 權限
若要從 Cloud Storage 值區載入資料，您必須被授予專案層級的 storage.objects.get 授權或該個別值區的授權。如要使用 URI 萬用字元，您也必須具備 storage.objects.list 權限。
授予預先定義的身分與存取權管理角色 storage.objectViewer，即可提供 storage.objects.get 與 storage.objects.list 權限。
限制
當您在 BigQuery 中載入 Cloud Datastore 匯出檔案中的資料時，請注意下列幾點限制：
- 指定 Cloud Datastore 匯出檔案時，不得在 Cloud Storage URI 中使用萬用字元。
- 載入 Cloud Datastore 匯出檔案中的資料時，您只能指定一個 Cloud Storage URI。
- 您無法在已定義結構定義的現有資料表中附加 Cloud Datastore 匯出資料。
- Cloud Datastore 匯出資料中的實體必須有一致的結構定義，這樣才能順利載入匯出資料。
- 假如不指定實體篩選器，匯出的資料就無法載入 BigQuery。匯出要求的實體篩選器中必須包含一或多個種類名稱。
- Cloud Datastore 匯出檔案的欄位大小上限為 64 KB。載入 Cloud Datastore 匯出檔案時，大於 64 KB 的所有欄位會遭截斷。
載入 Cloud Datastore 匯出服務資料
如何載入 Cloud Datastore 匯出中繼資料檔案中的資料：
主控台
在 GCP 主控台中開啟 BigQuery 網頁版 UI。
在導覽面板的「Resources」(資源) 部分，展開您的專案並選取資料集。按一下 [Create table] (建立資料表)。載入資料的程序與建立空白資料表的程序相同。
在「Create table」(建立資料表) 頁面的「Source」(來源) 區段中：
在「Create table from」(使用下列資料建立資料表) 部分，選取 [Cloud Storage]
在「Source」(來源) 欄位中輸入 Cloud Storage URI。Cloud Storage 值區的位置必須與要建立的表格所在的資料集位置相同。Cloud Datastore 匯出檔案的 URI 結尾應為
[KIND_NAME].export_metadata，例如default_namespace_kind_Book.export_metadata。在這個範例中，Book是種類名稱，default_namespace_kind_Book是由 Cloud Datastore 產生的檔案名稱。確認您已在 Cloud Storage URI 中指定
[KIND_NAME]。如果未在該 URI 中指定[KIND_NAME]，您會收到以下錯誤：does not contain valid backup metadata. (error code: invalid)。在「File format」(檔案格式) 部分中，選取 [Cloud Datastore Backup] (Cloud Datastore 備份)。
在「Create table」(建立資料表) 頁面的「Destination」(目的地) 區段中：
在「Dataset name」(資料集名稱) 部分選擇適當的資料集。
在「Table name」(資料表名稱) 欄位中，輸入您在 BigQuery 中建立資料表時使用的名稱。
確認「Table type」(資料表類型) 設為 [Native table] (原生資料表)。
在「結構定義」區段中，您不必執行任何操作。系統會根據 Cloud Datastore 匯出檔案推測結構定義。
在「Advanced options」(進階選項) 區段中選取適合的項目，然後按一下 [Create table] (建立資料表)。如要瞭解可用的選項，請參閱 Cloud Datastore 選項一節。
傳統版 UI
- 前往傳統 BigQuery 網頁版 UI。
前往 BigQuery 網頁版 UI - 在導覽面板中，將滑鼠游標懸停在資料集上，然後依序點選向下箭號圖示
> [Create new table] (建立新資料表)。載入資料的程序與建立空白資料表的程序相同。 - 在「Create Table」(建立資料表) 頁面的「Source Data」(來源資料) 部分中：
- 保持選取 [Create from source] (透過來源建立)。
- 在「Location」(位置) 中，選取 [Cloud Storage]，並在在「Source」(來源) 欄位中輸入 Cloud Storage URI。Cloud Storage 值區的位置必須與要建立的表格所在的資料集位置相同。Cloud Datastore 匯出檔案的 URI 結尾應為
[KIND_NAME].export_metadata，例如default_namespace_kind_Book.export_metadata。在這個範例中，Book是種類名稱，default_namespace_kind_Book是由 Cloud Datastore 產生的檔案名稱。確認您已在 Cloud Storage URI 中指定
[KIND_NAME]。如果未在該 URI 中指定[KIND_NAME]，您會收到以下錯誤：does not contain valid backup metadata. (error code: invalid)。 - 在「File format」(檔案格式) 部分中，選取 [Cloud Datastore Backup] (Cloud Datastore 備份)。
- 在「Create Table」(建立表格) 頁面的「Destination Table」(目的地表格) 區段中：
- 在「Table name」(表格名稱) 部分選擇適當的資料集，然後在表格名稱欄位中，輸入要在 BigQuery 中建立的表格名稱。
- 確認「Table type」(資料表類型) 設為 [Native table] (原生資料表)。
- 在「結構定義」區段中，您不必執行任何操作。系統會根據 Cloud Datastore 匯出檔案推測結構定義。
- 在「Options」(選項) 區段中選取適合的項目，然後按一下 [Create Table] (建立資料表)。如要瞭解可用的選項，請參閱 Cloud Datastore 選項一節。
指令列
使用 bq load 指令並將 source_format 設為 DATASTORE_BACKUP。提供 --location 標記並將值設為您的位置。
bq --location=[LOCATION] load --source_format=[FORMAT] [DATASET].[TABLE] [PATH_TO_SOURCE]
其中：
[LOCATION]是您的位置。--location是選用標記。例如，如果您在東京地區使用 BigQuery，請將標記的值設為asia-northeast1。您可以使用 .bigqueryrc 檔案設定位置的預設值。[FORMAT]是DATASTORE_BACKUP。[DATASET]是特定資料集，該資料集包含您要在當中載入資料的資料表。[TABLE]是您要在當中載入資料的資料表。如果該資料表不存在，系統就會建立新資料表。[PATH_TO_SOURCE]是 Cloud Storage URI。
舉例來說，下列指令會在名為 book_data 的資料表中載入 gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata Cloud Datastore 匯出檔案。
mybucket 與 mydataset 建立於 US 多地區位置。
bq --location=US load --source_format=DATASTORE_BACKUP mydataset.book_data gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata
API
設定下列屬性，以便使用 API 載入 Cloud Datastore 匯出資料。
建立指向 Cloud Storage 中來源資料的載入工作。
來源 URI 必須完整且符合下列格式：gs://[BUCKET]/[OBJECT]。檔案 (物件) 名稱的結尾必須是
[KIND_NAME].export_metadata。您只能針對 Cloud Datastore 匯出檔案指定一個 URI，且不得使用萬用字元。將 configuration.load.sourceFormat 屬性設為
DATASTORE_BACKUP，藉此指定資料格式。
Cloud Datastore 管理員備份
使用 Cloud Datastore Admin 備份功能匯出 Cloud Datastore 資料時，需注意副檔名會由 .export_metadata 替換為 .backup_info。匯入資料到 BigQuery 時，可使用 .backup_info 檔案或 .export_metadata 檔案，直到 Cloud Datastore Admin 備份服務不能再使用為止。
使用 Cloud Datastore 資料附加或覆寫資料表
在 BigQuery 中載入 Cloud Datastore 匯出資料時，您可以建立新資料表來儲存資料，也可以覆寫現有資料表，但無法在現有資料表中附加 Cloud Datastore 匯出資料。
如果您試圖在現有資料表中附加 Cloud Datastore 匯出資料，就會發生以下錯誤：Cannot append a datastore backup to a table
that already has a schema. Try using the WRITE_TRUNCATE write disposition to
replace the existing table。
如何使用 Cloud Datastore 匯出資料覆寫現有資料表：
主控台
- 在 GCP 主控台中開啟 BigQuery 網頁版 UI。 前往 BigQuery 網頁版 UI
- 在導覽面板的「Resources」(資源) 部分，展開您的專案並選取資料集。按一下 [Create table] (建立資料表)。載入資料的程序與建立空白資料表的程序相同。
在「Create table」(建立資料表) 頁面的「Source」(來源) 區段中：
在「Create table from」(使用下列資料建立資料表) 部分，選取 [Cloud Storage]
在「Source」(來源) 欄位中輸入 Cloud Storage URI。Cloud Storage 值區的位置必須與要建立的表格所在的資料集位置相同。Cloud Datastore 匯出檔案的 URI 結尾應為
[KIND_NAME].export_metadata，例如default_namespace_kind_Book.export_metadata。在這個範例中，Book是種類名稱，default_namespace_kind_Book是由 Cloud Datastore 產生的檔案名稱。確認您已在 Cloud Storage URI 中指定
[KIND_NAME]。如果未在該 URI 中指定[KIND_NAME]，您會收到以下錯誤：does not contain valid backup metadata. (error code: invalid)。在「File format」(檔案格式) 部分中，選取 [Cloud Datastore Backup] (Cloud Datastore 備份)。
在「Create table」(建立資料表) 頁面的「Destination」(目的地) 區段中：
在「Dataset name」(資料集名稱) 部分選擇適當的資料集。
在「Table name」(資料表名稱) 欄位中，輸入您在 BigQuery 中建立資料表時使用的名稱。
確認「Table type」(資料表類型) 設為 [Native table] (原生資料表)。
在「結構定義」區段中，您不必執行任何操作。系統會根據 Cloud Datastore 匯出檔案推測結構定義。
在「Advanced options」(進階選項) 部分的「Write preference」(寫入偏好設定) 選取 [Overwrite table] (覆寫資料表)。
按一下 [Create table] (建立資料表)。
傳統版 UI
- 前往傳統 BigQuery 網頁版 UI。
前往 BigQuery 網頁版 UI - 在導覽面板中，將滑鼠游標懸停在資料集上，然後依序點選向下箭號圖示 > [Create new table] (建立新資料表)。載入資料的程序與建立空白資料表的程序相同。
- 在「Create Table」(建立資料表) 頁面的「Source Data」(來源資料) 部分中：
- 保持選取 [Create from source] (透過來源建立)。
- 在「Location」(位置) 中，選取 [Cloud Storage]，並在在「Source」(來源) 欄位中輸入 Cloud Storage URI。Cloud Storage 值區的位置必須與要建立的表格所在的資料集位置相同。Cloud Datastore 匯出檔案的 URI 結尾應為
[KIND_NAME].export_metadata，例如default_namespace_kind_Book.export_metadata。在這個範例中，Book是種類名稱，default_namespace_kind_Book是由 Cloud Datastore 產生的檔案名稱。確認您已在 Cloud Storage URI 中指定
[KIND_NAME]。如果未在該 URI 中指定[KIND_NAME]，您會收到以下錯誤：does not contain valid backup metadata. (error code: invalid)。 - 在「File format」(檔案格式) 部分中，選取 [Cloud Datastore Backup] (Cloud Datastore 備份)。
- 在「Create Table」(建立表格) 頁面的「Destination Table」(目的地表格) 區段中：
- 在「資料表名稱」部分中選擇適當的資料集，然後在資料表名稱欄位中輸入要覆寫的資料表名稱。
- 確認「Table type」(資料表類型) 設為 [Native table] (原生資料表)。
- 在「結構定義」區段中，您不必執行任何操作。系統會根據 Cloud Datastore 匯出檔案推測結構定義。
- 在「Options」(選項) 部分中，將「Write preference」(寫入偏好設定) 設為 [Overwrite table] (覆寫資料表)。
- 按一下 [Create Table] (建立資料表)。
指令列
搭配 --replace 標記使用 bq load 指令，並將 source_format 設為 DATASTORE_BACKUP。加上 --location 標記並將值設為您的位置。
.
bq --location=[LOCATION] load --source_format=[FORMAT] --replace [DATASET].[TABLE] [PATH_TO_SOURCE]
其中：
[LOCATION]是您的位置。--location是選用標記。例如，如果您在東京地區使用 BigQuery，請將標記的值設為asia-northeast1。您可以使用 .bigqueryrc 檔案設定位置的預設值。[FORMAT]是DATASTORE_BACKUP。[DATASET]是特定資料集，該資料集包含您要在當中載入資料的資料表。[TABLE]是您要覆寫的資料表。[PATH_TO_SOURCE]是 Cloud Storage URI。
舉例來說，下列指令會載入 gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata Cloud Datastore 匯出檔案並覆寫名為 book_data 的資料表：
bq load --source_format=DATASTORE_BACKUP --replace mydataset.book_data gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata
API
設定下列屬性，以便透過 API 載入資料。
建立指向 Cloud Storage 中來源資料的載入工作。
來源 URI 必須完整且符合下列格式：gs://[BUCKET]/[OBJECT]。檔案 (物件) 名稱的結尾必須是
[KIND_NAME].export_metadata。您只能針對 Cloud Datastore 匯出檔案指定一個 URI，且不得使用萬用字元。將 configuration.load.sourceFormat 屬性設為
DATASTORE_BACKUP，藉此指定資料格式。將 configuration.load.writeDisposition 屬性設為
WRITE_TRUNCATE，藉此指定寫入配置。
Cloud Datastore 選項
如要變更 BigQuery 剖析 Cloud Datastore 匯出資料的方式，請在 UI、CLI 或 API 中指定額外選項。
| CSV 選項 | 傳統版 UI 選項 | CLI 標記 | BigQuery API 屬性 | 說明 |
|---|---|---|---|---|
| Projection fields (投影欄位) | 無 | --projection_fields |
projectionFields | 逗號分隔的清單，用來指定要從 Cloud Datastore 匯出檔案載入至 BigQuery 的實體屬性。屬性名稱有大小寫之分且必須為頂層屬性。如果不指定屬性，BigQuery 會載入所有屬性。如果系統在 Cloud Datastore 匯出資料中找不到任一指定屬性，工作結果中就會出現無效錯誤。預設值為 ''。 |
| Number of bad records allowed (允許的損壞紀錄數量) | Number of errors allowed | --max_bad_records |
maxBadRecords | (選用) BigQuery 在執行工作時可忽略的損壞記錄數量上限。如果損壞記錄的數量超過這個值，工作結果中就會出現無效錯誤。預設值為 0，表示所有紀錄都必須有效。 |
資料類型轉換
BigQuery 會將 Cloud Datastore 匯出檔案中各個實體的資料轉換成 BigQuery 的資料類型。下表說明不同資料類型的轉換對應關係。
| Cloud Datastore 資料類型 | BigQuery 資料類型 |
|---|---|
| Blob | BigQuery 會在載入資料時捨棄這類值。 |
| Blobstore 金鑰 | STRING |
| 布林值 | BOOLEAN |
| 類別 | STRING |
| Datastore 金鑰 | RECORD |
| 日期和時間 | TIMESTAMP |
| 電子郵件 | STRING |
| 嵌入實體 | RECORD |
| 浮點數 | FLOAT |
| 地理點 |
RECORD
[{"lat","DOUBLE"},
{"long","DOUBLE"}]
|
| IM 控點 | STRING |
| 整數 | INTEGER |
| 連結 | STRING |
| 電話號碼 | STRING |
| 郵遞地址 | STRING |
| Rating | INTEGER |
| 簡短 Blob | BigQuery 會在載入資料時捨棄這類值。 |
| 字串 | STRING (截斷至 64 KB) |
| 使用者 |
RECORD
[{"email","STRING"}
{"userid","STRING"}]
|
Datastore 金鑰屬性
Cloud Datastore 中每個實體都有專屬金鑰，當中包含命名空間和路徑等資訊。BigQuery 會為每個金鑰建立 RECORD 類型的資料，並透過巢狀欄位整理不同類型的資訊 (如下表所示)。
| 金鑰屬性 | 說明 | BigQuery 資料類型 |
|---|---|---|
__key__.app |
Cloud Datastore 應用程式名稱。 | STRING |
__key__.id |
實體的 ID 或 null (如果有設定 __key__.name)。 |
INTEGER |
__key__.kind |
實體的種類。 | STRING |
__key__.name |
實體的名稱或 null (如果有設定 __key__.id)。 |
STRING |
__key__.namespace |
如果 Cloud Datastore 應用程式使用自訂命名空間，這個屬性就是實體的命名空間。如果未使用自訂命名空間，則會以空白字串代表預設命名空間。 | STRING |
__key__.path |
經過整併的實體祖系路徑，其中包含一系列根實體和實體本身等項目的種類-識別碼組合，例如："Country", "USA", "PostalCode",
10011, "Route", 1234. |
字串 |
