Kebijakan GraphQL

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Lihat dokumentasi Apigee Edge.

Apa

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

Anda dapat menggunakan kebijakan GraphQL untuk:

• Pastikan API Anda hanya memproses permintaan yang sesuai dengan skema yang Anda berikan.
• Menerapkan pembatasan pada payload dengan menetapkan jumlah maksimum fragmen yang diizinkan.
• Mengaitkan GraphQL dengan produk API.
• Manfaatkan fitur kebijakan Oauth2, VerifyAPIKey, dan Kuota, seperti 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 sebagai parameter kueri

Untuk informasi selengkapnya, lihat resource berikut:

• Pengantar GraphQL
• Kueri dan Mutasi
• Referensi variabel flow

Kebijakan ini merupakan Kebijakan standar dan dapat di-deploy ke jenis lingkungan apa pun. Tidak semua pengguna perlu mengetahui tentang kebijakan dan jenis lingkungan. Untuk informasi tentang jenis kebijakan dan ketersediaan pada setiap jenis lingkungan, lihat Jenis kebijakan.

Lihat Menggunakan GraphQL untuk mengetahui contoh yang menggunakan kebijakan ini.

Elemen <GraphQL>

Menentukan kebijakan <GraphQL>.

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Source>request</Source>
  <OperationType>[query|mutuation|all]</OperationType>
  <MaxDepth>MAX_DEPTH</MaxDepth>
  <MaxCount>MAX_NUMBER_OF_QUERIES</MaxCount>
  // [Start maxpayloadsize]
  <MaxPayloadSizeInBytes>MAX_PAYLOAD_SIZE_IN_BYTES</MaxPayloadSizeInBytes>
  <Action>parse</Action>
  <ResourceURL>PATH/TO/SCHEMA.xsd</ResourceURL>
</GraphQL>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<GraphQL name="GraphQLParser">
  <Source>request</Source>
  <OperationType>query</OperationType>
  <MaxDepth>10</MaxDepth>
  <MaxCount>10</MaxCount>
  <MaxPayloadSizeInBytes></MaxPayloadSizeInBytes>
  <Action>parse</Action>
  <ResourceURL></ResourceURL>
</GraphQL>

Elemen ini memiliki atribut berikut yang sama untuk semua kebijakan:

Tabel berikut memberikan deskripsi tingkat tinggi tentang elemen turunan <GraphQL>:

Setiap elemen turunan ini dijelaskan di bagian berikutnya.

Referensi elemen turunan

Bagian ini menjelaskan elemen turunan <GraphQL>.

<Action>

Tindakan mewakili salah satu tindakan GraphQL berikut:

• parse: Apigee mengurai payload GraphQL menjadi variabel alur pesan. Lihat Contoh representasi variabel alur pesan untuk mengetahui penjelasan tentang variabel yang ditetapkan saat Action ditetapkan ke parse. Hal ini dapat menghemat waktu CPU yang berharga di backend. Perhatikan bahwa verify juga mengurai payload.
• verify: Apigee memverifikasi bahwa payload GraphQL sesuai dengan skema yang diupload ke proxy.
• parse_verify: Apigee mengurai dan memverifikasi permintaan GraphQL.

Elemen <Action> menggunakan sintaksis berikut:

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Action>parse</Action>
</GraphQL>

<MaxCount>

Jumlah fragmen maksimum yang dapat berada dalam payload. Anda dapat menggunakan cara ini untuk mencegah server back-end GraphQL pelanggan mengeksekusi kueri yang sangat kompleks, sehingga memaksa klien untuk memecah logika mereka menjadi payload yang lebih kecil.

Elemen <MaxCount> menggunakan sintaksis berikut:

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <MaxCount>MAX_NUMBER_OF_QUERIES</MaxCount>
</GraphQL>

<MaxDepth>

Kedalaman maksimum kueri, jika direpresentasikan sebagai hierarki. MaxDepth memungkinkan Anda memblokir kueri mendalam pada payload, sehingga Apigee tidak perlu membuat variabel aliran yang sangat besar untuk menyimpan nilai. Namun, payload akan dikirim sebagaimana adanya, terlepas dari nilai MaxDepth. Nilai defaultnya adalah 10.

