新的資料可攜權 API 功能現已推出，並將於 2025 年 2 月 20 日開放所有人使用！

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

為要求套用時間篩選器

在本快速入門課程中，您將為帳戶取得 OAuth 權杖，並使用時間戳記將要求傳送至 Data Portability API 端點，藉此篩選匯出的資料。

本快速入門導覽課程將說明如何使用 Data Portability API 搭配時間存取權，並為支援的資源套用時間篩選器。如要進一步瞭解使用者資料的時間限制存取權，請參閱「使用時間限制存取權」。

課程內容

在本快速入門導覽課程中，您將瞭解如何：

將經過驗證的週期性要求傳送至 InitiatePortabilityArchive 端點，只匯出自上次匯出後新增的資料。
將經過驗證的要求傳送至 InitiatePortabilityArchive 端點，只匯出過去 6 個月的資料。
將已驗證的要求傳送至 InitiatePortabilityArchive 端點，只匯出特定時間範圍的資料。

必要條件

如要執行這個快速入門，您需要：

確認資料可攜權 API 適用於您所在地區的使用者。如需支援國家/地區清單，請參閱「與第三方分享資料副本」頁面中的常見問題。
完成 Data Portability API 的設定步驟。
請按照JavaScript 網頁應用程式的步驟設定 OAuth。在實際工作環境中，您通常會使用不同的流程，例如網路伺服器應用程式的 OAuth 流程。為了簡化操作，本快速入門導覽課程會使用 JavaScript 網頁應用程式流程。
- 建立授權憑證時，請記下 OAuth 2.0 用戶端 ID 和授權的重新導向 URI (例如 https://google.com)。您稍後會在快速入門指南中使用這些值。
- 為 Data Portability API 設定範圍時，請注意，這個快速入門會使用 myactivity.search 資源群組：https://www.googleapis.com/auth/dataportability.myactivity.search。
- 選擇要允許存取的時間長度時，請選取「30 天」，以便測試時間篩選功能。(時間篩選器也適用於一次性存取權)。
取得 OAuth 權杖。
取得貴機構擁有或控管的帳戶存取權。這個帳戶的搜尋活動資料會在本快速入門課程中匯出。

取得 OAuth 權杖

在本快速入門課程中，您會傳送授權要求，以便使用網址取得 OAuth 權杖。這個程序會使用 JavaScript 網頁應用程式的流程。這個流程不會傳回重新整理權杖。

對於正式版應用程式，您通常會使用 OAuth 流程來取得更新權杖，以便視需要產生存取權杖。這類情況的範例是伺服器端網頁應用程式的流程。

如要取得 OAuth 權杖，請按照下列步驟操作：

請撰寫類似以下的網址。
```
https://accounts.google.com/o/oauth2/v2/auth?
client_id=client_id&
redirect_uri=redirect_uri&
response_type=token&
scope=https://www.googleapis.com/auth/dataportability.myactivity.search&
state=developer-specified-value
```
在網址中：
- client_id 是您的 OAuth 用戶端 ID。
- redirect_uri 是您授權的重新導向 URI，例如 https://google.com。
請注意，本快速入門導覽課程的網址中使用的範圍是搜尋活動範圍。您可以使用任何支援 TimeFilter 的範圍。

警告： 請勿將 Data Portability API 範圍與其他類型的範圍混用、一次使用過多範圍，或納入先前已授予的範圍，否則會導致錯誤。詳情請參閱「範圍限制」一節。
將網址貼到瀏覽器的網址列中，然後按照 OAuth 流程中的步驟操作。這個流程要求您登入貴機構擁有或控管的帳戶，也就是您用於本快速入門課程的帳戶。

這是同意 OAuth 範圍的帳戶。同意聲明畫面應如下所示 (畫面上的文字可能與圖片中的文字不同)：
選擇要授予存取權的範圍，以及共用帳戶資料存取權的時間長度 (一次、30 天或 180 天)。在這個快速入門導覽課程中，請選擇「30 天」。(時間篩選器也適用於一次性存取權)。
授權並決定存取時間長度後，系統應會將您轉送至重新導向 URI (https://google.com)。網址列中產生的網址會包含 OAuth 存取權杖。

舉例來說，如果使用者帳戶授予 OAuth 存取 dataportability.myactivity.search 範圍的權限，系統會產生類似以下的網址：
```
https://google.com/#state=developer-specified-value&access_token=your_OAuth_token&token_type=Bearer&expires_in=3599&scope=https://www.googleapis.com/auth/dataportability.myactivity.search
```
在網址中，your_OAuth_token 是代表權杖的字串。

重要事項： 您的 OAuth 存取權權杖會在一小時後過期。如果您需要產生新的權杖，請按照前述步驟操作。
如要驗證 OAuth 權杖，請將下列網址貼到瀏覽器中：
```
https://www.googleapis.com/oauth2/v3/tokeninfo?access_token=your_OAuth_token
```
回應內容應如下所示：
```
{
  "azp": <your_azp_value>,
  "aud": <your_aud_value>,
  "scope": "https://www.googleapis.com/auth/dataportability.myactivity.search",
  "exp": "1694210968",
  "expires_in": "3334",
  "access_type": "online"
}
```
您不需要 azp 或 aud 欄位就能提出要求。azp 欄位代表授權顯示者的 client_id，而 aud 欄位則會識別此權杖的目標對象，也就是應用程式的其中一個用戶端 ID。

注意： 您也可以透過發出 HTTP GET 要求來驗證權杖。
收集 OAuth 權杖和 API 金鑰。您需要這些資訊才能呼叫 Data Portability API。

傳送要求至端點

在本快速入門課程中，您會使用 curl 指令呼叫 Data Portability API 端點，並搭配時間戳記篩選匯出的資料。這些指令需要先前收集到的 OAuth 權杖和 API 金鑰。

上次匯出作業的資料

您可以使用時間篩選器搭配時間存取權，匯出自上次匯出後的新資料。舉例來說，請考量範圍 https://www.googleapis.com/auth/dataportability.myactivity.search。

首先，您需要將已驗證的要求傳送至 InitiatePortabilityArchive 端點。這項要求會啟動完整資料集的封存工作。

執行下列 curl 指令：
```
curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"]}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate
```
在指令中：
- your_OAuth_token 是您的 OAuth 憑證。
警告： resources 參數應只包含已授予存取權且支援時間篩選器的 OAuth 範圍。在這個範例中，只有 myactivity.search 已授予。如果您加入其他資源群組或不支援的資源群組，系統會傳回錯誤。詳情請參閱「範圍限制」一節。
InitiatePortabilityArchive 要求會傳回 archiveJobId 和 accessType。工作 ID 用於擷取資料封存的狀態，而存取類型則決定您是否已獲得一次性或時間限制的資料存取權。以時間為依據的存取權限會顯示以下資訊：
```
{
  "archiveJobId": "<your_job_id_1>"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}
```
如果您無法提供有效的 OAuth 權杖，系統會傳回以下錯誤訊息：
```
Request had invalid authentication credentials. Expected OAuth 2.0 access
token, login cookie or other valid authentication credential. See
https://developers.google.com/identity/sign-in/web/devconsole-project.
```
接著，您可以向 GetPortabilityArchiveState 端點傳送已驗證的要求，擷取封存工作狀態。

執行下列 curl 指令：
```
curl -H 'Authorization: Bearer your_OAuth_token' -X GET \
-H "Content-Type: application/json; charset=utf-8" \
https://dataportability.googleapis.com/v1/archiveJobs/your_job_id_1/portabilityArchiveState
```
在指令中：
- your_OAuth_token 是您的 OAuth 憑證。
- your_job_id_1 是 InitiatePortabilityArchive 要求傳回的工作 ID。
回應內容取決於工作狀態。如果工作尚未完成，回應會提供目前狀態。您應定期向這個端點傳送要求，直到工作完成為止。
```
{
  "state": "IN_PROGRESS"
}
```
如果工作已完成，回應會包含狀態，以及一或多個用於下載資料封存檔的已簽署網址。另外還有一個 export_time 欄位，代表首次呼叫 InitiatePortabilityArchive 時的時間戳記。
```
{
  "state": "COMPLETE",
  "urls": [
    "<signed_url>"
  ]
  "export_time": "<timestamp_of_first_initiate_request>"
}
```
將已簽署的網址貼到瀏覽器中，即可下載資料封存檔。請檢查封存檔案的內容，確認其中包含預期的搜尋活動資料。

注意： 完成封存作業所需的時間取決於封存檔案的大小。最長七天。
如果您在回應中收到 FAILED 狀態，可以使用 RetryPortabilityArchive 方法重試匯出作業。

等待至少 24 小時，然後使用與步驟 1 相同的指令向 InitiatePortabilityArchive 提出另一項要求，但這次請使用 export_time 做為 start_time。

curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"],
"start_time": timestamp_of_first_initiate_request}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate

對於時間限制存取權，這會傳回：

{
  "archiveJobId": "<your_job_id_2>"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}

重複步驟 2，將經過驗證的要求傳送至 GetPortabilityArchiveState 端點，以便擷取封存工作狀態 (使用 <your_job_id_2>)。

工作完成後，回應會是：

  {
    "state": "COMPLETE",
    "urls": [
      "signed_urls"
    ],
    "start_time": timestamp_of_first_initiate_request,
    "export_time": timestamp_of_second_initiate_request
  }

確認第二次匯出作業中的資料僅包含第一次匯出作業後產生的新資料。

過去 6 個月的資料

您也可以使用時間篩選器，只匯出最新資料，而非整個語料庫。

假設今天的日期是 2024-10-01，且您想匯出過去 6 個月的資料。首先，您將已驗證的要求傳送至 InitiatePortabilityArchive 端點，並將 start_time 設為「2024-04-01T00:00:00Z」。

執行下列 curl 指令：

curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"],
"start_time": "2024-04-01T00:00:00Z"}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate

