Mengekspor data dari Analytics

Anda sedang melihat dokumentasi Apigee Edge.
Buka dokumentasi Apigee X. info

Menyiapkan izin untuk agen layanan yang ditetapkan

Untuk menyiapkan izin bagi agen layanan yang ditetapkan, sebagai persiapan untuk perubahan yang dijelaskan di atas, lakukan langkah-langkah berikut.

1. Temukan nama agen layanan Google Cloud Anda dengan memasukkan perintah berikut:

   curl -X GET \
     "https://api.enterprise.apigee.com/v1/organizations/ORG" \
     -u email:password \
     | jq -r '.properties.property[] | select(.name=="serviceAgent.analytics") | .value'

   adalah ORG adalah organisasi Anda. Tindakan ini akan menampilkan nama dan nilai agen layanan seperti yang ditunjukkan di bawah:

   "property" : [
     {
      "name" : "serviceAgent.analytics",
      "value" : "service-9q1ibk@gcp-sa-apigee-uap.iam.gserviceaccount.com"
      },

2. Buka dasbor IAM di Konsol Google Cloud.
3. Pilih project Google Cloud Anda.
4. Klik Add di bagian atas panel IAM.
5. Di kolom New principals, masukkan agen layanan value yang ditampilkan di langkah 1. Misalnya, value yang ditampilkan pada langkah 1 adalah service-9q1ibk@gcp-sa-apigee-uap.iam.gserviceaccount.com.
6. Klik tombol +Add Another Role, lalu tambahkan peran berikut:
   • Pengguna BigQuery
   • Storage Admin
7. Klik Simpan.

Data Analisis Apigee

Format data ekspor

Ekspor data analisis ke salah satu format berikut:

• Nilai yang dipisahkan koma (CSV)

  Pemisah defaultnya adalah karakter koma (,). Karakter pembatas yang didukung meliputi koma (,), pipa (|), dan tab (\t). Konfigurasikan nilai menggunakan properti csvDelimiter, seperti yang dijelaskan dalam Ekspor referensi properti permintaan .

• JSON (dibatasi baris baru)

  Memungkinkan karakter baris baru digunakan sebagai pembatas.

Data yang diekspor mencakup semua metrik dan dimensi analisis yang terintegrasi dalam Edge, serta data analisis kustom yang Anda tambahkan. Untuk deskripsi data yang diekspor, lihat Referensi metrik, dimensi, dan filter Analytics.

Anda dapat mengekspor data analisis ke repositori data berikut:

• Google Cloud Storage
• Google BigQuery

Ringkasan proses ekspor

Langkah-langkah berikut meringkas proses yang digunakan untuk mengekspor data analisis:

1. Konfigurasi repositori data Anda (Cloud Storage atau BigQuery) untuk ekspor data. Anda harus memastikan repositori data Anda telah dikonfigurasi dengan benar, dan akun layanan yang digunakan untuk menulis data ke repositori data memiliki izin yang benar.

2. Buat penyimpanan data yang menentukan properti repositori data (Cloud Storage atau BigQuery) tempat Anda mengekspor data, termasuk kredensial yang digunakan untuk mengakses repositori data.

   Saat membuat penyimpanan data, Anda mengupload kredensial repositori data ke Edge Credentials Vault untuk menyimpannya dengan aman. Mekanisme ekspor data kemudian menggunakan kredensial tersebut untuk menulis data ke repositori data Anda.

3. Gunakan API ekspor data untuk memulai ekspor data. Ekspor data berjalan secara asinkron di latar belakang.

4. Gunakan API ekspor data untuk menentukan kapan ekspor selesai.

5. Setelah ekspor selesai, akses data yang diekspor di repositori data Anda.

Bagian berikut menjelaskan langkah-langkah ini secara lebih detail.

Mengonfigurasi repositori data Anda

Mekanisme ekspor data analisis menulis data ke Cloud Storage atau BigQuery. Agar penulisan tersebut terjadi, Anda harus:

• Buat akun layanan Google Cloud Platform.
• Tetapkan peran akun layanan agar dapat mengakses Cloud Storage atau BigQuery.

Membuat akun layanan untuk Cloud Storage atau BigQuery

Akun layanan adalah jenis Akun Google milik aplikasi Anda, bukan milik pengguna perorangan. Aplikasi Anda kemudian menggunakan akun layanan untuk mengakses layanan.

Akun layanan memiliki kunci akun layanan yang direpresentasikan oleh string JSON. Saat membuat penyimpanan data Edge yang menentukan koneksi ke repositori data, Anda akan meneruskan kunci ini ke sana. Mekanisme ekspor data kemudian menggunakan kunci tersebut untuk mengakses repositori data Anda.

Akun layanan yang terkait dengan kunci harus merupakan pemilik project Google Cloud Platform dan memiliki akses tulis ke bucket Google Cloud Storage. Untuk membuat kunci layanan dan mendownload payload yang diperlukan, lihat Membuat dan Mengelola Kunci Akun Layanan dalam dokumentasi Google Cloud Platform.

Misalnya, saat pertama kali mendownload kunci, kunci akan diformat sebagai objek JSON:

{ 
  "type": "service_account", 
  "project_id": "myProject", 
  "private_key_id": "12312312", 
  "private_key": "-----BEGIN PRIVATE KEY-----\n...", 
  "client_email": "client_email@developer.gserviceaccount.com", 
  "client_id": "879876769876", 
  "auth_uri": "https://accounts.google.com/organizations/oauth2/auth", 
  "token_uri": "https://oauth2.googleapis.com/token", 
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2", 
  "client_x509_cert_url": "https://www.googleapis.com" 
}

Mengonfigurasi Google Cloud Storage

Sebelum Anda dapat mengekspor data ke Google Cloud Storage:

• Pastikan API BigQuery dan Cloud Resource Manager diaktifkan di project Google Cloud Platform Anda. Lihat Mengaktifkan API untuk mengetahui petunjuknya. Apigee menggunakan BigQuery API untuk memanfaatkan fitur BigQuery Export saat mengekspor ke Cloud Storage dan Cloud Resource Manager API untuk memeriksa izin sebelum setiap ekspor.

• Pastikan akun layanan ditetapkan ke peran berikut:

  • BigQuery Job User
  • Storage Object Creator
  • Admin Penyimpanan (hanya diperlukan untuk menguji penyimpanan data seperti yang dijelaskan dalam Menguji konfigurasi penyimpanan data. Jika peran ini terlalu luas, Anda dapat menambahkan izin storage.buckets.get ke peran yang sudah ada.)

  Atau, jika Anda ingin mengubah peran yang ada atau membuat peran khusus, tambahkan izin berikut pada peran tersebut:

  • bigquery.jobs.create
  • storage.objects.create
  • storage.buckets.get (hanya diperlukan untuk menguji penyimpanan data seperti yang dijelaskan dalam Menguji konfigurasi penyimpanan data)

Mengonfigurasi Google BigQuery

Sebelum Anda dapat mengekspor data ke Google BigQuery:

• Pastikan API BigQuery dan Cloud Resource Manager diaktifkan di project Google Cloud Platform Anda. Lihat Mengaktifkan API untuk mengetahui petunjuknya. Apigee menggunakan Cloud Resource Manager API untuk memeriksa izin sebelum setiap ekspor.
• Pastikan BigQuery API diaktifkan di project Google Cloud Platform Anda. Lihat Mengaktifkan dan Menonaktifkan API untuk mengetahui petunjuknya.

• Pastikan akun layanan ditetapkan ke peran berikut:

  • BigQuery Job User
  • Editor Data BigQuery

  Jika Anda ingin mengubah peran yang sudah ada atau membuat peran khusus, tambahkan izin berikut pada peran tersebut:

  • bigquery.datasets.create
  • bigquery.datasets.get
  • bigquery.jobs.create
  • bigquery.tables.create
  • bigquery.tables.get
  • bigquery.tables.updateData

Membuat penyimpanan data

Penyimpanan data menentukan koneksi ke repositori data ekspor Anda (Cloud Storage, BigQuery), termasuk kredensial yang digunakan untuk mengakses repositori data.

Tentang Vault Kredensial Edge

Edge menggunakan Credentials Vault untuk menyimpan kredensial yang digunakan untuk mengakses repositori data ekspor Anda dengan aman. Agar layanan dapat mengakses kredensial di Edge Credentials Vault, Anda harus menentukan konsumen kredensial.

Saat membuat penyimpanan data menggunakan UI Edge, seperti yang dijelaskan di bawah, Edge secara otomatis membuat pengguna yang digunakan untuk mengakses kredensial.

Menguji konfigurasi penyimpanan data

Saat Anda membuat penyimpanan data, Edge tidak menguji atau memvalidasi bahwa kredensial dan konfigurasi repositori data Anda valid. Artinya, Anda dapat membuat penyimpanan data dan tidak mendeteksi error apa pun sampai Anda menjalankan ekspor data pertama.

Atau, uji konfigurasi penyimpanan data sebelum membuatnya. Pengujian berguna karena proses ekspor data yang besar dapat memerlukan waktu lama untuk dijalankan. Dengan menguji kredensial dan konfigurasi penyimpanan data sebelum mulai mendownload data dalam jumlah besar, Anda dapat dengan cepat memperbaiki semua masalah terkait setelan.

Jika pengujian berhasil, buat penyimpanan data. Jika pengujian gagal, perbaiki error, lalu uji ulang konfigurasi. Anda hanya membuat penyimpanan data setelah pengujian berhasil.

Untuk mengaktifkan fitur pengujian, Anda harus:

• Pastikan Cloud Resource Manager API diaktifkan di project Google Cloud Platform Anda. Lihat Mengaktifkan dan Menonaktifkan API untuk mengetahui petunjuknya.

Membuat penyimpanan data

Untuk membuat penyimpanan data di UI:

1. Login ke https://apigee.com/edge sebagai administrator org, lalu pilih organisasi Anda.

   CATATAN: Anda harus menjadi administrator organisasi Edge agar dapat membuat penyimpanan data.

2. Pilih Admin > Analytics Datastores dari menu navigasi sebelah kiri. Halaman Analytics Datastores akan ditampilkan.

3. Pilih tombol + Add Datastore. Anda akan diminta untuk memilih jenis penyimpanan data:

   

4. Pilih jenis target ekspor data:

   • Google Cloud Storage
   • Google BigQuery

   Halaman konfigurasi akan muncul:

   

5. Masukkan Nama penyimpanan data.

6. Pilih kredensial yang digunakan untuk mengakses repositori data. Menu drop-down untuk kredensial yang tersedia akan muncul.

   Kredensial bersifat khusus untuk jenis repositori data. Lihat Membuat akun layanan untuk Cloud Storage atau BigQuery guna mengetahui informasi selengkapnya.

   • Jika Anda telah mengupload kredensial, pilih kredensial dari menu drop-down. Pastikan Anda memilih kredensial yang sesuai untuk jenis repositori data.

   • Jika Anda menambahkan kredensial baru ke penyimpanan data, pilih Tambahkan baru. Di kotak dialog, masukkan:

     1. Nama kredensial.
     2. Konten kredensial adalah kunci akun layanan JSON khusus untuk repositori data Anda seperti yang ditentukan dalam artikel Membuat akun layanan untuk Cloud Storage atau BigQuery.
     3. Pilih Create.

7. Masukkan properti khusus untuk jenis repositori data:

   • Untuk Google Cloud Storage:

     Properti	Deskripsi	Wajib diisi?
     Project ID	ID Project Google Cloud Platform. Untuk membuat project Google Cloud Platform, lihat Membuat dan Mengelola Project dalam dokumentasi Google Cloud Platform.	Ya
     Nama Bucket	Nama bucket di Cloud Storage tempat Anda ingin mengekspor data analisis. Bucket harus ada sebelum Anda melakukan ekspor data. Untuk membuat bucket Cloud Storage, lihat Membuat Bucket Storage dalam dokumentasi Google Cloud Platform.	Ya
     Jalur	Direktori tempat menyimpan data analisis di bucket Cloud Storage.	Ya

   • Untuk BigQuery:

     Properti	Deskripsi	Wajib diisi?
     Project ID	ID Project Google Cloud Platform. Untuk membuat project Google Cloud Platform, lihat Membuat dan Mengelola Project dalam dokumentasi Google Cloud Platform.	Ya
     Nama Set Data	Nama set data BigQuery yang ingin Anda ekspor data analisisnya. Pastikan set data dibuat sebelum meminta ekspor data. Untuk membuat set data BigQuery, lihat Membuat dan Menggunakan Set Data dalam dokumentasi Google Cloud Platform.	Ya
     Awalan Tabel	Awalan untuk nama tabel yang dibuat untuk data analisis dalam set data BigQuery.	Ya

8. Pilih Uji koneksi untuk memastikan bahwa kredensial dapat digunakan untuk mengakses repositori data.

   Jika pengujian berhasil, simpan penyimpanan data Anda.

   Jika pengujian gagal, perbaiki masalah yang ada dan coba lagi pengujian. Arahkan mouse ke pesan error di UI untuk menampilkan informasi tambahan dalam tooltip.

9. Setelah pengujian koneksi lulus, Simpan penyimpanan data.

Mengubah penyimpanan data

Untuk mengubah penyimpanan data:

1. Login ke https://apigee.com/edge sebagai administrator org, lalu pilih organisasi Anda.

2. Pilih Admin > Analytics Datastores dari menu navigasi sebelah kiri. Halaman Analytics Datastores akan ditampilkan.

3. Arahkan kursor mouse ke kolom Diubah dalam laporan untuk diubah. Ikon edit dan hapus akan muncul.

4. Edit atau hapus penyimpanan data.

5. Jika Anda mengedit penyimpanan data, pilih Uji koneksi untuk memastikan bahwa kredensial dapat digunakan untuk mengakses penyimpanan data.

   Jika pengujian berhasil, Anda dapat melihat data sampel di repositori data Anda.

   Jika pengujian gagal, perbaiki masalah yang ada dan coba lagi pengujian.

6. Setelah pengujian koneksi lulus, Update penyimpanan data.

Mengekspor data analisis

Untuk mengekspor data analisis, kirimkan permintaan POST ke /analytics/exports API. Teruskan informasi berikut dalam isi permintaan:

• Nama dan deskripsi permintaan ekspor
• Rentang tanggal data yang diekspor (nilai hanya dapat mencakup satu hari)
• Format data yang diekspor
• Nama penyimpanan data
• Apakah monetisasi diaktifkan di organisasi

Contoh permintaan ekspor disediakan di bawah. Untuk deskripsi lengkap tentang properti isi permintaan, lihat Referensi properti permintaan ekspor.

Tanggapan dari POST adalah dalam bentuk:

{
    "self": "/organizations/myorg/environments/test/analytics/exports/a7c2f0dd-1b53-4917-9c42-a211b60ce35b",
    "created": "2017-09-28T12:39:35Z",
    "state": "enqueued"
}

Perhatikan bahwa properti state dalam respons disetel ke enqueued. Permintaan POST bekerja secara asinkron. Itu berarti permintaan akan terus berjalan di latar belakang setelah permintaan menampilkan respons. Nilai yang memungkinkan untuk state mencakup: enqueued, running, completed, failed.

Gunakan URL yang ditampilkan di properti self untuk melihat status permintaan ekspor data, seperti yang dijelaskan dalam Melihat status permintaan ekspor Analytics. Setelah permintaan selesai, nilai properti state dalam respons ditetapkan ke completed. Anda kemudian dapat mengakses data analisis di repositori data Anda.

Contoh 1: Mengekspor data ke Cloud Storage

Permintaan berikut mengekspor kumpulan lengkap data mentah selama 24 jam terakhir dari lingkungan test dalam organisasi myorg. Konten diekspor ke Cloud Storage dalam JSON:

curl -X POST -H "Content-Type:application/json" \
"https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/analytics/exports" \
  -d \
  '{
    "name": "Export raw results to Cloud Storage",
    "description": "Export raw results to Cloud Storage for last 24 hours",
    "dateRange": {
      "start": "2018-06-08", 
      "end": "2018-06-09"
    },
    "outputFormat": "json",
    "datastoreName": "My Cloud Storage data repository"
  }' \
  -u orgAdminEmail:password

