開始使用 Data Portability API

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

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

課程內容

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

提供有效的 OAuth 權杖，將經過驗證的要求傳送至 InitiatePortabilityArchive 端點。回應應包含有效的 job_id。
將已驗證的要求傳送至 GetPortabilityArchiveState 端點。回應應包含有效的工作狀態，且在工作完成時提供已簽署的網址。
(選用) 使用相同的憑證，再次將含有有效 OAuth 權杖的已驗證要求傳送至 InitiatePortabilityArchive 端點。這會傳回 RESOURCE_EXHAUSTED 錯誤，目的是強調 ResetAuthorization 端點的重要性。
將已驗證的要求傳送至 ResetAuthorization 端點。這項要求會撤銷所有使用者授予的 OAuth 範圍。
(選用) 使用先前使用的相同 OAuth 權杖，向 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。
- 當您選擇要允許存取權的時間長度時，這個快速入門會使用一次性存取權。
取得 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。
請注意，本快速入門導覽課程的網址中使用的範圍是搜尋活動範圍。您也可以使用 YouTube 活動範圍或兩者皆用。

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

這是同意 OAuth 範圍的帳戶。同意畫面應如下圖所示 (畫面上的文字可能與圖片中的文字不同)：
選擇要授予存取權的範圍，以及共用帳戶資料存取權的時間長度 (一次、30 天或 180 天)。在本快速入門課程中，請選擇「僅限一次」。
授權同意並選擇存取時間長度後，系統應會將您轉送至重新導向 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 金鑰。

如要呼叫 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_ONE_TIME'
}
```
如果您無法提供有效的 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. Please call ResetAuthorization and re-obtain consent before trying again.",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "RESOURCE_EXHAUSTED_ONE_TIME",
        "domain": "dataportability.googleapis.com"
  "metadata": {
    "previous_job_ids": "{previous_job_ids}"
    "access_type": "ACCESS_TYPE_ONE_TIME"
...

將已驗證的要求傳送至 ResetAuthorization 端點。這項要求會撤銷所有使用者授予的 OAuth 範圍，並讓您針對已使用的資源群組呼叫 InitiatePortabilityArchive。
```
curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
https://dataportability.googleapis.com/v1/authorization:reset
```
在指令中：
- your_OAuth_token 是您的 OAuth 憑證。
這個指令會傳回空白回應。

(選用) 重新設定授權後，請向 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 憑證。

由於您提供的 OAuth 權杖已遭到撤銷，因此回應應傳回錯誤。

...
  "error": {     
    "code": 401,    
        "message": "Request had invalid authentication credentials. Expected
        OAuth 2 access token, login cookie or other valid authentication
        credential. See https://developers.google.com/identity/sign-in/web/devconsole-project.",
        "status": "UNAUTHENTICATED"
  }