使用以時間為準的存取權

在本快速入門中，您將為帳戶取得 OAuth 權杖，並向 Data Portability API 端點傳送定期要求。

本快速入門導覽課程將說明如何使用 Data Portability API，以時間為依據存取使用者資料。如要一次性存取使用者資料，請參閱「開始使用資料可攜權 API」。如要瞭解如何為要求套用時間篩選器，請參閱「套用時間篩選器」。

課程內容

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

提供有效的 OAuth 權杖，將經過驗證的要求傳送至 InitiatePortabilityArchive 端點。回應應包含有效的 job_id。
將已驗證的要求傳送至 GetPortabilityArchiveState 端點。回應應包含有效的工作狀態，且在工作完成時提供已簽署的網址。
使用相同的憑證，再次傳送含有有效 OAuth 權杖的驗證要求至 InitiatePortabilityArchive 端點。如果要求是在初始要求後的 24 小時內提出，系統會傳回 FAILED_PRECONDITION 錯誤。

必要條件

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

確認資料可攜權 API 適用於您所在地區的使用者。如需支援國家/地區清單，請參閱「與第三方分享資料副本」頁面中的常見問題。
完成 Data Portability API 的設定步驟。
請按照伺服器端網頁應用程式的設定步驟，設定 OAuth。
- 建立授權憑證時，請記下 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 權杖。這項程序會使用伺服器端網頁應用程式的流程。這個流程會產生重新整理權杖，供您用於後續匯出作業。

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

請編寫如下網址。
```
https://accounts.google.com/o/oauth2/v2/auth?
client_id=client_id&
redirect_uri=redirect_uri&
response_type=code&
access_type=offline&
scope=https://www.googleapis.com/auth/dataportability.myactivity.search&
state=developer-specified-value
```
在網址中：
- client_id 是您的 OAuth 用戶端 ID。
- redirect_uri 是您授權的重新導向 URI，例如 https://google.com。
請注意，本快速入門導覽課程的網址中使用的範圍是搜尋活動範圍。您也可以使用 YouTube 活動範圍或兩者皆用。

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

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

舉例來說，如果使用者帳戶授予 OAuth 存取 dataportability.myactivity.search 範圍的權限，系統會產生類似以下的網址：
```
https://google.com/#state=developer-specified-value&code=your_auth_code&scope=https://www.googleapis.com/auth/dataportability.myactivity.search
```
如要將授權碼換成存取權杖，請使用以下方式呼叫 OAuth 權杖端點：
```
curl https://oauth2.googleapis.com/token\
-H 'Content-Type: application/x-www-form-urlencoded' -X POST\
-d 'code=your_auth_code&\
redirect_uri=redirect_uri\
client_id=client_id&\
client_secret=client_secret&\
grant_type=authorization_code'
```
回應內容應如下所示：
```
{
  "access_token": your_OAuth_token,
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/dataportability.myactivity.search",
  "refresh_token": your_refresh_token,
  "refresh_token_expires_in": 2591999
}
```
在網址中，your_OAuth_token 是代表權杖的字串。

refresh_token_expires_in 欄位以秒為單位，反映使用者選擇 30 天 (2592000 秒) 或 180 天 (15552000 秒) 的存取權。如果應用程式的發布狀態為「測試」，則無論使用者選擇何種測試群組，您都只能存取 7 天 (604800 秒)。

重要事項： 您的 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 金鑰。

如要呼叫 Data Portability API，請按照下列步驟操作：

首先，您需要將已驗證的要求傳送至 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 要求會傳回 job_id 和 accessType。工作 ID 用於擷取資料封存的狀態，而存取類型則可判斷您是否已獲得一次性或時間限制的資料存取權。以時間為依據的存取權限會顯示以下資訊：
```
{
  "archiveJobId": "<your_job_id>"
  "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/portabilityArchiveState
```
在指令中：
- your_OAuth_token 是您的 OAuth 憑證。
- your_job_id 是 InitiatePortabilityArchive 要求傳回的工作 ID。
回應內容取決於工作狀態。如果工作尚未完成，回應會提供目前狀態。您應定期向這個端點傳送要求，直到工作完成為止。
```
{
  "state": "IN_PROGRESS"
}
```
如果工作已完成，回應會包含狀態，以及一或多個用於下載資料封存檔的已簽署網址。
```
{
  "state": "COMPLETE",
  "urls": [
    "<signed_url>"
  ]
}
```
將已簽署的網址貼到瀏覽器中，即可下載資料封存檔。請檢查封存檔案的內容，確認其中包含預期的搜尋活動資料。

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

重複執行上述指令，將已驗證的要求傳送至 InitiatePortabilityArchive 端點。

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 憑證。

回應應指出您已匯出 myactivity.search 資源，並提供可重試的時間戳記。

...
  "error": {
    "code": 429,
    "message": "Requested resources have already been exported. You can initiate another export after #{timestamp_after_24hrs}.",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "RESOURCE_EXHAUSTED_TIME_BASED",
        "domain": "dataportability.googleapis.com"
  "metadata": {
    "previous_job_ids": "#{previous_job_ids}"
    "access_type": "ACCESS_TYPE_TIME_BASED"
    "timestamp_after_24hrs": "#{timestamp_after_24hrs}"
...

24 小時後，您可以要求新的匯出作業，但必須先將重新整理權杖換成新的存取權杖。

curl https://oauth2.googleapis.com/token\
-H 'Content-Type: application/x-www-form-urlencoded' -X POST\
-d 'refresh_token=your_refresh_token&\
client_id=client_id&\
client_secret=client_secret&\
grant_type=refresh_token'

回應內容應如下所示：

{
  "access_token": your_OAuth_token,
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/dataportability.myactivity.search",
  "refresh_token_expires_in": 2505599
}

如果使用者續訂存取權，新的到期時間會顯示在 refresh_token_expires_in 欄位中。

您可以使用新的存取權杖重複執行 InitiatePortabilityArchive 和 GetPortabilityArchiveState 步驟。