Gunakan URI yang ditentukan oleh properti self untuk memantau status tugas seperti yang dijelaskan dalam artikel Melihat status permintaan ekspor Analytics.

Contoh 2: Mengekspor data ke BigQuery

Permintaan berikut mengekspor file CSV yang dipisahkan koma ke BigQuery:

curl -X POST -H "Content-Type:application/json"  \
  "https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/analytics/exports" \
  -d \
  '{
    "name": "Export query results to BigQuery",
    "description": "One-time export to BigQuery",
    "dateRange": {
      "start": "2018-06-08", 
      "end": "2018-06-09"
    },
    "outputFormat": "csv",
    "csvDelimiter": ",", 
    "datastoreName": "My BigQuery data repository"
  }' \
  -u orgAdminEmail:password

Catatan: File CSV yang diekspor akan membuat tabel BigQuery dengan awalan berikut:

<PREFIX>_<EXPORT_DATE>_api_<UUID>_from_<FROM_DATE>_to_<TO_DATE>

Gunakan URI yang ditentukan oleh properti self untuk memantau status tugas seperti yang dijelaskan dalam Melihat status permintaan ekspor Analytics.

Contoh 3: Mengekspor data monetisasi

Jika monetisasi diaktifkan di lingkungan dalam organisasi, Anda dapat melakukan dua jenis ekspor data:

