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

開始使用 Data Portability API

在這個快速入門導覽課程中，您會取得帳戶的 OAuth 憑證，並將要求傳送至 Data Portability API 端點。

涵蓋內容

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

提供有效的 OAuth 權杖，將通過驗證的要求傳送至 InitiatePortabilityArchive 端點。回應應包含有效的 job_id。
將通過驗證的要求傳送至 GetPortabilityArchiveState 端點。回應應包含有效的工作狀態；工作完成時，也會附上已簽署的網址。
(選用) 使用相同憑證，再次將具備有效 OAuth 權杖的已驗證要求傳送至 InitiatePortabilityArchive 端點。這會傳回 RESOURCE_EXHAUSTED 錯誤，旨在醒目顯示 ResetAuthorization 端點的重要性。
將通過驗證的要求傳送至 ResetAuthorization 端點。這項要求會撤銷所有由使用者授予的 OAuth 範圍。
(選用) 使用先前使用的相同 OAuth 權杖，將要求傳送至 InitiatePortabilityArchive 端點。授權重設後，要求應該會失敗。

必要條件

如要執行本快速入門導覽課程，您必須：

確認您所在地區的使用者能使用 Data Portability 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&
include_granted_scopes=true&
state=developer-specified-value
```
在網址中：
- client_id 是您的 OAuth 用戶端 ID。
- redirect_uri 是授權的重新導向 URI，例如 https://google.com。
請注意，本快速入門導覽課程的網址範圍是搜尋活動範圍。你也可以將範圍設為 YouTube 活動範圍，也可以同時設定這兩種範圍。
將網址貼到瀏覽器的網址列中，然後按照 OAuth 流程中的步驟進行。此流程會要求您登入貴機構擁有或控管的帳戶，您在本快速入門導覽課程中使用的帳戶。

(已啟用 OAuth 範圍的帳戶)。同意畫面應如下所示 (畫面中的文字可能與下圖中的文字不同)：
表示同意之後，系統會將您導向至重新導向 URI：https://google.com。在網址列中產生的網址包含 OAuth 存取權杖。

例如，如果使用者帳戶授予 dataportability.myactivity.search 範圍的 OAuth 存取權，產生的網址如下所示：
```
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"
}

收集您的 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。這個工作 ID 可用來擷取資料封存檔案的狀態。
```
{
  "archiveJobId": "<your_job_id>"
}
```
如果您未提供有效的 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。如果工作未完成，回應會提供目前狀態。您應定期傳送要求至此端點，直到工作完成為止。
```
{
  "state": "IN_PROGRESS"
}
```
如果工作完成，回應會包含狀態和一或多個已簽署網址，可用於下載資料封存檔。
```
{
  "state": "COMPLETE",
  "urls": [
    "<signed_url>"
  ]
}
```
將已簽署的網址貼到瀏覽器中，即可下載資料封存檔。您應檢查封存內容，確保其中含有預期的搜尋活動資料。

注意： 完成封存工作所需的時間取決於封存工作大小。持續時間上限為 7 天。
注意： 如果您在回應中收到 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": "Resource has been exhausted (check quota).",
  "status": "RESOURCE_EXHAUSTED"
}

將通過驗證的要求傳送至 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"
  }