Halaman ini diterjemahkan oleh Cloud Translation API.

Mulai gunakan Data Portability API

Dalam panduan memulai ini, Anda akan mendapatkan token OAuth untuk akun Anda dan mengirim permintaan ke endpoint Data Portability API.

Yang Anda pelajari

Dalam panduan memulai ini, Anda akan mempelajari cara:

Kirim permintaan terautentikasi ke endpoint InitiatePortabilityArchive dengan memberikan token OAuth yang valid. Respons harus berisi job_id yang valid.
Kirim permintaan yang diautentikasi ke endpoint GetPortabilityArchiveState. Respons harus berisi status tugas yang valid, dan URL yang ditandatangani saat tugas selesai.
(Opsional) Kirim permintaan terautentikasi dengan token OAuth yang valid ke endpoint InitiatePortabilityArchive untuk kedua kalinya menggunakan kredensial yang sama. Tindakan ini akan menampilkan error RESOURCE_EXHAUSTED dan dimaksudkan untuk menyoroti pentingnya endpoint ResetAuthorization.
Kirim permintaan yang diautentikasi ke endpoint ResetAuthorization. Permintaan ini akan mencabut semua cakupan OAuth yang diberikan pengguna.
(Opsional) Kirim permintaan ke endpoint InitiatePortabilityArchive menggunakan token OAuth yang sama dengan yang Anda gunakan sebelumnya. Permintaan akan gagal setelah otorisasi direset.

Prasyarat

Untuk menjalankan panduan memulai ini, Anda perlu:

