Fitur Data Portability API baru kini diluncurkan dan akan tersedia untuk semua pengguna paling lambat 20 Februari 2025.

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 satu kali ke endpoint Data Portability API.

Panduan memulai ini membahas cara menggunakan Data Portability API untuk akses satu kali ke data pengguna. Untuk akses berkelanjutan ke data pengguna, lihat Menggunakan Akses Berbasis Waktu. Untuk mempelajari cara menerapkan filter waktu ke permintaan Anda, lihat Menerapkan Filter Waktu.

Yang Anda pelajari

Dalam panduan memulai ini, Anda akan mempelajari cara:

Kirim permintaan yang diautentikasi 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 saat tugas selesai, URL yang ditandatangani.
(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 quickstart ini, Anda harus:

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-langkah penyiapan untuk Data Portability API.
Ikuti langkah-langkah untuk mengonfigurasi OAuth untuk aplikasi web JavaScript. Dalam produksi, Anda biasanya akan menggunakan alur yang berbeda seperti alur OAuth untuk aplikasi server web. Untuk mempermudah, panduan memulai ini menggunakan alur aplikasi web JavaScript.
- Saat membuat kredensial otorisasi, catat Client ID OAuth 2.0 dan URI pengalihan yang sah (misalnya, https://google.com). Anda akan memerlukannya nanti di panduan memulai.
- Saat Anda mengonfigurasi cakupan untuk Data Portability API, perhatikan bahwa quickstart ini menggunakan grup resource myactivity.search: https://www.googleapis.com/auth/dataportability.myactivity.search.
- Saat Anda memilih durasi waktu yang ingin Anda izinkan untuk akses, quickstart ini akan menggunakan akses satu kali.
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:

Buat 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&
state=developer-specified-value
```
Di URL:
- client_id adalah client ID OAuth Anda.
- redirect_uri adalah URI pengalihan yang sah; misalnya, https://google.com.
Perhatikan bahwa cakupan yang digunakan di URL untuk panduan memulai ini adalah cakupan aktivitas penelusuran. Anda juga dapat menggunakan cakupan aktivitas YouTube atau kedua cakupan tersebut.

Peringatan: Jangan menggabungkan cakupan Data Portability API dengan jenis cakupan lainnya, menggunakan terlalu banyak cakupan sekaligus, atau menyertakan cakupan yang telah diberikan sebelumnya karena hal ini akan mengakibatkan error. Untuk mengetahui detailnya, lihat Batasan cakupan.
Tempel URL tersebut ke kolom URL browser Anda, lalu ikuti langkah-langkah dalam alur OAuth. Alur ini mengharuskan Anda login ke akun yang dimiliki atau dikontrol oleh organisasi yang Anda gunakan untuk memulai panduan ini.

Ini adalah akun yang memberikan izin ke cakupan OAuth. Layar izin akan terlihat seperti ini (teks di layar Anda mungkin berbeda dengan teks dalam gambar ini):
Pilih cakupan yang akan diberi akses dan durasi waktu untuk membagikan akses ke data akun (sekali, 30 hari, atau 180 hari). Untuk panduan memulai ini, pilih Hanya sekali.
Setelah memberikan izin dan memilih durasi akses, Anda akan diarahkan ke URI pengalihan—https://google.com. URL yang dihasilkan di kolom URL menyertakan 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
```
Dalam URL, your_OAuth_token adalah string yang mewakili token.

Penting: Token akses OAuth Anda akan berakhir masa berlakunya dalam 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"
}
```
Anda tidak memerlukan kolom azp atau aud untuk membuat permintaan. Kolom azp mewakili client_id presenter resmi, dan kolom aud mengidentifikasi audiens yang menjadi target token ini, yang akan sama dengan salah satu client ID untuk aplikasi Anda.

Catatan: Anda juga dapat memverifikasi token dengan mengeluarkan permintaan HTTP GET.
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, Anda mengirim permintaan yang diautentikasi ke endpoint InitiatePortabilityArchive. Permintaan ini akan 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.
Peringatan: 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 ditampilkan. Untuk mengetahui detailnya, lihat Pembatasan cakupan.

Permintaan InitiatePortabilityArchive menampilkan job_id dan accessType. ID tugas digunakan untuk mengambil status arsip data dan jenis akses menentukan apakah Anda telah diberi akses satu kali atau berbasis waktu ke data. Untuk tujuan panduan memulai ini, Anda harus memiliki akses satu kali.
```
{
  'archiveJobId': '<your_job_id>'
  'accessType': 'ACCESS_TYPE_ONE_TIME'
}
```
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 mengirim permintaan yang diautentikasi ke endpoint GetPortabilityArchiveState untuk mengambil status tugas pengarsipan.

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 didasarkan pada status 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 yang ditandatangani 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 isi arsip untuk memastikan bahwa arsip tersebut berisi data aktivitas penelusuran yang diharapkan.

Catatan: Jumlah waktu yang diperlukan untuk menyelesaikan tugas pengarsipan bergantung pada ukuran arsip. Durasi maksimumnya 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.

Respons harus menunjukkan bahwa izin satu kali untuk resource myactivity.search telah habis untuk pengguna ini.

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

Kirim permintaan yang diautentikasi ke endpoint ResetAuthorization. Permintaan ini 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"
  }