排定資料匯出作業

本頁面說明如何排定 Cloud Firestore 資料的匯出作業。如要定期執行匯出作業，建議使用 Cloud Functions 和 Cloud Scheduler。

注意： 從 Cloud Firestore 匯出資料時，每項匯出的文件將產生一項讀取作業。不過，這些讀取作業不會顯示在主控台的用量部分。因此設定週期性匯出作業前，請務必瞭解這點，以免產生非預期的費用。

事前準備

排定受管理資料匯出作業前，必須先完成下列事項：

1. 啟用 Google Cloud 專案的計費功能。只有已啟用計費功能的 Google Cloud 專案才能使用匯出及匯入功能。
   注意：Firebase 專案必須採用 Blaze 方案，才能使用代管匯出與匯入功能。Google Cloud 的計費功能啟用之後，Firebase 專案會自動升級為 Blaze 方案。
2. 匯出作業需要目的地 Cloud Storage 值區。在 Cloud Firestore 資料庫位置附近的位置建立 Cloud Storage 值區。您無法透過「要求者付費」值區執行匯出作業。

建立 Cloud 函式和 Cloud Scheduler 工作

請按照下列步驟建立 Node.js Cloud 函式，以啟動 Cloud Firestore 資料匯出作業，並建立 Cloud Scheduler 工作來呼叫該函式：

Firebase CLI

1. 安裝 Firebase CLI。在新目錄中，為 Cloud Functions 初始化 CLI：

   firebase init functions --project PROJECT_ID

   1. 選擇「JavaScript」做為語言。
   2. 視需要啟用 ESLint。
   3. 輸入 y 即可安裝依附元件。

2. 將 functions/index.js 檔案中的程式碼替換為下列內容：

   const functions = require('firebase-functions');
   const firestore = require('@google-cloud/firestore');
   const client = new firestore.v1.FirestoreAdminClient();
   
   // Replace BUCKET_NAME
   const bucket = 'gs://BUCKET_NAME';
   
   exports.scheduledFirestoreExport = functions.pubsub
                                               .schedule('every 24 hours')
                                               .onRun((context) => {
   
     const projectId = process.env.GCP_PROJECT;
     const databaseName = 
       client.databasePath(projectId, '(default)');
   
     return client.exportDocuments({
       name: databaseName,
       outputUriPrefix: bucket,
       // Leave collectionIds empty to export all collections
       // or set to a list of collection IDs to export,
       // collectionIds: ['users', 'posts']
       collectionIds: []
       })
     .then(responses => {
       const response = responses[0];
       console.log(`Operation Name: ${response['name']}`);
     })
     .catch(err => {
       console.error(err);
       throw new Error('Export operation failed');
     });
   });
   index.js

3. 在上述程式碼中，修改以下內容：
   • 請將 BUCKET_NAME 替換為您的值區名稱。
   • 修改 every 24 hours，設定匯出時間表。請使用 AppEngine cron.yaml 語法或 Unix-cron 格式 (* * * * *)。

   • 修改 collectionIds: []，只匯出指定的集合群組。請保持原樣，匯出所有集合。

     注意：如果您匯出所有集合，後續的匯入作業都必須匯入匯出資料檔案中的所有集合。

4. 部署排定的函式：

   firebase deploy --only functions

GCP 控制台

建立 Cloud 函式

1. 前往 GCP Console 的「Cloud Functions」頁面：

   前往「Cloud Functions」頁面

2. 按一下「建立函式」
3. 請輸入函式名稱，例如 firestoreExport
4. 在「觸發條件」下方，選取「Cloud Pub/Sub」
5. 在「主題」下方，選取「建立新主題」。輸入 Pub/Sub 主題的名稱，例如 initiateFirestoreExport。建立 Cloud Scheduler 工作時，請記下主題名稱，
6. 在「原始碼」下方，選取「內嵌編輯器」。在 index.js 下方輸入下列程式碼：

   const firestore = require('@google-cloud/firestore');
   const client = new firestore.v1.FirestoreAdminClient();
   // Replace BUCKET_NAME
   const bucket = 'gs://BUCKET_NAME'
   
   exports.scheduledFirestoreExport = (event, context) => {
     const databaseName = client.databasePath(
       process.env.GCP_PROJECT,
       '(default)'
     );
   
     return client
       .exportDocuments({
         name: databaseName,
         outputUriPrefix: bucket,
         // Leave collectionIds empty to export all collections
         // or define a list of collection IDs:
         // collectionIds: ['users', 'posts']
         collectionIds: [],
       })
       .then(responses => {
         const response = responses[0];
         console.log(`Operation Name: ${response['name']}`);
         return response;
       })
       .catch(err => {
         console.error(err);
       });
   };

   在上述程式碼中，修改以下內容：
   • 請將 BUCKET_NAME 替換為您的值區名稱。

   • 修改 collectionIds: []，只匯出指定的集合群組。請保持原樣，匯出所有集合。

     注意：如果您匯出所有集合，後續的匯入作業都必須匯入匯出資料檔案中的所有集合。