對於時間限制存取權，這會傳回：

{
  "archiveJobId": "job_id_1"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}

向 GetPortabilityArchiveState 端點提出要求，擷取封存工作狀態。

執行下列 curl 指令：

curl -H 'Authorization: Bearer your_OAuth_token' -X GET \
-H "Content-Type: application/json; charset=utf-8" \
https://dataportability.googleapis.com/v1/archiveJobs/job_id_1/portabilityArchiveState

工作完成後，回應會是：

{
  "state": "COMPLETE",
  "urls": [
    "signed_urls"
  ],
  "start_time": "2024-04-01T00:00:00Z",
  "export_time": "2024-10-01T00:00:00Z"
}

請注意，start_time 是步驟 1 中指定的 start_time，而 export_time 是步驟 1 中呼叫 InitiatePortabilityArchive 時的時間戳記。

確認匯出內容僅包含過去六個月的資料。

特定時間範圍的資料

您可以使用時間篩選器，匯出特定日期範圍的資料，例如僅匯出 2023 年的資料。

首先，您會將已驗證的要求傳送至 InitiatePortabilityArchive 端點，其中 start_time 為「2023-01-01T00:00:00Z」，end_time 為「2023-12-31T23:59:59Z」。

執行下列 curl 指令：

curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"],
"start_time": "2023-01-01T00:00:00Z",
"end_time": "2023-12-31T23:59:59Z"}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate

