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

Catatan: Untuk application/json payload formulir

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

Apigee saat ini mengabaikan kolom operationName dan variables opsional.

Untuk informasi selengkapnya, lihat referensi berikut:

• Pengantar GraphQL
• Kueri dan Mutasi
• Referensi variabel alur

Kebijakan ini adalah Kebijakan standar dan dapat di-deploy ke jenis lingkungan apa pun. Untuk mengetahui informasi tentang jenis kebijakan dan ketersediaan dengan setiap jenis lingkungan, lihat Jenis kebijakan.

Lihat Menggunakan GraphQL untuk mengetahui contoh yang menggunakan kebijakan ini.

Perhatian: Memverifikasi payload terhadap skema umumnya merupakan operasi yang mahal, dan sebaiknya pertimbangkan hal ini dengan cermat saat memutuskan apakah akan melakukan validasi skema. 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.

Elemen <GraphQL>

Menentukan kebijakan <GraphQL>.

Nilai default	Lihat tab Kebijakan Default, di bawah
Wajib?	Wajib
Jenis	JENIS
Elemen Induk	t/a
Elemen Turunan	<Action> <MaxDepth> <MaxCount> <MaxPayloadSizeInBytes> <OperationType> <Source> <ResourceURL>

Sintaks

Elemen <GraphQL> menggunakan sintaksis berikut:

<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&lt/MaxPayloadSizeInBytes>
  <Action>parse</Action>
  <ResourceURL>PATH/TO/SCHEMA.xsd</ResourceURL>
</GraphQL>

Kebijakan Default

Contoh berikut menunjukkan setelan default saat Anda menambahkan kebijakan <GraphQL> ke alur di UI Apigee:

<?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 umum untuk semua kebijakan:

Atribut	Default	Wajib?	Deskripsi
name	T/A	Wajib	Nama internal kebijakan. Nilai atribut name dapat berisi huruf, angka, spasi, tanda hubung, garis bawah, dan titik. Nilai ini tidak boleh melebihi 255 karakter. Secara opsional, gunakan elemen <DisplayName> untuk memberi label pada kebijakan di editor proxy UI pengelolaan dengan nama bahasa alami yang berbeda.
continueOnError	false	Opsional	Tetapkan ke false untuk menampilkan error saat kebijakan gagal. Perilaku ini wajar terjadi untuk sebagian besar kebijakan. Tetapkan ke true agar eksekusi alur berlanjut meskipun setelah kebijakan gagal. Lihat juga: Aturan error HANYA dipicu dalam status error (tentang continueOnError) Menangani error dalam alur saat ini
enabled	benar	Opsional	Tetapkan ke true untuk menerapkan kebijakan. Tetapkan ke false untuk menonaktifkan kebijakan. Kebijakan tidak akan diterapkan meskipun tetap terlampir ke alur.
async	false	Tidak digunakan lagi	Atribut ini tidak digunakan lagi.

Tabel berikut memberikan deskripsi umum elemen turunan <GraphQL>:

Elemen Turunan	Wajib?	Deskripsi
Operasi umum
<Action>	Opsional	Menentukan tindakan yang akan dilakukan untuk permintaan: parse, verify, atau parse_verify (keduanya).
<MaxCount>	Opsional	Jumlah maksimum kueri atau fragmen yang dapat dihasilkan permintaan GraphQL. Nilai defaultnya adalah 10.
<MaxDepth>	Opsional	Kedalaman maksimum hierarki untuk kueri. Nilai defaultnya adalah 4.
<MaxPayloadSizeInBytes>	Opsional	Ukuran maksimum payload dalam kilobyte.
<OperationType>	Wajib	Menentukan jenis permintaan yang dapat diuraikan: query, mutation, atau query_mutation (salah satu).
<ResourceURL>	Opsional	DESKRIPSI. Lokasi file skema GraphQL.
<Source>	Wajib	request

Setiap elemen turunan ini dijelaskan di bagian berikut.

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

Nilai default	parse
Wajib?	Opsional
Jenis	String
Elemen Induk	<GraphQL>
Elemen Turunan	tidak ada

Elemen <Action> menggunakan sintaksis berikut:

Sintaks

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

<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 membagi logika mereka menjadi payload yang lebih kecil.