Elemen <MaxDepth> menggunakan sintaksis berikut:

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <MaxDepth>MAX_DEPTH</MaxDepth>
</GraphQL>

<MaxPayloadSizeInBytes>

Ukuran maksimum payload dalam kilobyte. Anda dapat menggunakannya untuk membatasi ukuran payload, guna menghindari masalah performa.

Catatan: Jika MaxPayloadSizeInByte tidak disediakan dalam kebijakan, tidak ada batasan ukuran yang akan diterapkan.

Elemen <MaxPayloadSizeInBytes> menggunakan sintaksis berikut:

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <MaxPayloadSizeInBytes>MAX_PAYLOAD_SIZE_IN_BYTES</MaxPayloadSizeInBytes>
</GraphQL>

<OperationType>

Menunjukkan jenis permintaan yang bisa diurai:

• query: Kueri GraphQL.
• mutation: Mutasi A GraphQL
• query_mutation: Kueri A GraphQL atau mutasi.

Jika cakupannya adalah query, dan permintaan mutasi diteruskan, permintaan akan gagal dan menampilkan error 4xx.

Elemen <OperationType> menggunakan sintaksis berikut:

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <OperationType>[query|mutation|query_mutation]</OperationType>
</GraphQL>

<ResourceURL>

Jalur ke file skema GraphQL yang digunakan kebijakan GraphQL untuk memverifikasi permintaan. Lihat Contoh untuk mengetahui contoh upload skema GraphQL ke Apigee.

Jika nama file skema yang Anda upload adalah my-schema.graphql, maka elemen <ResourceURL> akan

<ResourceURL>graphql://my-schema.graphql</ResourceURL>

Elemen ResourceURL menggunakan sintaksis berikut:

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <ResourceURL>PATH/TO/SCHEMA.graphql</ResourceURL>
</GraphQL>

<Source>

Sumber tempat kebijakan ini dijalankan.

Elemen <Source> menggunakan sintaksis berikut:

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Source>request</Source>
</GraphQL>

Parser GraphQL

Parser graphQL mendukung semua fitur kueri graphQL dan menampilkannya sebagai grafik dalam notasi titik-titik alur pesan. Kueri dapat terdiri dari definisi operasi dan, secara opsional, fragmen yang diidentifikasi sebagai definisi fragmen. Lihat spesifikasi GraphQL.

Anatomi permintaan graphQL

Diagram di bawah menunjukkan anatomi permintaan graphQL.

Representasi dalam aliran pesan definisi operasi

Implementasi parser mencakup semua aspek sintaksis graphQL, termasuk dukungan untuk kueri dan mutasi. Lihat Variabel alur pesan.

Variabel alur pesan mengikuti konvensi ini:

graphql.(root-index).(root definition)[(sub-indices).(child-definitions)…]

dengan:

• graphql: Awalan statis yang menunjukkan bahwa ini adalah variabel alur pesan terkait graphQL
• root-Index: indeks berbasis yang menunjukkan indeks definisi kueri tingkat root (default hingga 4 per permintaan)
• root-definition: Isi pesan permintaan graphQL tingkat root, argumen, nilainya
• sub-indices: Indeks turunan
• child-definitions: Definisi tingkat daun yang berhubungan dengan kolom tertentu dan nilainya

Representasi dalam variabel alur pesan dari definisi operasi

Representasi dalam aliran pesan definisi fragmen

Contoh representasi variabel alur pesan

Contoh berikut menunjukkan representasi variabel alur pesan untuk contoh payload permintaan.

{
 employee(id: 123) {
   id
   firstName
   lastName
 }
}

query Characters($episode: Episode, $withFriends: Boolean!) {
   friends @include(if: $withFriends) {
     friendsName
    }
}

query getUsers {
  admins: users(role: ADMIN) {
    lastName
  }
  accountants: users(role: ACCOUNTANT) {
    firstName
  }
}

Topik terkait

Menggunakan GraphQL