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'

   dengan 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

Ekspor data analisis ke salah satu format berikut:

• Nilai yang dipisahkan koma (CSV)

  Pemisah defaultnya adalah karakter koma (,). Karakter pembatas yang didukung meliputi koma (,), garis vertikal (|), dan tab (\t). Konfigurasi 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 dibuat di Edge, dan data analisis kustom yang Anda tambahkan. Untuk mengetahui 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. Konfigurasi 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 Anda

Mekanisme ekspor data analisis menulis data ke Cloud Storage atau BigQuery. Agar penulisan tersebut dapat 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 individu. Kemudian, aplikasi Anda menggunakan akun layanan untuk mengakses layanan.

Akun layanan memiliki kunci akun layanan yang diwakili oleh string JSON. Saat membuat penyimpanan data Edge yang menentukan koneksi ke repositori data, Anda meneruskan kunci ini. Mekanisme ekspor data kemudian menggunakan kunci 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 servis 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 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
  • 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 ada.)

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

  • 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 ada, atau membuat peran khusus, tambahkan izin berikut ke peran:

  • 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 Vault Kredensial untuk menyimpan kredensial yang digunakan untuk mengakses repositori data ekspor Anda secara 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 Anda mulai mendownload data dalam jumlah besar, Anda dapat dengan cepat memperbaiki masalah apa pun pada setelan Anda.

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. dan pilih organisasi Anda.

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

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

3. Pilih tombol + Add Datastore. Anda akan diminta 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 daftar drop-down. Pastikan Anda memilih kredensial yang sesuai untuk jenis repositori data.

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

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

7. Masukkan properti khusus untuk jenis repositori data:

   • Untuk Google Cloud Storage:

     Properti	Deskripsi	Wajib?
     Project ID	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 Storage di dokumentasi Google Cloud Platform.	Ya
     Jalur	Direktori tempat menyimpan data analisis di bucket Cloud Storage.	Ya

   • Untuk BigQuery:

     Properti	Deskripsi	Wajib?
     Project ID	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 datanya ingin Anda ekspor. 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 bahwa 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 berhasil, Simpan penyimpanan data.

Mengubah penyimpanan data

Untuk mengubah penyimpanan data:

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

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

3. Arahkan kursor mouse ke kolom Diubah dari 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 sampel data di repositori data.

   Jika pengujian gagal, perbaiki masalah dan coba lagi pengujian.

6. Setelah pengujian koneksi berhasil, Perbarui penyimpanan data.

Mengekspor data analisis

Untuk mengekspor data analisis, kirim 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
• Data store name
• Apakah monetisasi diaktifkan di organisasi

Contoh permintaan ekspor diberikan di bawah. Untuk mengetahui deskripsi lengkap properti isi permintaan, lihat Referensi properti permintaan ekspor.

Respons dari POST ada 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, aplikasi 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 akan ditetapkan ke completed. Kemudian, Anda dapat mengakses data analisis di repositori data.

Contoh 1: Mengekspor data ke Cloud Storage

Permintaan berikut mengekspor set 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 dibatasi 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 dalam dua contoh sebelumnya.
• Ekspor data monetisasi untuk mengekspor data khusus monetisasi.

Untuk melakukan ekspor data monetisasi, tentukan "dataset":"mint" di 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 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 Anda memiliki dua lingkungan di organisasi, 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 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 melampaui kuota panggilan, API akan menampilkan respons HTTP 429.

Melihat status semua permintaan ekspor analisis

Untuk melihat status semua permintaan ekspor analisis, kirim 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 dalam antrean (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, kirim 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 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 disetel ke "0 detik".

Referensi properti permintaan ekspor

Tabel berikut menjelaskan properti yang dapat Anda teruskan di 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"
  }