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.

Menerapkan Filter Waktu ke Permintaan

Dalam panduan memulai ini, Anda akan mendapatkan token OAuth untuk akun Anda, dan mengirim permintaan ke endpoint Data Portability API menggunakan stempel waktu untuk memfilter data yang diekspor.

Panduan memulai ini membahas cara menggunakan Data Portability API dengan akses berbasis waktu dan menerapkan filter waktu untuk resource yang didukung. Untuk mengetahui detail selengkapnya tentang akses berbasis waktu ke data pengguna, lihat Menggunakan Akses Berbasis Waktu.

Yang Anda pelajari

Dalam panduan memulai ini, Anda akan mempelajari cara:

Kirim permintaan terautentikasi berulang ke endpoint InitiatePortabilityArchive untuk hanya mengekspor data baru sejak ekspor terakhir Anda.
Kirim permintaan yang diautentikasi ke endpoint InitiatePortabilityArchive untuk hanya mengekspor data dari 6 bulan terakhir.
Kirim permintaan yang diautentikasi ke endpoint InitiatePortabilityArchive untuk hanya mengekspor data dari jangka waktu tertentu.

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 memilih durasi waktu yang Anda inginkan untuk mengizinkan akses, Anda harus memilih 30 hari untuk menguji pemfilteran waktu dengan akses berbasis waktu. (Filter Waktu juga berfungsi dengan 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 dapat menggunakan cakupan apa pun yang mendukung Filter Waktu.

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. (Filter Waktu juga berfungsi dengan akses satu kali.)
Setelah memberikan izin dan menentukan durasi akses, Anda akan diarahkan ke URI alihan—https://google.com. URL yang dibuat 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 menggunakan perintah curl untuk memanggil endpoint Data Portability API dengan stempel waktu untuk memfilter data yang diekspor.Perintah ini memerlukan token OAuth dan kunci API yang Anda kumpulkan sebelumnya.

Data dari ekspor terakhir

Anda dapat menggunakan Filter Waktu dengan Akses Berbasis Waktu untuk mengekspor data baru sejak ekspor terakhir. Misalnya, pertimbangkan cakupan https://www.googleapis.com/auth/dataportability.myactivity.search.

Pertama, Anda mengirim permintaan yang diautentikasi ke endpoint InitiatePortabilityArchive. Permintaan ini akan memulai tugas arsip untuk korpus data lengkap.

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 dan mendukung Filter Waktu. Dalam contoh ini, hanya myactivity.search yang diberikan. Jika Anda menyertakan grup resource tambahan, atau grup resource yang tidak didukung, error akan ditampilkan. Untuk mengetahui detailnya, lihat Batasan cakupan.

Permintaan InitiatePortabilityArchive menampilkan archiveJobId 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_1>"
  "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_1/portabilityArchiveState
```
Dalam perintah:
- your_OAuth_token adalah token OAuth Anda.
- your_job_id_1 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. Ada juga kolom export_time yang mewakili stempel waktu saat panggilan pertama ke InitiatePortabilityArchive dilakukan.
```
{
  "state": "COMPLETE",
  "urls": [
    "<signed_url>"
  ]
  "export_time": "<timestamp_of_first_initiate_request>"
}
```
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.
Tunggu minimal 24 jam, lalu buat permintaan lain ke InitiatePortabilityArchive menggunakan perintah yang sama seperti pada langkah 1, tetapi kali ini gunakan export_time sebagai start_time.
```
curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"],
"start_time": timestamp_of_first_initiate_request}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate
```
Catatan: Anda dapat menyesuaikan start_time agar sedikit tumpang-tindih dengan export_time untuk memastikan data yang dihasilkan di antara permintaan disertakan dalam ekspor.

Untuk akses berbasis waktu, tindakan ini akan menampilkan:
```
{
  "archiveJobId": "<your_job_id_2>"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}
```
Ulangi langkah 2 untuk mengirim permintaan yang diautentikasi ke endpoint GetPortabilityArchiveState guna mengambil status tugas pengarsipan (menggunakan <your_job_id_2>).

Setelah tugas selesai, responsnya akan berupa:

  {
    "state": "COMPLETE",
    "urls": [
      "signed_urls"
    ],
    "start_time": timestamp_of_first_initiate_request,
    "export_time": timestamp_of_second_initiate_request
  }

Pastikan data dalam ekspor kedua hanya berisi data baru yang dihasilkan setelah ekspor pertama.

Data dari 6 bulan terakhir

Anda juga dapat menggunakan Filter Waktu untuk hanya mengekspor data terbaru, bukan korpus lengkap.

Asumsikan tanggal hari ini adalah 2024-10-01 dan Anda ingin mengekspor data selama 6 bulan terakhir. Pertama, Anda mengirim permintaan yang diautentikasi ke endpoint InitiatePortabilityArchive dengan start_time "2024-04-01T00:00:00Z".

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"],
"start_time": "2024-04-01T00:00:00Z"}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate

Untuk akses berbasis waktu, tindakan ini akan menampilkan:

{
  "archiveJobId": "job_id_1"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}

Buat permintaan 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/job_id_1/portabilityArchiveState

Setelah tugas selesai, responsnya akan berupa:

{
  "state": "COMPLETE",
  "urls": [
    "signed_urls"
  ],
  "start_time": "2024-04-01T00:00:00Z",
  "export_time": "2024-10-01T00:00:00Z"
}

Perhatikan bahwa start_time adalah start_time yang ditentukan di langkah 1 dan export_time adalah stempel waktu saat panggilan ke InitiatePortabilityArchive dilakukan di langkah 1.

Pastikan ekspor hanya berisi data dari enam bulan terakhir.

Data dari jangka waktu tertentu

Anda dapat menggunakan Filter Waktu untuk mengekspor data dari rentang tanggal tertentu, seperti data hanya dari tahun 2023.

Pertama, Anda mengirim permintaan yang diautentikasi ke endpoint InitiatePortabilityArchive dengan start_time "2023-01-01T00:00:00Z" dan end_time "2023-12-31T23:59:59Z".

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"],
"start_time": "2023-01-01T00:00:00Z",
"end_time": "2023-12-31T23:59:59Z"}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate

Untuk akses berbasis waktu, tindakan ini akan menampilkan:

{
  "archiveJobId": "job_id_1"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}

Buat permintaan 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/job_id_1/portabilityArchiveState

Setelah tugas selesai, responsnya akan berupa:

{
  "state": "COMPLETE",
  "urls": [
    "signed_urls"
  ],
  "start_time": "2023-01-01T00:00:00Z",
  "export_time": "2023-12-31T23:59:59Z"
}

Perhatikan bahwa start_time adalah start_time yang ditentukan pada langkah 1 dan export_time sama dengan end_time yang diberikan pada langkah 1.

Pastikan ekspor hanya berisi data dari tahun 2023.

Cakupan yang didukung

Cakupan berikut mendukung Filter Waktu:

https://www.googleapis.com/auth/dataportability.myactivity.youtube
https://www.googleapis.com/auth/dataportability.myactivity.maps
https://www.googleapis.com/auth/dataportability.myactivity.search
https://www.googleapis.com/auth/dataportability.myactivity.myadcenter
https://www.googleapis.com/auth/dataportability.myactivity.shopping
https://www.googleapis.com/auth/dataportability.myactivity.play
https://www.googleapis.com/auth/dataportability.chrome.history

Perhatian: Permintaan yang difilter waktu yang menggabungkan cakupan yang didukung dan tidak didukung akan menghasilkan error INVALID_ARGUMENT yang menyatakan The requested resources do not support time filters.