Cara Mengatur Parameter Global di Apidog (Kirim Header Otentikasi Otomatis di Setiap Permintaan)

Anda memiliki empat puluh titik akhir (endpoint) dalam sebuah proyek, dan setiap titik akhir membutuhkan header Authorization: Bearer ... yang sama dan header X-Api-Version pada setiap panggilan. Menambahkan dua baris itu secara manual ke setiap permintaan lambat, dan yang lebih buruk, itu bisa berbeda. Satu titik akhir mendapatkan token, yang lain terlupakan, dan Anda menghabiskan satu sore mengejar kesalahan 401 yang hanya muncul pada tiga rute dari empat puluh.

Ada cara yang lebih baik. Apidog memungkinkan Anda mendefinisikan parameter satu kali dan menerapkannya ke setiap permintaan secara otomatis. Atur header di tingkat proyek, referensikan token Anda sebagai variabel, dan setiap titik akhir akan mewarisinya tanpa Anda perlu menyentuh satu pun permintaan. Panduan ini menjelaskan tiga cara yang didokumentasikan untuk ini: parameter global, variabel lingkungan, dan skrip lingkup folder sebagai cadangan. Anda akan selesai dengan pengaturan kerja yang melampirkan header otentikasi dan header versi ke semuanya, ditambah cara untuk membuktikan bahwa header tersebut benar-benar terkirim. Jika Anda ingin latar belakang yang lebih mendalam tentang variabel terlebih dahulu, panduan kami tentang menguasai variabel di Apidog sangat cocok dengan ini.

tombol

Ide permintaan yang membawa header standar pada setiap panggilan tidak hanya ada di Apidog. Ini adalah pola yang sama yang dijelaskan oleh referensi header HTTP MDN: sekumpulan kecil pasangan kunci/nilai yang menyertai setiap permintaan. Tugas Apidog adalah memungkinkan Anda mengatur set tersebut satu kali.

Apa Arti Sebenarnya “Parameter Global”

Parameter global di Apidog adalah parameter permintaan yang berlaku di seluruh proyek daripada hanya untuk satu titik akhir. Anda mendefinisikannya satu kali, dan Apidog melampirkannya ke permintaan yang cocok secara otomatis.

Parameter global mencakup empat lokasi, dan ini adalah kunci dari keseluruhan fitur:

Headers (Header Permintaan) untuk hal-hal seperti Authorization atau X-Api-Version.
Cookies (Informasi Cookie) untuk cookie sesi.
Query (Parameter Kueri URL) untuk nilai-nilai seperti ?api_key= yang ditambahkan ke setiap URL.
Body (Parameter Body Permintaan) untuk bidang yang harus dibawa setiap body permintaan.

Untuk kasus penggunaan header otentikasi, Anda menginginkan Headers. Tiga lainnya bekerja dengan cara yang sama jika nilai standar Anda berada dalam cookie, string kueri, atau bidang body.

Satu aturan penting sebelum Anda memulai: parameter global memiliki prioritas lebih rendah daripada parameter yang ditentukan di tingkat titik akhir. Jika permintaan spesifik sudah mengatur header Authorization-nya sendiri, nilai tingkat titik akhir itu yang menang dan yang global akan dikesampingkan. Anggap parameter global sebagai default yang mengisi ketika sebuah titik akhir belum berbicara untuk dirinya sendiri, bukan sebagai penimpaan keras yang menimpa segalanya. Prioritas itulah yang membuat parameter global aman untuk diaktifkan di seluruh proyek besar.

Berikut adalah panduan inti. Tujuannya: melampirkan Authorization dan X-Api-Version ke setiap titik akhir dalam proyek tanpa mengedit satu pun dari mereka.

Langkah 1: Buka Manajemen Lingkungan

Parameter global berada di Manajemen Lingkungan, yang Anda buka dari kanan atas halaman. Ini adalah titik masuk untuk parameter yang berlaku di seluruh proyek, dan dokumentasi Apidog menggambarkannya sebagai rumah bagi nilai-nilai yang menyertai setiap permintaan. Bukalah, dan Anda akan melihat bagian tempat Anda menambahkan parameter berdasarkan lokasi.

Langkah 2: Pilih Lokasi Headers

