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'

   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 di langkah 1 adalah service-9q1ibk@gcp-sa-apigee-uap.iam.gserviceaccount.com.
6. Klik tombol +Add Another Role dan tambahkan peran berikut:
   • BigQuery User
   • Storage Admin
7. Klik Simpan.

Data Apigee Analytics

Format data ekspor

Mengekspor data analisis ke salah satu format berikut:

• Nilai yang dipisahkan koma (CSV)

  Pemisah defaultnya adalah karakter koma (,). Karakter pemisah yang didukung mencakup koma (,), pipa (|), dan tab (\t). Konfigurasikan nilai menggunakan properti csvDelimiter, seperti yang dijelaskan dalam Referensi properti permintaan ekspor .

• JSON (dibatasi baris baru)

  Mengizinkan karakter baris baru digunakan sebagai pembatas.

Data yang diekspor mencakup semua metrik dan dimensi analisis yang disertakan 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 merangkum proses yang digunakan untuk mengekspor data analisis Anda:

1. Konfigurasikan repositori data Anda (Cloud Storage atau BigQuery) untuk ekspor data. Anda harus memastikan bahwa repositori data 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

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 yang dimiliki aplikasi Anda, bukan milik pengguna individual. Kemudian, aplikasi Anda akan 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 meneruskan kunci ini. Mekanisme ekspor data kemudian menggunakan kunci tersebut untuk mengakses repositori data Anda.

Akun layanan yang terkait dengan kunci tersebut 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 didownload, 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 dapat mengekspor data ke Google Cloud Storage:

• Pastikan BigQuery dan Cloud Resource Manager API diaktifkan di project Google Cloud Platform Anda. Lihat Mengaktifkan API untuk mengetahui petunjuknya. Apigee menggunakan BigQuery API untuk memanfaatkan fitur ekspor BigQuery 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
  • Storage Admin (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 ada.)

  Atau, jika Anda ingin mengubah peran yang ada, atau membuat peran khusus, tambahkan izin berikut ke 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 BigQuery dan Cloud Resource Manager API 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 ada, atau membuat peran khusus, tambahkan izin berikut ke 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 Edge Credentials Vault

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 akan otomatis membuat konsumen 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 hingga Anda menjalankan ekspor data pertama.

Atau, uji konfigurasi penyimpanan data sebelum membuatnya. Pengujian berguna karena proses ekspor data yang besar dapat memerlukan waktu yang lama untuk dieksekusi. Dengan menguji kredensial dan konfigurasi penyimpanan data sebelum mulai mendownload data dalam jumlah besar, Anda dapat dengan cepat memperbaiki masalah pada 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 organisasi, lalu pilih organisasi Anda.

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

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

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

   

4. Pilih jenis target data ekspor:

   • Google Cloud Storage
   • Google BigQuery

   Halaman konfigurasi akan muncul:

   

5. Masukkan Nama penyimpanan data.

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

   Kredensial khusus untuk jenis repositori data. Lihat Membuat akun layanan untuk Cloud Storage atau BigQuery untuk 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 yang khusus untuk repositori data Anda seperti yang ditentukan oleh 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?
     ID Project	ID Project Google Cloud Platform. Untuk membuat project Google Cloud Platform, lihat Membuat dan Mengelola Project di 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 Penyimpanan di dokumentasi Google Cloud Platform.	Ya
     Jalur	Direktori tempat menyimpan data analisis di bucket Cloud Storage.	Ya

   • Untuk BigQuery:

     Properti	Deskripsi	Wajib?
     ID Project	ID Project Google Cloud Platform. Untuk membuat project Google Cloud Platform, lihat Membuat dan Mengelola Project di 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 di set data BigQuery.	Ya

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

   Jika pengujian berhasil, simpan penyimpanan data Anda.

   Jika pengujian gagal, perbaiki masalah 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 organisasi, lalu pilih organisasi Anda.

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

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

4. Mengedit atau menghapus penyimpanan data.

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

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

   Jika pengujian gagal, perbaiki masalah dan coba lagi pengujian.

6. Setelah pengujian koneksi lulus, Perbarui penyimpanan data.

Mengekspor data analisis

Untuk mengekspor data analisis, buat 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 diberikan di bawah. Untuk deskripsi lengkap properti isi permintaan, lihat Referensi properti permintaan ekspor.

Respons dari POST 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 berfungsi secara asinkron. Artinya, tugas tersebut akan terus berjalan di latar belakang setelah permintaan menampilkan respons. Nilai yang mungkin 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 analisis. Saat permintaan selesai, nilai properti state dalam respons ditetapkan ke completed. Kemudian, Anda dapat mengakses data analisis di repositori data.

Contoh 1: Mengekspor data ke Cloud Storage

Permintaan berikut mengekspor kumpulan lengkap data mentah selama 24 jam terakhir dari lingkungan test di 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 Melihat status permintaan ekspor analisis.

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

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 dalam 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, hilangkan 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 export API

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

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

  • 70 panggilan per bulan per organisasi/lingkungan.

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

• Untuk organisasi dan lingkungan dengan monetisasi diaktifkan, 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 Anda 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 analisis

Untuk melihat status semua permintaan ekspor analisis, buat 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

Berikut adalah contoh respons yang mencantumkan dua permintaan ekspor, satu diantrekan (dibuat dan dalam antrean) dan satu 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 analisis

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

Misalnya, permintaan berikut menampilkan status permintaan ekspor analisis 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 respons:

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