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.

Gunakan Akses Berbasis Waktu

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

Panduan memulai ini membahas cara menggunakan Data Portability API untuk akses berbasis waktu ke data pengguna. Untuk akses satu kali ke data pengguna, lihat Mulai Menggunakan Data Portability API. 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.
Kirim permintaan yang diautentikasi dengan token OAuth yang valid ke endpoint InitiatePortabilityArchive untuk kedua kalinya menggunakan kredensial yang sama. Tindakan ini akan menampilkan error FAILED_PRECONDITION saat permintaan dibuat dalam waktu 24 jam sejak permintaan awal.

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 sisi server.
- Saat membuat kredensial otorisasi,catat Client ID OAuth 2.0, secret klien, dan URI pengalihan yang diotorisasi (misalnya, https://google.com). Anda memerlukannya nanti di quickstart.
- 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 memilih durasi waktu yang Anda inginkan untuk mengizinkan akses, Anda harus memilih 30 hari untuk menguji akses berbasis waktu.
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 sisi server. Alur ini menghasilkan token refresh yang dapat Anda gunakan untuk ekspor berikutnya.

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=code&
access_type=offline&
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 30 hari.
Setelah memberikan izin dan menentukan durasi akses, Anda akan diarahkan ke URI alihan—https://google.com. URL yang dibuat di kolom URL menyertakan kode otorisasi yang Anda tukarkan dengan token OAuth pada langkah berikutnya.

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&code=your_auth_code&scope=https://www.googleapis.com/auth/dataportability.myactivity.search
```
Untuk menukar kode otorisasi dengan token akses, panggil endpoint token oauth dengan:
```
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'
```
Responsnya akan terlihat seperti ini:
```
{
  "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
}
```
Dalam URL, your_OAuth_token adalah string yang mewakili token.

Kolom refresh_token_expires_in dalam hitungan detik dan mencerminkan apakah pengguna memilih akses selama 30 hari (259.2000 detik) atau 180 hari (1555.2000 detik). Jika aplikasi Anda memiliki status publikasi Pengujian, Anda memiliki akses selama 7 hari (604800 detik) terlepas dari pilihan pengguna.

Penting: Masa berlaku token akses OAuth Anda akan berakhir dalam satu jam—simpan token refresh agar dapat ditukar dengan token akses baru nanti.
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 akses berbasis waktu, Anda akan melihat:
```
{
  "archiveJobId": "<your_job_id>"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}
```
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.

Jika menerima status FAILED dalam respons, Anda dapat mencoba lagi ekspor menggunakan metode RetryPortabilityArchive.

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 akan menunjukkan bahwa Anda telah mengekspor resource myactivity.search dan stempel waktu untuk waktu Anda dapat mencoba lagi.

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

Setelah 24 jam, Anda dapat meminta ekspor baru, tetapi Anda harus menukarkan token refresh dengan token akses baru terlebih dahulu.

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'

Responsnya akan terlihat seperti ini:

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

Jika pengguna memperpanjang akses, waktu habis masa berlaku baru akan ditampilkan di kolom refresh_token_expires_in.

Anda dapat menggunakan token akses baru untuk mengulangi langkah-langkah InitiatePortabilityArchive dan GetPortabilityArchiveState.