7. 在 package.json 下方，新增下列依附元件：

   {
     "dependencies": {
       "@google-cloud/firestore": "^1.3.0"
     }
   }

8. 在「要執行的函式」下方，輸入 scheduledFirestoreExport，也就是 index.js 中的函式名稱。
9. 按一下「建立」來部署 Cloud 函式。

建立 Cloud Scheduler 工作

接著，建立 Cloud Scheduler 工作來呼叫 Cloud 函式：

1. 前往 GCP Console 中的「Cloud Scheduler」頁面：

   前往 Cloud Scheduler

2. 按一下 [Create Job] (建立工作)。
3. 輸入工作的「Name」(名稱)，例如 scheduledFirestoreExport。
4. 輸入「頻率」，例如 every 24 hours。
5. 選取時區。
6. 在「Target」下方，選取「Pub/Sub」。在「主題」欄位中，輸入您在 Cloud 函式旁邊定義的 Pub/Sub 主題名稱，也就是上方範例中的 initiateFirestoreExport。
7. 在「Payload」欄位中輸入 start export。工作需要定義酬載，但上述 Cloud 函式實際上不會使用這個值。
8. 點選「建立」。

您目前已部署 Cloud 函式和 Cloud Scheduler 工作，但 Cloud 函式仍需具備存取權限才能執行匯出作業。

設定存取權限

接下來，授予 Cloud 函式權限以開始匯出作業，並寫入 GCS 值區。

此 Cloud 函式使用專案的預設服務帳戶來驗證和授權其匯出作業。建立專案時，系統會為您建立下列名稱的預設服務帳戶：

[e-mail]

這個服務帳戶需要權限才能啟動匯出作業，以及寫入 Cloud Storage 值區。如要授予這些權限，請將下列身分與存取權管理角色指派給預設服務帳戶：

• Cloud Datastore Import Export Admin
  注意：這個 Datastore 角色也會授予 Cloud Firestore 的權限。
• 值區的 Owner 或 Storage Admin 角色

您可以使用 gcloud 和 gsutil 指令列工具來指派這些角色。

如果尚未安裝，您可以透過 Google Cloud Platform 控制台中的 Cloud Shell 存取這些工具：
啟動 Cloud Shell

1. 指派 Cloud Datastore Import Export Admin 角色。替換 PROJECT_ID，然後執行下列指令：

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member serviceAccount:[e-mail] \
       --role roles/datastore.importExportAdmin
   

2. 為值區指派儲存空間管理員角色。替換 PROJECT_ID 和 BUCKET_NAME，然後執行下列指令：

   gsutil iam ch serviceAccount:[e-mail]:admin \
       gs://BUCKET_NAME
   

如果您停用或刪除 App Engine 預設服務帳戶，App Engine 應用程式就無法存取 Cloud Firestore 資料庫。如果您已停用 App Engine 服務帳戶，可以重新啟用，請參閱啟用服務帳戶。如果您在過去 30 天內刪除了 App Engine 服務帳戶，可以還原服務帳戶，請參閱取消刪除服務帳戶一節。

測試 Cloud Scheduler 工作和 Cloud 函式

您可以在 Google Cloud Platform Console 的「Cloud Scheduler」頁面中測試 Cloud Scheduler 工作。

1. 前往 GCP 主控台的「Cloud Scheduler」頁面。
   前往 Cloud Scheduler

2. 在新 Cloud Scheduler 工作的資料列中，按一下「立即執行」。

   幾秒後，Cloud Scheduler 工作應將結果欄更新為「Success」和「Last run」至目前時間。您可能需要按一下「Refresh」(重新整理)。

Cloud Scheduler 頁面只會確認名為您的 Cloud 函式的工作。開啟 Cloud 函式頁面即可查看函式記錄檔。

查看 Cloud 函式記錄檔

如要查看 Cloud 函式是否已成功啟動匯出作業，請開啟該函式的記錄：

Firebase 主控台

前往 Firebase 控制台的「Cloud Functions」頁面。

前往函式記錄檔頁面

GCP 控制台

前往 GCP 主控台的「Cloud Functions」頁面。

前往記錄檢視器

查看匯出進度

您可以使用 gcloud firestore operations list 指令查看匯出作業的進度，請參閱管理匯出和匯入作業。

匯出作業完成後，您可以在 Cloud Storage 值區中查看輸出檔案：

開啟 Cloud Storage 瀏覽器