Nilai default	10
Wajib?	Opsional
Jenis	String
Elemen Induk	<GraphQL>
Elemen Turunan	tidak ada

Elemen <MaxCount> menggunakan sintaksis berikut:

Sintaks

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

<MaxDepth>

Kedalaman maksimum kueri, saat ditampilkan 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. Nilai defaultnya adalah 10.

Catatan: MaxDepth berfungsi saat elemen Action ditetapkan ke parse atau parse-verify. Sebaiknya gunakan MaxDepth dengan tindakan ini untuk memeriksa kedalaman, bukan menggunakan tindakan verify yang lebih mahal.

Nilai default	10
Wajib?	Opsional
Jenis	Bilangan bulat
Elemen Induk	<GraphQL>
Elemen Turunan	tidak ada

Elemen <MaxDepth> menggunakan sintaksis berikut:

Sintaks

<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, untuk menghindari masalah performa.

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

Nilai default	request
Wajib?	Opsional
Jenis	String
Elemen Induk	<GraphQL>
Elemen Turunan	tidak ada

Elemen <MaxPayloadSizeInBytes> menggunakan sintaksis berikut:

Sintaks

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

<OperationType>

Menunjukkan jenis permintaan yang dapat diuraikan:

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

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

Nilai default	query
Wajib?	Opsional
Jenis	String
Elemen Induk	<GraphQL>
Elemen Turunan	tidak ada

Elemen <OperationType> menggunakan sintaksis berikut:

Sintaks

<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 contoh mengupload skema GraphQL ke Apigee.

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

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

Nilai default	t/a
Wajib?	Opsional
Jenis	String
Elemen Induk	<GraphQL>
Elemen Turunan	tidak ada

Elemen ResourceURL menggunakan sintaksis berikut:

Sintaks

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

<Source>

Sumber tempat kebijakan ini dijalankan.

Catatan: Sumbernya harus berupa string kueri graphql mentah, bukan kueri graphql yang digabungkan dalam JSON.

Nilai default	request
Wajib?	Opsional
Jenis	String
Elemen Induk	<GraphQL>
Elemen Turunan	tidak ada

Elemen <Source> menggunakan sintaksis berikut:

Sintaks

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

Parser GraphQL

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

Anatomi permintaan graphQL

Diagram di bawah menunjukkan anatomi permintaan graphQL.

Representasi dalam alur 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 berkorelasi dengan kolom tertentu dan nilainya

Representasi dalam variabel alur pesan definisi operasi

Kolom dalam pesan	Jenis	Deskripsi
nama	String	Nama operasi graphQL. Perhatikan bahwa nama ini tidak terkait dengan nama dalam alur pesan.
definisi	String - Operasi	Menunjukkan bahwa ini berisi isi pesan utama permintaan kueri
operationType	kueri atau mutasi	Jenis operasi yang sedang dilakukan.
variableDefinition	Bilangan bulat	Fungsi ini berfungsi seperti definisi argumen untuk fungsi dalam bahasa yang diketik. File ini mencantumkan semua variabel, diawali dengan $, diikuti dengan jenisnya.
perintah	Bilangan bulat	@include dan @skip adalah dua perintah yang saat ini ditawarkan, yang dapat memfilter berdasarkan nilai yang diteruskan secara dinamis.
selectionSet	Bilangan bulat	Pengelompokan logis satu tingkat dari semua atribut yang terkait dengan objek.

Representasi dalam alur pesan dari definisi fragmen

Nama Variabel Alur Pesan	Jenis	Deskripsi
nama	String	Nama fragmen.
definisi	Fragmen string	Menunjukkan bahwa isi permintaan adalah fragmen untuk permintaan utama.
typeCondition	String	Kondisi saat fragmen dipanggil.
variableDefinition	Bilangan bulat	Definisi variabel yang diteruskan sebagai argumen ke fragmen.

Contoh representasi variabel alur pesan

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

Contoh kueri 1

Contoh ini menunjukkan kueri yang dibuat dengan argumen yang diteruskan sebagai input, yang membuat kueri untuk tiga atribut karyawan.

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

Tabel menunjukkan representasi variabel alur pesan yang sesuai.