• Ekspor data standar seperti yang ditunjukkan pada dua contoh sebelumnya.
• Ekspor data monetisasi untuk mengekspor data khusus monetisasi.

Untuk melakukan ekspor data monetisasi, tentukan "dataset":"mint" dalam payload permintaan. Organisasi dan lingkungan harus mendukung monetisasi untuk menetapkan opsi ini. Jika tidak, hapus properti dataset dari payload:

  '{
    "name": "Export raw results to Cloud Storage",
    "description": "Export raw results to Cloud Storage for last 24 hours",
    "dateRange": {
      "start": "2018-06-08", 
      "end": "2018-06-09"
    },
    "outputFormat": "json",
    "datastoreName": "My Cloud Storage data repository",
    "dataset":"mint"
  }'

Tentang kuota API ekspor

Untuk mencegah penggunaan panggilan API ekspor data yang mahal secara berlebihan, Edge akan menerapkan kuota pada panggilan ke /analytics/exports API:

• Untuk organisasi dan lingkungan yang tidak mengaktifkan monetisasi, kuotanya adalah:

  • 70 panggilan per bulan per organisasi/lingkungan.

  Misalnya, jika memiliki dua lingkungan di organisasi Anda, prod dan test, Anda dapat melakukan 70 panggilan API per bulan untuk setiap lingkungan.