Pilih Headers (lokasi Header Permintaan) karena Anda menambahkan header otentikasi. Jika nilai standar Anda adalah cookie, parameter kueri, atau bidang body, Anda akan memilih Cookies, Query, atau Body. Mekanismenya identik di keempatnya.

Langkah 3: Isi Detail Parameter

Setiap parameter global memiliki seperangkat properti yang tetap. Isikan untuk header pertama Anda:

Name (Nama): Authorization
Type (Tipe): tipe parameter (string untuk nilai header).
Default Value (Nilai Default): Bearer {{token}} (lebih lanjut tentang bagian {{token}} di bawah).
Description (Deskripsi): catatan singkat seperti “Bearer token untuk semua titik akhir yang diautentikasi.”

Bidang Default dan penanda wajib (tanda bintang *) juga muncul pada parameter yang wajib. Tambahkan baris kedua dengan cara yang sama untuk header versi:

Name (Nama): X-Api-Version
Type (Tipe): string
Default Value (Nilai Default): 2024-08-01
Description (Deskripsi): “Versi API yang dipatok untuk setiap permintaan.”

Langkah 4: Aktifkan Parameter

Setiap parameter memiliki sakelar aktifkan/nonaktifkan di sisi kanan. Nyalakan untuk mengaktifkan parameter. Sakelar ini berguna nantinya: jika Anda perlu membungkam header global untuk sesi debugging, Anda menonaktifkannya di sini daripada menghapusnya dan mengetik ulang semuanya.

Langkah 5: Simpan

Simpan konfigurasi. Kedua header sekarang bersifat global. Setiap permintaan dalam proyek akan membawa Authorization dan X-Api-Version kecuali jika titik akhir spesifik menimpanya.

Langkah 6: Buktikan Bahwa Itu Benar-Benar Terkirim

Jangan hanya percaya bahwa itu berhasil; periksa. Kirim permintaan apa pun dalam proyek, lalu buka tab Actual Request (Permintaan Aktual) di konsol respons. Tab itu menunjukkan permintaan persis seperti saat dikirim, dengan variabel yang sudah diganti dengan nilai aslinya. Anda seharusnya melihat kedua header tercantum di sana:

GET /v1/orders/8842 HTTP/1.1
Host: api.yourservice.com
Authorization: Bearer sk_live_7f3a9c2e1b8d4056
X-Api-Version: 2024-08-01

Jika header muncul di Permintaan Aktual, berarti itu terkirim. Ini adalah bagian paling berguna dalam seluruh pengaturan, karena mengubah “Saya kira sudah diterapkan” menjadi “Saya bisa melihat itu diterapkan.”

Jaga Rahasia Tetap Tersembunyi dari Header: Gunakan Variabel

Perhatikan bahwa Nilai Default di atas adalah Bearer {{token}}, bukan Bearer sk_live_7f3a9c2e1b8d4056. Sintaksis kurung kurawal ganda itu merujuk pada variabel alih-alih mengkodekan token mentah ke dalam parameter. Skema Bearer itu sendiri didefinisikan dalam RFC 6750, dan referensi header Otorisasi MDN menjelaskan cara server membacanya. Dokumen Apidog secara eksplisit menyatakan aspek keamanan: untuk data sensitif seperti token otentikasi dan kunci API, gunakan variabel lingkungan daripada menyimpan nilai mentah sebagai Nilai Default teks biasa. Variabel adalah placeholder dinamis untuk nilai yang Anda gunakan di banyak permintaan dan skrip, dan itu menjaga rahasia tetap tersembunyi dari definisi parameter.

Berikut cara mengatur variabel token:

Klik ikon lingkungan (ikon ≡) di kanan atas. Perhatikan bahwa ini adalah titik masuk yang berbeda dari Manajemen Lingkungan: ikon ≡ adalah tempat variabel berada.
Temukan bagian Global Variables (Variabel Global).
Buat variabel, misalnya token dengan nilai rahasia bearer Anda.
Klik Save (Simpan).

Sekarang nilai header global Anda Bearer {{token}} akan berubah menjadi Bearer <your-real-secret> saat dikirim, dan tab Permintaan Aktual mengonfirmasi substitusi. Mengarahkan kursor ke nama variabel di mana pun menunjukkan nilai dan cakupan saat ini, yang merupakan cara cepat untuk memeriksa apakah Anda merujuk yang benar.