Variabel alur pesan	Nilai
graphql.operation.operationType	QUERY
graphql.fragment.count	1
graphql.operation.selectionSet.count	1
graphql.operation.variableDefinitions.count	0
graphql.operation.selectionSet.1.name	employee
graphql.operation.selectionSet.1.argument.count	1
graphql.operation.selectionSet.1.argument.1.name	id
graphql.operation.selectionSet.1.argument.1.value	IntValue{value=123}
graphql.operation.selectionSet.1.directive.count	0
graphql.operation.selectionSet.1.selectionSet.count	3
graphql.operation.selectionSet.1.selectionSet.1.name	id
graphql.operation.selectionSet.1.selectionSet.2.name	firstName
graphql.operation.selectionSet.1.selectionSet.3.name	lastName

Contoh kueri 2

Contoh ini menunjukkan kueri yang dibuat dengan argumen yang diteruskan sebagai input, yang mengkueri nama teman.

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

Tabel di bawah menunjukkan representasi variabel alur pesan yang sesuai.

Variabel alur pesan	Nilai
graphql.operation.operationType	QUERY
graphql.operation.selectionSet.count	1
graphql.operation.name	Characters
graphql.fragment.count	0
graphql.operation.selectionSet.1.name	friends
graphql.operation.variableDefinitions.count	2
graphql.operation.variableDefinitions.1.name	episode
graphql.operation.variableDefinitions.1.type	TypeName{name='Episode'}
graphql.operation.variableDefinitions.2.name	withFriends
graphql.operation.variableDefinitions.2.type	NonNullType{type=TypeName{name='Boolean'}}
graphql.operation.selectionSet.1.argument.count	0
graphql.operation.selectionSet.1.selectionSet.count	1
graphql.operation.selectionSet.1.selectionSet.1.name	friendsName
graphql.operation.selectionSet.1.directive.count	1
graphql.operation.selectionSet.1.directive.1.argument.1.name	if
graphql.operation.selectionSet.1.directive.1.argument.1.value	VariableReference{name='withFriends'}

Contoh kueri 3

Contoh ini memiliki definisi variabel dengan alias.

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

Tabel di bawah menunjukkan representasi variabel alur pesan yang sesuai.

Variabel alur pesan	Nilai
graphql.operation.operationType	QUERY
graphql.operation.selectionSet.count	2
graphql.operation.selectionSet.1.name	users
graphql.operation.selectionSet.1.alias	admins
graphql.operation.variableDefinitions.count	0
graphql.operation.selectionSet.1.argument.count	1
graphql.operation.selectionSet.1.argument.1.name	role
graphql.operation.selectionSet.1.argument.1.value	EnumValue{name='ADMIN'}
graphql.operation.selectionSet.1.argument.2.name	null
graphql.operation.selectionSet.1.argument.2.value	null
graphql.operation.selectionSet.1.selectionSet.count	1
graphql.operation.selectionSet.1.selectionSet.count	1
graphql.operation.selectionSet.1.selectionSet.1.name	lastName
graphql.operation.selectionSet.1.selectionSet.1.alias	null
graphql.operation.selectionSet.1.selectionSet.2.name	null
graphql.operation.selectionSet.1.selectionSet.2.alias	null
graphql.operation.selectionSet.1.directive.count	0
graphql.operation.selectionSet.1.directive.1.argument.1.name	null
graphql.operation.selectionSet.1.directive.1.argument.1.value	null
graphql.operation.selectionSet.2.name	users
graphql.operation.selectionSet.2.alias	accountants
graphql.operation.selectionSet.2.argument.count	1
graphql.operation.selectionSet.2.argument.1.name	role
graphql.operation.selectionSet.2.argument.1.value	EnumValue{name='ACCOUNTANT'}
graphql.operation.selectionSet.2.selectionSet.count	1
graphql.operation.selectionSet.2.selectionSet.1.name	firstName
graphql.operation.selectionSet.2.directive.count	0
graphql.operation.selectionSet.2.selectionSet.1.alias	null
graphql.operation.selectionSet.2.selectionSet.2.name	null
graphql.operation.selectionSet.2.selectionSet.2.alias	null
graphql.operation.selectionSet.2.directive.count	0

Topik terkait

Menggunakan GraphQL