對於使用 Cloud Datastore 代管的匯入與匯出服務建立的 Cloud Datastore 匯出檔案，BigQuery 支援從這類檔案載入資料的功能。您可以使用代管的匯入與匯出服務，將 Cloud Datastore 實體匯出至 Cloud Storage 值區，然後在 BigQuery 中以資料表的形式載入匯出檔案。
如要瞭解如何建立 Cloud Datastore 匯出檔案，請參閱 Cloud Datastore 說明文件中的匯出與匯入實體一節。關於如何排定匯出時程，請參閱排定匯出時程一文。
您可以在 API 中設定 projectionFields 屬性或在 CLI 中使用 --projection_fields 標記，來控制 BigQuery 要載入的屬性。
如果您想略過載入程序，可以將匯出檔案設為外部資料來源，直接查詢匯出檔案。詳情請參閱外部資料來源。
將資料從 Cloud Storage 載入至 BigQuery 資料表時，包含該資料表的資料集必須位於與 Cloud Storage 值區相同的地區或多地區位置。
限制
當您在 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 的所有欄位會遭截斷。
所需權限
將資料載入 BigQuery 時，您必須具備相關權限，以便執行載入工作以及將資料載入新的或現有的 BigQuery 資料表和分區。如要載入 Cloud Storage 中的資料，您也要有權限存取包含資料的值區。
BigQuery 權限
您至少要具備下列權限，才能將資料載入 BigQuery。不管您要將資料載入或附加到資料表或分區，還是覆寫資料表或分區資料，都需要這些權限。
bigquery.tables.createbigquery.tables.updateDatabigquery.jobs.create
以下是具有 bigquery.tables.create 和 bigquery.tables.updateData 權限的預先定義 Cloud IAM 角色：
bigquery.dataEditorbigquery.dataOwnerbigquery.admin
以下是具有 bigquery.jobs.create 權限的預先定義 Cloud IAM 角色：
bigquery.userbigquery.jobUserbigquery.admin
此外，具備 bigquery.datasets.create 權限的使用者在建立資料集時，會獲得 bigquery.dataOwner 存取權。
bigquery.dataOwner 存取權可讓使用者透過載入工作建立及更新資料集中的資料表。
如要進一步瞭解 BigQuery 中的 Cloud IAM 角色和權限，請參閱存取權控管。
Cloud Storage 權限
您必須具備 storage.objects.get 權限，才能從 Cloud Storage 值區載入資料。如要使用 URI 萬用字元，您必須同時具備 storage.objects.list 權限。
只要授予預先定義的 Cloud IAM 角色 storage.objectViewer，即可提供 storage.objects.get 與 storage.objects.list 權限。
載入 Cloud Datastore 匯出服務資料
如何載入 Cloud Datastore 匯出中繼資料檔案中的資料：
主控台
在 GCP Console 中開啟 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或export[NUM].export_metadata，例如default_namespace_kind_Book.export_metadata。在這個範例中，Book是種類名稱，default_namespace_kind_Book是由 Cloud Datastore 產生的檔案名稱。 - 在「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]，然後在來源欄位中輸入 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 選項一節。
CLI
使用 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 管理員備份功能匯出 Cloud Datastore 資料時，副檔名會是 .export_metadata，而不是 .backup_info。將資料匯入 BigQuery 時，可使用 .backup_info 檔案或 .export_metadata 檔案，直到 Cloud Datastore 管理員備份服務不能再使用為止。
將 Cloud Datastore 資料附加到資料表或使用 Cloud Datastore 資料覆寫資料表
將 Cloud Datastore 匯出資料載入 BigQuery 時，您可以建立新資料表來儲存資料，也可以覆寫現有資料表，但無法將 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 Console 中開啟 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] (覆寫資料表)。
按一下 [建立資料表]。
傳統版 UI
- 前往傳統 BigQuery 網頁版 UI。
前往 BigQuery 網頁版 UI - 在導覽面板中，將游標移至特定資料集上，按一下向下箭頭圖示 ，然後點選 [Create new table]。載入資料的程序與建立空白資料表的程序相同。
- 在「Create Table」(建立資料表) 頁面的「Source Data」(來源資料) 部分中：
- 保持選取 [Create from source] (透過來源建立)。
- 在「Location」中，選取 [Cloud Storage]，然後在來源欄位中輸入 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] (建立資料表)。
CLI
搭配 --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。 |
STRING |