Pasangan ini adalah pola yang direkomendasikan: parameter global memiliki slot header, dan variabel memiliki rahasia. Panduan mendalam kami tentang manajemen lingkungan dan rahasia klien API membahas lebih jauh tentang cara menjaga token agar tidak bocor ke apa pun yang mungkin Anda bagikan atau komit.

Mengganti Nilai per Lingkungan

Variabel menjadi lebih berguna ketika Anda memiliki lebih dari satu. Proyek nyata menghubungi server yang berbeda untuk Pengembangan, Pengujian, dan Produksi, dan masing-masing biasanya menginginkan token yang berbeda. Kelompokkan setiap set di bawah lingkungannya sendiri, lalu beralih di antara mereka dengan dropdown Lingkungan di samping ikon ≡ (lingkungan sampel mungkin bernama Local Mock). Mengganti lingkungan mengarahkan permintaan Anda ke serangkaian server yang berbeda dan menukar nilai variabel lingkungan tersebut. Header global Bearer {{token}} Anda tetap sama; hanya rahasia yang terpecahkan yang berubah sesuai lingkungan. Jika Anda membangun alur otentikasi di atas ini, konsep dalam panduan skema keamanan kami menjelaskan bagaimana definisi bearer, kunci API, dan OAuth dipetakan ke permintaan nyata.

Ketika Anda Hanya Ingin Header pada Satu Folder

Parameter global memengaruhi seluruh proyek. Terkadang itu terlalu luas. Katakanlah hanya titik akhir /admin Anda yang membutuhkan header X-Admin-Scope, dan sisa proyek tidak boleh membawanya.

Berikut adalah batasan jujur: Apidog tidak memiliki bidang "tambah header" bawaan di pengaturan folder. Tidak ada UI header tingkat folder untuk diisi. Yang didokumentasikan sebagai gantinya adalah solusi menggunakan skrip pra-permintaan di tingkat folder, sehingga setiap permintaan di dalam folder tersebut mewarisi header. Skrip ini menggunakan skrip pm.* yang kompatibel dengan Postman:

pm.request.headers.add({ key: 'X-Admin-Scope', value: 'full' });

Tambahkan itu sebagai skrip pra-permintaan di folder, dan setiap permintaan di folder tersebut akan mendapatkan header, sementara permintaan di luar folder tidak. Ini adalah skrip, bukan sakelar pengaturan, jadi anggaplah ini sebagai solusi yang disengaja untuk kebutuhan lingkup folder daripada jalur utama. Untuk model skrip yang lebih luas di mana ini berada, lihat panduan kami tentang skrip pra-permintaan dan pasca-permintaan di Apidog.

Tuas Mana, dan Kapan

Anda sekarang memiliki tiga cara untuk melampirkan header tanpa mengedit titik akhir. Pilih berdasarkan cakupan:

Parameter global (Headers) melalui Manajemen Lingkungan: header berlaku untuk seluruh proyek. Ini adalah default Anda untuk header otentikasi atau header versi bersama.
Variabel lingkungan ({{token}}): pasangkan dengan parameter global sehingga slot header bersifat global tetapi rahasia disimpan dengan aman dan bertukar per lingkungan.
Skrip pra-permintaan tingkat folder (pm.request.headers.add): header hanya berlaku untuk satu folder. Gunakan ini ketika cakupan proyek terlalu luas.

Beberapa hal yang perlu diperhatikan. Periksa nama parameter yang duplikat agar dua header global tidak bertabrakan, dan pastikan Tipe setiap parameter sesuai dengan cara penggunaannya. Dan ingat aturan prioritas: titik akhir yang menetapkan Authorization-nya sendiri menimpa yang global, yang merupakan fitur ketika satu rute membutuhkan token yang berbeda, tetapi bisa mengejutkan jika Anda lupa bahwa rute tersebut memiliki nilai sendiri. Tidak ada dari ketiga fitur ini yang memiliki batasan paket dalam dokumen, jadi Anda tidak memerlukan tingkatan tertentu untuk menggunakannya.