• Untuk organisasi dan lingkungan yang mengaktifkan monetisasi, kuotanya adalah:

  • 70 panggilan per bulan untuk setiap organisasi dan lingkungan untuk data standar.
  • 70 panggilan per bulan untuk setiap organisasi dan lingkungan untuk data monetisasi.

  Misalnya, jika mengaktifkan monetisasi di organisasi prod, Anda dapat melakukan 70 panggilan API untuk data standar dan 70 panggilan API tambahan untuk data monetisasi.

Jika Anda melebihi kuota panggilan, API akan menampilkan respons HTTP 429.

Melihat status semua permintaan ekspor Analytics

Untuk melihat status semua permintaan ekspor Analytics, kirimkan permintaan GET ke /analytics/exports.

Misalnya, permintaan berikut menampilkan status semua permintaan ekspor analisis untuk lingkungan test di organisasi myorg:

curl -X GET \
  "https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/analytics/exports" \
  -u email:password

Yang berikut memberikan contoh respons yang mencantumkan dua permintaan ekspor, satu diantrekan (dibuat dan dalam antrean) dan satu lagi selesai:

[
  {
    "self":
"/v1/organizations/myorg/environments/test/analytics/exports/e8b8db22-fe03-4364-aaf2-6d4f110444ba",
    "name": "Export results To Cloud Storage",
    "description": "One-time export to Google Cloud Storage",
    "userId": "my@email.com",
    "datastoreName": "My Cloud Storage data store",
    "executionTime": "36 seconds",
    "created": "2018-09-28T12:39:35Z",
    "updated": "2018-09-28T12:39:42Z",
    "state": "enqueued"
  },
  {
    "self":
"/v1/organizations/myorg/environments/test/analytics/exports/9870987089fe03-4364-aaf2-6d4f110444ba"
    "name": "Export raw results to BigQuery",
    "description": "One-time export to BigQuery",
    ... 
  }
]