對於時間限制存取權，這會傳回：

{
  "archiveJobId": "job_id_1"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}

向 GetPortabilityArchiveState 端點提出要求，擷取封存工作狀態。

執行下列 curl 指令：

curl -H 'Authorization: Bearer your_OAuth_token' -X GET \
-H "Content-Type: application/json; charset=utf-8" \
https://dataportability.googleapis.com/v1/archiveJobs/job_id_1/portabilityArchiveState

工作完成後，回應會是：

{
  "state": "COMPLETE",
  "urls": [
    "signed_urls"
  ],
  "start_time": "2023-01-01T00:00:00Z",
  "export_time": "2023-12-31T23:59:59Z"
}

請注意，start_time 是步驟 1 中指定的 start_time，而 export_time 等於步驟 1 中提供的 end_time。

確認匯出內容僅包含 2023 年的資料。

支援的範圍

下列範圍支援時間篩選器：

https://www.googleapis.com/auth/dataportability.myactivity.youtube
https://www.googleapis.com/auth/dataportability.myactivity.maps
https://www.googleapis.com/auth/dataportability.myactivity.search
https://www.googleapis.com/auth/dataportability.myactivity.myadcenter
https://www.googleapis.com/auth/dataportability.myactivity.shopping
https://www.googleapis.com/auth/dataportability.myactivity.play
https://www.googleapis.com/auth/dataportability.chrome.history

注意：如果時間篩選要求混合支援和不支援的範圍，就會導致 INVALID_ARGUMENT 錯誤，並顯示 The requested resources do not support time filters。