Menggunakan GraphQL

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

Kebijakan GraphQL dapat mengurai payload permintaan GraphQL menjadi variabel alur pesan, memverifikasi permintaan terhadap skema GraphQL, atau keduanya.

Kebijakan GraphQL dapat mengurai payload GraphQL menjadi variabel alur pesan, memverifikasi permintaan GraphQL terhadap skema, atau keduanya.

Anda dapat menggunakan kebijakan GraphQL untuk:

• Pastikan API Anda hanya memproses permintaan yang sesuai dengan skema yang Anda berikan.
• Terapkan batasan pada payload dengan menetapkan jumlah maksimum fragmen yang diizinkan.
• Mengaitkan GraphQL dengan produk API.
• Manfaatkan fitur kebijakan Oauth2, VerifyAPIKey, dan Quota, seperti halnya di REST.

GraphQL mendukung jenis payload berikut:

• POST payload graphQL dengan Content-Type : application/graphql
• POST payload graphQL dengan Content-Type: applcation/json
• GET payload graphQL dengan payload adalah parameter kueri

Catatan: Untuk payload application/json dalam bentuk

{
"query": "...",
"operationName": "...",
"variables": { "myVariable": "someValue", ... }
}

Apigee saat ini mengabaikan kolom operationName dan variables opsional.

Untuk ringkasan singkat opsi kebijakan GraphQL, lihat Opsi GraphQL di bawah.

Untuk mempelajari GraphQL lebih lanjut, lihat GraphQL.org.

Contoh

Contoh berikut menunjukkan cara mengupload skema GraphQL ke Apigee, dan menggunakannya untuk memvalidasi permintaan dengan konten GraphQL.

Perhatian: Memverifikasi payload terhadap skema umumnya merupakan operasi yang mahal, dan sebaiknya Anda memilih untuk melakukan validasi skema dengan hati-hati. Operasi validasi skema dapat memerlukan CPU yang intensif, terutama jika payload dan skema bersifat kompleks, dan dapat menyebabkan latensi yang signifikan.

Catatan: Anda hanya dapat memberikan satu skema per kebijakan. Jika Anda perlu menyertakan beberapa skema, tambahkan beberapa kebijakan GraphQL ke proxy Anda.

Catatan: Khusus untuk Editor Proxy klasik:

• Anda hanya dapat mengupload file skema GraphQL saat menambahkan kebijakan GraphQL. Anda tidak dapat menguploadnya di panel Resources di Proxy Editor.
• Setelah mengupload file skema GraphQL, Anda tidak dapat melihat atau mengeditnya di Editor Proxy.

Batasan ini tidak berlaku untuk Editor Proxy baru.

Membuat file skema

Untuk menjalankan contoh, buat file skema GraphQL terlebih dahulu dengan konten berikut:

type Query {
  allPersons(last: Int): [Person!]!
}

type Mutation {
  createPerson(name: String!, age: Int!): Person!
}

type Subscription {
  newPerson: Person!
}

type Person {
  name: String!
  sex: String!
  age: Int!
  posts: [Post!]!
}

type Post {
  title: String!
  author: Person!
}

Simpan file dengan nama apa pun yang ingin Anda gunakan, diikuti dengan ekstensi .graphql.

Menambahkan kebijakan GraphQL di UI Apigee

Catatan: Apigee memperkenalkan Editor Proxy versi baru, yang akan mempermudah pengelolaan proxy.

Petunjuk di dua tab pertama di bawah menjelaskan cara menggunakan Editor Proxy baru atau Editor Proxy klasik.

Editor Proxy Baru

Pertama, buat kebijakan GraphQL sebagai berikut:

1. Login ke UI Apigee.
2. Di menu navigasi, pilih Develop > API Proxies.
3. Dalam daftar proxy, pilih proxy API yang ingin Anda gunakan kebijakan GraphQL-nya.
4. Klik tab DEVELOP.
5. Di panel kiri, klik tombol + di samping folder Policies.

6. Pada dialog Create policy, klik di kolom Select policy type, lalu scroll ke bawah ke Mediation dan pilih GraphQL.

   

   Masukkan Nama tampilan dan Nama.

   Selanjutnya, pilih file skema GraphQL sebagai berikut:

   1. Klik kolom Schema File. Tindakan ini akan menampilkan pilihan berikut:
      • Tanpa Skema. Jika Anda memilih opsi ini, Apigee tidak akan menggunakan skema untuk memvalidasi permintaan.
      • Mengimpor skema GraphQL (.graphql)

   2. Pilih Impor skema GraphQL (.graphql). Tindakan ini akan menampilkan hal berikut:

      

   3. Klik Pilih File, lalu pilih file skema yang Anda buat sebelumnya (yang harus memiliki ekstensi .graphql). File akan muncul di kolom Nama skema.

      
7. Klik Create untuk membuat kebijakan.

Setelah membuat kebijakan GraphQL, Anda dapat melampirkan kebijakan tersebut ke langkah dalam PreFlow:

1. Pilih Endpoint Proxy > default > PreFlow di panel kiri:

   

2. Klik tombol + di samping PreFlow di panel Response di kanan bawah Editor Visual:

   

3. Pada dialog Tambahkan langkah kebijakan, pilih kebijakan GQL-.
   Catatan:Contoh ini menggunakan nama default, GQL, untuk kebijakan GraphQL. Anda dapat mengubah nama di elemen DisplayName dalam XML untuk kebijakan, dengan menambahkan frasa deskriptif setelah GQL-. Lihat Mengubah nama kebijakan.