Melihat status permintaan ekspor Analytics

Untuk melihat status permintaan ekspor analisis tertentu, kirimkan permintaan GET ke /analytics/exports/{exportId}, dengan {exportId} adalah ID yang terkait dengan permintaan ekspor analisis.

Misalnya, permintaan berikut menampilkan status permintaan ekspor Analytics dengan ID 4d6d94ad-a33b-4572-8dba-8677c9c4bd98.

curl -X GET \
"https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/analytics/exports/4d6d94ad-a33b-4572-8dba-8677c9c4bd98" \
-u email:password

Berikut adalah contoh responsnya:

{
  "self":
"/v1/organizations/myorg/environments/test/analytics/exports/4d6d94ad-a33b-4572-8dba-8677c9c4bd98",
  "name": "Export results To Cloud Storage",
  "description": "One-time export to Google Cloud Storage",
  "userId": "my@email.com",
  "datastoreName": "My Cloud Storage data store",
  "executionTime": "36 seconds",
  "created": "2018-09-28T12:39:35Z",
  "updated": "2018-09-28T12:39:42Z",
  "state": "enqueued"
}

Jika ekspor analisis tidak menampilkan data analisis, executionTime ditetapkan ke "0 detik".

Referensi properti permintaan ekspor

Tabel berikut menjelaskan properti yang dapat Anda teruskan dalam isi permintaan dalam format JSON saat mengekspor data analisis.

"dateRange": {
    "start": "2018-07-29",
    "end": "2018-07-30"
}

Contoh:

{
    "name": "Export raw results to Cloud Storage",
    "description": "Export raw results to Cloud Storage for last 24 hours",
    "dateRange": {
      "start": "2018-06-08", 
      "end": "2018-06-09"
    },
    "outputFormat": "json",
    "datastoreName": "My Cloud Storage data repository"
  }