Menggunakan GraphQL

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat Dokumentasi Apigee Edge.

Kebijakan GraphQL dapat mengurai payload permintaan GraphQL ke dalam alur pesan variabel, verifikasi permintaan terhadap skema GraphQL, atau keduanya.

The GraphQL policy can parse GraphQL payloads into message flow variables, verify GraphQL requests against a schema, or both.

You can use the GraphQL policy to:

• Ensure that your APIs only process requests that conform to the schema you provide.
• Impose restrictions on the payload by setting a maximum on the number of fragments allowed.
• Associate GraphQL with API products.
• Leverage the Oauth2, VerifyAPIKey, and Quota policy features, just as in REST.

GraphQL supports the following types of payloads:

• POST of graphQL payloads with Content-Type : application/graphql
• POST of graphQL payloads with Content-Type: applcation/json
• GET of graphQL payloads where the payload is a query parameter

Note: For application/json payloads of the form

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

Apigee currently ignores the optional operationName and variables fields.

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

Untuk mempelajari lebih lanjut tentang GraphQL, 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 operasi yang mahal, dan kami sarankan memilih untuk melakukan validasi skema dengan hati-hati. Operasi validasi skema bisa menghabiskan banyak CPU, terutama ketika payload dan skema bersifat kompleks, dan dapat menghasilkan latensi yang signifikan.

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

Catatan: Hanya 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 Proxy Editor baru.

Membuat file skema

Untuk menjalankan contoh, pertama-tama buat file skema GraphQL 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 yang ingin Anda gunakan, diikuti dengan ekstensi .graphql.

Menambahkan kebijakan GraphQL di UI Apigee

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

Petunjuk pada dua tab pertama di bawah ini menjelaskan cara gunakan 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 > Proxy API.
3. Dalam daftar proxy, pilih proxy API tempat Anda ingin menggunakan kebijakan GraphQL.
4. Klik tab PENGEMBANGAN.
5. Di panel sebelah kiri, klik tombol + di samping folder Policies.

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

   

   Masukkan Nama tampilan dan Nama.

   Berikutnya, pilih file skema GraphQL sebagai berikut:

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

   2. Pilih Import GraphQL schema (.graphql). Tindakan ini akan menampilkan berikut ini:

      

   3. Klik Choose File dan pilih file skema yang dibuat sebelumnya (yang harus memiliki ekstensi .graphql). File muncul di kolom Nama skema.

      
7. Klik Create untuk membuat kebijakan.

Setelah membuat kebijakan GraphQL, Anda dapat menyertakannya ke langkah di PreFlow:

1. Pilih Proxy Endpoints > default > PreFlow di di panel sebelah kiri:

   

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

   

3. Di dialog Add policy step, pilih kebijakan GQL-.
   Catatan:Contoh ini menggunakan nama default, GQL, untuk GraphQL lebih lanjut. Anda dapat mengubah nama di elemen DisplayName di XML untuk kebijakan izin yang relevan, dengan menambahkan frasa deskriptif setelah GQL-. Lihat Ubah nama kebijakan.
4. Klik Add untuk melampirkan kebijakan.
5. Klik Save untuk menyimpan revisi saat ini dengan perubahan Anda.
6. Untuk men-deploy perubahan, klik tab Overview dan pilih Deploy.

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

Editor Proxy Klasik

1. Login ke UI Apigee.
2. Di menu navigasi, pilih Develop > Proxy API.
3. Dalam daftar proxy, pilih proxy API tempat Anda ingin menggunakan kebijakan GraphQL.
4. Klik tab PENGEMBANGAN.

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

   

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

   

   Panel Add Step 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:
      • Tidak Ada Skema. Jika Anda memilih opsi ini, Apigee tidak akan menggunakan skema untuk memvalidasi permintaan.
      • Mengimpor skema GraphQL (.graphql)

   2. Pilih Import GraphQL schema (.graphql). Tindakan ini akan menampilkan berikut ini:

      

   3. Klik Choose File dan pilih file skema yang dibuat sebelumnya (yang harus memiliki ekstensi .graphql). File muncul di kolom Nama skema.

      

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

   

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

8. Untuk men-deploy proxy, klik tab Overview dan 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 basis proxy dan HOST_NAME adalah nama {i>proxy<i} Anda, termasuk nomor revisi terbaru. Jika Anda jalankan perintah, Apigee memvalidasi permintaan terhadap skema dan menampilkan {i>output<i} tersebut.

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

Berikut contoh lain permintaan:

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. Opsinya adalah:
  • 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, jika direpresentasikan sebagai hierarki. MaxDepth memungkinkan Anda memblokir kueri yang mendalam di 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 berada dalam payload. Anda dapat menggunakannya untuk mencegah server back-end GraphQL pelanggan menjalankan kueri kompleks, yang memaksa klien untuk memecah logika mereka menjadi {i>payload<i} yang lebih kecil.
• Action: Salah satu tindakan GraphQL berikut:
  • parseApigee mengurai payload GraphQL ke dalam variabel flow. Anda selanjutnya dapat menggunakan konten variabel flow dalam kebijakan seperti Javacallout. Perlu diketahui bahwa parse juga memverifikasi payload.
  • verify: Apigee memverifikasi bahwa payload GraphQL sesuai dengan skema diunggah 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 Referensi kebijakan GraphQL halaman.