4. Klik Tambahkan untuk melampirkan kebijakan.
5. Klik Simpan untuk menyimpan revisi saat ini dengan perubahan Anda.
6. Untuk men-deploy perubahan, klik tab Ringkasan, lalu pilih Deploy.

Lihat Opsi GraphQL di bawah untuk mengetahui opsi yang dapat Anda tetapkan untuk kebijakan GraphQL.

Editor Proxy Klasik

1. Login ke UI Apigee.
2. Di menu navigasi, pilih Develop > API Proxies.
3. Dalam daftar proxy, pilih proxy API yang ingin Anda gunakan kebijakan GraphQL-nya.
4. Klik tab DEVELOP.

5. Di panel Flow: PreFlow, klik tombol + Step.

   

6. Di panel Add Step, scroll ke bawah ke bagian Mediation, lalu pilih GraphQL.

   

   Panel Tambahkan Langkah menampilkan opsi berikut:

   • Nama Tampilan: Nama tampilan kebijakan.
   • Nama: Nama internal kebijakan.
   • File skema: Opsi untuk mengupload file yang berisi skema GraphQL yang akan digunakan Apigee untuk memvalidasi permintaan dengan konten GraphQL.

   Untuk menggunakan skema, lakukan hal berikut:

   1. Klik kolom Schema File. Tindakan ini akan menampilkan pilihan berikut:
      • Tanpa Skema. Jika Anda memilih opsi ini, Apigee tidak akan menggunakan skema untuk memvalidasi permintaan.
      • Mengimpor skema GraphQL (.graphql)

   2. Pilih Impor skema GraphQL (.graphql). Tindakan ini akan menampilkan hal berikut:

      

   3. Klik Pilih File, lalu pilih file skema yang Anda buat sebelumnya (yang harus memiliki ekstensi .graphql). File akan muncul di kolom Nama skema.

      

7. Klik Tambahkan. Panel Flow: PreFlow kini muncul seperti yang ditunjukkan di bawah ini:

   

   Lihat Opsi GraphQL di bawah untuk mengetahui opsi yang dapat Anda tetapkan untuk kebijakan GraphQL. Untuk contoh ini, biarkan apa adanya.

8. Untuk men-deploy proxy, klik tab Ringkasan, lalu pilih Deploy.

   

Sekarang Anda dapat menguji kebijakan GraphQL dengan perintah curl berikut:

curl --location --request POST 'https://PROXY_BASEPATH/HOST_NAME' --data-raw 'query query_name {allPersons {name}}' -k

Dengan PROXY_BASEPATH adalah jalur dasar proxy dan HOST_NAME adalah nama proxy Anda, termasuk nomor revisi terbaru. Saat Anda menjalankan perintah, Apigee akan memvalidasi permintaan terhadap skema dan menampilkan output berikut.

{
  "query query_name {allPersons {name}}": "",
  "id": 101
}

Berikut adalah contoh permintaan lainnya:

curl --location --request POST 'https://PROXY_BASEPATH/HOST_NAME' --data-raw 'query ilovegql {DEADBEEF}' -k

Kali ini validasi permintaan gagal dengan pesan error berikut.

{"fault":{"faultstring":"steps.graphQL.SchemaValidationFailed","detail":{"errorcode":"steps.graphQL.SchemaValidationFailed"}}}

Opsi GraphQL

GraphPolicy memiliki opsi berikut:

• OperationType: Jenis operasi. Opsi yang tersedia:
  • query: GraphQL yang setara dengan operasi GET REST.
  • mutation: GraphQL yang setara dengan operasi PUT REST.
  • query_mutation: query dan mutation.
• MaxDepth: Kedalaman maksimum kueri, saat direpresentasikan sebagai hierarki. MaxDepth memungkinkan Anda memblokir kueri mendalam dalam payload, sehingga Apigee tidak perlu membuat variabel flow yang sangat besar untuk menyimpan nilai. Namun, payload dikirim apa adanya, terlepas dari nilai MaxDepth.
• MaxCount: Jumlah maksimum fragmen yang dapat ada dalam payload. Anda dapat menggunakannya untuk mencegah server backend GraphQL pelanggan menjalankan kueri yang sangat kompleks, sehingga memaksa klien untuk memecah logikanya menjadi payload yang lebih kecil.
• Action: Salah satu tindakan GraphQL berikut:
  • parseApigee mengurai payload GraphQL menjadi variabel alur. Anda kemudian dapat menggunakan konten variabel alur dalam kebijakan seperti JavaCallout. Perhatikan bahwa parse juga memverifikasi payload.
  • verify: Apigee memverifikasi bahwa payload GraphQL sesuai dengan skema yang diupload ke proxy. Anda dapat menggunakan verify untuk memastikan bahwa Anda tidak mendapatkan permintaan yang tidak sesuai dengan skema Anda. Hal ini dapat menghemat waktu CPU yang berharga di backend.
  • parse_verify: Mengurai dan memverifikasi payload.
• ResourceURL: Jalur ke file skema GraphQL yang digunakan Apigee untuk memverifikasi permintaan GraphQL.`

Untuk mempelajari opsi ini lebih lanjut, lihat halaman referensi kebijakan GraphQL.