Otomatiskan Alur Kerja dengan Apidog CLI

Parameter global dan lingkungan bukan hanya kenyamanan GUI; mereka juga terbawa ke dalam jalankan otomatis. Ketika Anda membangun skenario pengujian yang disimpan di Apidog dan menjalankannya dari baris perintah, jalankan akan mewarisi lingkungan yang Anda lewati berdasarkan ID, sehingga header Bearer {{token}} dan nilai X-Api-Version yang sama yang berfungsi di GUI akan diselesaikan dengan cara yang sama di CI.

Instal CLI (Node.js v16+) dan autentikasi:

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>

Kemudian jalankan skenario yang disimpan terhadap lingkungan tertentu:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli

Flag -e memilih lingkungan, sehingga skenario mengambil variabel lingkungan tersebut, termasuk token Anda. Flag -t adalah ID skenario pengujian dan -r adalah pelapor (cli, html, atau junit). Itulah hubungannya: definisikan header dan variabel satu kali, dan setiap skenario yang dijalankan melalui CLI akan membawanya. Untuk pengaturan dan detail token, lihat panduan instalasi Apidog CLI, dan untuk menghubungkan jalankan ke otomatisasi, alur kerja Apidog CLI di GitHub Actions kami menunjukkan seluruh pipeline.

FAQ

Apakah parameter global menimpa header yang saya tetapkan pada titik akhir spesifik?

Tidak. Parameter global memiliki prioritas lebih rendah daripada parameter tingkat titik akhir. Jika sebuah permintaan mendefinisikan header Authorization-nya sendiri, nilai tersebut yang menang dan yang global diabaikan untuk permintaan itu. Global bertindak sebagai default proyek, mengisi di mana pun titik akhir belum menetapkan nilainya sendiri.

Di mana saya harus menyimpan token yang sebenarnya agar tidak terlihat sebagai teks biasa?

Gunakan variabel lingkungan atau global, bukan Nilai Default mentah. Atur header global ke Bearer {{token}} dan simpan rahasia sebenarnya dalam variabel yang dibuat melalui ikon lingkungan ≡. Dokumen merekomendasikan variabel atau metode aman untuk data sensitif secara khusus agar token tidak disimpan secara inline. Panduan kami tentang mengekstrak variabel dengan JSONPath membahas cara menangkap token dari respons login dan menggunakannya kembali dengan cara yang sama.

Bagaimana cara mengkonfirmasi bahwa header global benar-benar terkirim?

Kirim permintaan apa pun, lalu buka tab Actual Request (Permintaan Aktual) di konsol respons. Ini menunjukkan permintaan sebagaimana benar-benar dikirim, dengan {{token}} dan variabel lainnya sudah diganti dengan nilainya. Jika header Anda muncul di sana, itu berarti sudah terkirim.

Bisakah saya menambahkan header default hanya ke satu folder alih-alih seluruh proyek?

Ya, tetapi bukan melalui bidang pengaturan, karena Apidog tidak memiliki UI header folder bawaan. Tambahkan skrip pra-permintaan di folder menggunakan pm.request.headers.add({ key, value }), dan setiap permintaan di folder tersebut akan mewarisi header sementara sisa proyek tidak.

Apakah saya memerlukan paket berbayar untuk menggunakan parameter global atau variabel lingkungan?

Dokumentasi untuk fitur-fitur ini tidak mencantumkan batasan tingkatan apa pun. Parameter global, variabel lingkungan, dan skrip pra-permintaan tingkat folder semuanya didokumentasikan tanpa batasan gratis versus berbayar.

Ringkasan

Mengatur header pada setiap permintaan adalah pekerjaan satu kali di Apidog: definisikan header sebagai parameter global di bawah Manajemen Lingkungan, referensikan rahasia sebagai variabel {{token}} agar tetap tersembunyi dari teks biasa, dan konfirmasikan bahwa itu terkirim dengan tab Permintaan Aktual. Ketika Anda hanya membutuhkan header pada satu folder, solusi skrip pra-permintaan mencakupnya. Untuk mengikuti di proyek Anda sendiri, Unduh Apidog dan siapkan header global pertama Anda. Ini gratis, tidak memerlukan kartu kredit.