Pastikan Data Portability API tersedia untuk pengguna di lokasi Anda. Untuk mengetahui daftar negara dan wilayah yang didukung, lihat Pertanyaan Umum di halaman "Membagikan salinan data Anda kepada pihak ketiga".
Selesaikan langkah penyiapan untuk Data Portability API.
Ikuti langkah-langkah guna mengonfigurasi OAuth untuk aplikasi web JavaScript. Dalam produksi, Anda biasanya akan menggunakan alur yang berbeda seperti alur OAuth untuk aplikasi server web. Agar mudah, panduan memulai ini menggunakan alur aplikasi web JavaScript.
- Saat membuat kredensial otorisasi, catat Client ID OAuth 2.0 dan URI pengalihan yang diberi otorisasi (misalnya, https://google.com). Anda akan memerlukannya nanti di panduan memulai.
- Saat Anda mengonfigurasi cakupan untuk Data Portability API, perhatikan bahwa panduan memulai ini menggunakan grup resource myactivity.search: https://www.googleapis.com/auth/dataportability.myactivity.search.
Dapatkan token OAuth.
Mendapatkan akses ke akun yang dimiliki atau dikontrol oleh organisasi Anda. Data aktivitas penelusuran akun ini diekspor dalam panduan memulai ini.

Mendapatkan token OAuth

Untuk panduan memulai ini, Anda akan mengirim permintaan otorisasi untuk mendapatkan token OAuth menggunakan URL. Proses ini menggunakan alur untuk aplikasi web JavaScript. Alur ini tidak menampilkan token refresh.

Untuk aplikasi produksi, Anda biasanya akan menggunakan alur OAuth untuk mendapatkan token refresh yang dapat digunakan untuk membuat token akses sesuai permintaan. Contohnya adalah alur untuk aplikasi web sisi server.

Untuk mendapatkan token OAuth:

Tulis URL seperti berikut.
```
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
```
Di URL:
- client_id adalah client ID OAuth Anda.
- redirect_uri adalah URI pengalihan yang diberi otorisasi; misalnya, https://google.com.
Perhatikan bahwa cakupan yang digunakan dalam URL untuk panduan memulai ini adalah cakupan aktivitas penelusuran. Anda juga dapat menggunakan cakupan aktivitas YouTube atau kedua cakupan.
Tempelkan URL ke kolom URL browser Anda, dan ikuti langkah-langkah dalam alur OAuth. Alur ini mengharuskan Anda untuk login ke akun yang dimiliki atau dikontrol oleh organisasi yang Anda gunakan untuk panduan memulai ini.

Ini adalah akun yang memberikan izin untuk cakupan OAuth. Layar izin akan terlihat seperti ini (teks di layar Anda dapat berbeda dari teks pada gambar ini):
Setelah memberikan izin, Anda akan diteruskan ke URI pengalihan—https://google.com. URL yang dibuat di kolom URL mencakup token akses OAuth.

Misalnya, jika akun pengguna memberikan akses OAuth ke cakupan dataportability.myactivity.search, URL yang dihasilkan akan terlihat seperti ini:
```
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
```
Di URL, <your_OAuth_token> adalah string yang mewakili token.

Penting: Masa berlaku token akses OAuth Anda akan berakhir dalam waktu satu jam. Jika Anda perlu membuat token baru, ikuti langkah-langkah sebelumnya.

Untuk memvalidasi token OAuth, tempel URL ini ke browser Anda:

https://www.googleapis.com/oauth2/v3/tokeninfo?access_token=your_OAuth_token

Responsnya akan terlihat seperti ini:

{
  "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"
}

Kumpulkan token OAuth dan kunci API Anda. Anda memerlukannya untuk melakukan panggilan ke Data Portability API.

Mengirim permintaan ke endpoint

Dalam panduan memulai ini, Anda akan menggunakan perintah curl untuk memanggil endpoint Data Portability API. Perintah ini memerlukan token OAuth dan kunci API yang Anda kumpulkan sebelumnya.

Untuk memanggil Data Portability API:

Pertama, kirim permintaan terautentikasi ke endpoint InitiatePortabilityArchive. Permintaan ini memulai tugas pengarsipan.

Jalankan perintah curl berikut:
```
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
```
Dalam perintah:
- your_OAuth_token adalah token OAuth Anda.
CATATAN: Parameter resources hanya boleh berisi cakupan OAuth yang diberi akses. Dalam contoh ini, hanya myactivity.search yang diberikan. Jika Anda menyertakan grup resource tambahan, error akan muncul.

Permintaan InitiatePortabilityArchive menampilkan job_id. ID tugas ini digunakan untuk mengambil status arsip data.
```
{
  "archiveJobId": "<your_job_id>"
}
```
Jika Anda gagal memberikan token OAuth yang valid, pesan error ini akan ditampilkan:
```
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.
```
Selanjutnya, Anda akan mengirim permintaan terautentikasi ke endpoint GetPortabilityArchiveState untuk mengambil status tugas arsip.

Jalankan perintah curl berikut:
```
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
```
Dalam perintah:
- your_OAuth_token adalah token OAuth Anda.
- your_job_id adalah ID tugas yang ditampilkan oleh permintaan InitiatePortabilityArchive.
Respons ini didasarkan pada state tugas. Jika tugas belum selesai, respons akan memberikan status saat ini. Anda harus mengirim permintaan ke endpoint ini secara berkala hingga tugas selesai.
```
{
  "state": "IN_PROGRESS"
}
```
Jika tugas selesai, respons akan berisi status dan satu atau beberapa URL bertanda tangan yang digunakan untuk mendownload arsip data.
```
{
  "state": "COMPLETE",
  "urls": [
    "<signed_url>"
  ]
}
```
Tempel URL yang ditandatangani ke browser Anda untuk mendownload arsip data. Anda harus memeriksa konten arsip untuk memastikan bahwa konten berisi data aktivitas penelusuran yang diharapkan.

Catatan: Jumlah waktu yang diperlukan untuk menyelesaikan tugas arsip bergantung pada ukuran arsip. Durasi maksimum adalah tujuh hari.
Catatan: Jika Anda menerima status FAILED dalam respons, Anda dapat mencoba lagi ekspor menggunakan metode RetryPortabilityArchive.

(Opsional) Ulangi perintah sebelumnya untuk mengirim permintaan yang diautentikasi ke endpoint 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

Dalam perintah:

your_OAuth_token adalah token OAuth Anda.

Responsnya harus menunjukkan bahwa izin satu kali untuk resource myactivity.search sudah habis untuk pengguna ini.

...
  "error":
    {
      "code": 429,
  "message": "Resource has been exhausted (check quota).",
  "status": "RESOURCE_EXHAUSTED"
}

Kirim permintaan terautentikasi ke endpoint ResetAuthorization. Permintaan ini akan mencabut semua cakupan OAuth yang diberikan pengguna dan memungkinkan Anda memanggil InitiatePortabilityArchive untuk grup resource yang telah Anda gunakan.
```
curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
https://dataportability.googleapis.com/v1/authorization:reset
```
Dalam perintah:
- your_OAuth_token adalah token OAuth Anda.
Perintah ini menampilkan respons kosong.

(Opsional) Setelah mereset otorisasi, kirim permintaan lain ke endpoint InitiatePortabilityArchive. Gunakan perintah curl yang sama dengan yang Anda gunakan sebelumnya.

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

Dalam perintah:

your_OAuth_token adalah token OAuth Anda.

Respons akan menampilkan error karena token OAuth yang Anda berikan telah dicabut.

...
  "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"
  }