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:
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>
.
Nilai default | Lihat tab Kebijakan Default di bawah |
Wajib? | Diperlukan |
Jenis | JENIS |
Elemen Induk | t/a |
Elemen Turunan | <Action> <MaxDepth> <MaxCount> <MaxPayloadSizeInBytes> <OperationType> <Source> <ResourceURL> |
Sintaksis
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</MaxPayloadSizeInBytes> <Action>parse</Action> <ResourceURL>PATH/TO/SCHEMA.xsd</ResourceURL> </GraphQL>
Kebijakan Default
Contoh berikut menunjukkan setelan default saat Anda menambahkan kebijakan <GraphQL>
ke flow 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 sama untuk semua kebijakan:
Atribut | Default | Wajib? | Deskripsi |
---|---|---|---|
name |
T/A | Wajib |
Nama internal kebijakan. Nilai atribut Atau, gunakan elemen |
continueOnError |
false | Opsional | Setel ke false untuk menampilkan error jika kebijakan gagal. Ini adalah perilaku yang wajar untuk sebagian besar kebijakan. Setel ke true agar eksekusi alur tetap berlanjut bahkan setelah kebijakan gagal. Lihat juga:
|
enabled |
true | Opsional | Setel ke true untuk menerapkan kebijakan. Setel ke false untuk menonaktifkan kebijakan. Kebijakan tidak akan diterapkan meskipun tetap melekat pada alur. |
async |
false | Tidak digunakan lagi | Atribut ini sudah tidak digunakan lagi. |
Tabel berikut memberikan deskripsi tingkat tinggi tentang elemen turunan <GraphQL>
:
Elemen Turunan | Wajib? | Deskripsi |
---|---|---|
Operasi umum | ||
<Action> |
Opsional | Menentukan tindakan yang harus diambil untuk permintaan: parse , verify , atau
parse_verify (keduanya).
|
<MaxCount> |
Opsional | Jumlah maksimum kueri atau fragmen yang dapat dihasilkan oleh 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> |
Diperlukan | Menentukan jenis permintaan yang dapat diurai: query ,
mutation , atau query_mutation (salah satu). |
<ResourceURL> |
Opsional | DESKRIPSI. Lokasi file skema GraphQL. |
<Source> |
Diperlukan | request |
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 saatAction
ditetapkan keparse
. Hal ini dapat menghemat waktu CPU yang berharga di backend. Perhatikan bahwaverify
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:
Sintaksis
<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.
Nilai default | 10 |
Wajib? | Opsional |
Jenis | String |
Elemen Induk | <GraphQL> |
Elemen Turunan | tidak ada |
Elemen <MaxCount>
menggunakan sintaksis berikut:
Sintaksis
<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.
Nilai default | 10 |
Wajib? | Opsional |
Jenis | Bilangan bulat |
Elemen Induk | <GraphQL> |
Elemen Turunan | tidak ada |
Elemen <MaxDepth>
menggunakan sintaksis berikut:
Sintaksis
<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.
Nilai default | request |
Wajib? | Opsional |
Jenis | String |
Elemen Induk | <GraphQL> |
Elemen Turunan | tidak ada |
Elemen <MaxPayloadSizeInBytes>
menggunakan sintaksis berikut:
Sintaksis
<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 GraphQLquery_mutation
: Kueri A GraphQL atau mutasi.
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:
Sintaksis
<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>
Nilai default | t/a |
Wajib? | Opsional |
Jenis | String |
Elemen Induk | <GraphQL> |
Elemen Turunan | tidak ada |
Elemen ResourceURL
menggunakan sintaksis berikut:
Sintaksis
<GraphQL continueOnError="[false|true]" enabled="[true|false]" name="POLICY_NAME" > <ResourceURL>PATH/TO/SCHEMA.graphql</ResourceURL> </GraphQL>
<Source>
Sumber tempat kebijakan ini dijalankan.
Nilai default | request |
Wajib? | Opsional |
Jenis | String |
Elemen Induk | <GraphQL> |
Elemen Turunan | tidak ada |
Elemen <Source>
menggunakan sintaksis berikut:
Sintaksis
<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 graphQLroot-Index
: indeks berbasis yang menunjukkan indeks definisi kueri tingkat root (default hingga 4 per permintaan)root-definition
: Isi pesan permintaan graphQL tingkat root, argumen, nilainyasub-indices
: Indeks turunanchild-definitions
: Definisi tingkat daun yang berhubungan dengan kolom tertentu dan nilainya
Representasi dalam variabel alur pesan dari definisi operasi
Kolom dalam pesan | Jenis | Deskripsi |
---|---|---|
name | 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 | Fungsinya sama 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 sebuah objek. |
Representasi dalam aliran pesan definisi fragmen
Nama Variabel Alur Pesan | Jenis | Deskripsi |
---|---|---|
name | String | Nama fragmen. |
definisi | Fragmen string | Menunjukkan bahwa isi permintaan adalah fragmen dari permintaan utama. |
typeCondition | String | Kondisi saat fragmen dipanggil. |
variableDefinition | Bilangan bulat | Definisi variabel diteruskan sebagai argumen ke fragmen. |
Contoh representasi variabel alur pesan
Contoh berikut menunjukkan representasi variabel alur pesan untuk contoh payload permintaan.
Contoh kueri 1
Contoh ini menunjukkan kueri yang dibuat dengan argumen yang diteruskan sebagai input, yang membuat kueri untuk tiga atribut untuk 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 membuat kueri untuk 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 |