API Proksi

Important

Karena v3.3.1, setiap permintaan API Proksi Dev memerlukan Authorization: Bearer <token> header; permintaan tanpa pengembalian 401 Unauthorizedtoken yang valid .

Dev Proxy dilengkapi dengan API web yang memungkinkan Anda berinteraksi dengan proksi secara terprogram. API tersedia di alamat IP dan port yang ditentukan dalam pengaturan proksi.

Dev Proxy menghasilkan token unik untuk setiap instans yang sedang berjalan dan menyimpannya dalam file yang hanya dapat diakses oleh pengguna yang memulai instans. Dapatkan token menggunakan devproxy status atau devproxy api token. CI Saat variabel lingkungan diatur, gunakan devproxy api token karena Proksi Dev menghilangkan token dari status dan output startup.

Untuk menggunakan token yang diketahui alih-alih yang dihasilkan, misalnya ketika alat lain memulai Dev Proxy dan memanggil API-nya, atur DEV_PROXY_API_TOKEN variabel lingkungan sebelum Anda memulai Dev Proxy atau meneruskannya menggunakan --env opsi . Nilai harus panjangnya minimal 32 karakter, tidak menghitung padding berikutnya=, dan hanya dapat berisi huruf ASCII, digit, dan karakter -, , ., _~, +dan /, secara opsional diikuti dengan = padding. Dev Proxy memangkas spasi kosong di sekitarnya. Jika nilai tidak valid, Dev Proxy tidak dimulai dan keluar dengan kesalahan. Dev Proxy masih menyimpan token, jadi devproxy status, devproxy api token, dan devproxy stop terus bekerja.

Sertakan token di Authorization header:

Authorization: Bearer <token>

Permintaan tanpa pengembalian 401 Unauthorizedtoken yang valid . Permintaan browser juga harus berasal dari asal yang tercantum dalam apiAllowedOrigins pengaturan. Asal lain mengembalikan 403 Forbidden.

Operasional

Daftar berikut menunjukkan operasi API yang tersedia.

GET /proxy

Mengembalikan instans ProxyInfo dengan informasi tentang instans Dev Proxy yang sedang berjalan.

Contoh: Mendapatkan informasi tentang instans Dev Proxy yang sedang berjalan

Permintaan:

GET http://localhost:8897/proxy
Authorization: Bearer <token>

Respons:

200 OK

{
  "recording": false,
  "configFile": "/Users/user/dev-proxy/devproxyrc.json"
}

POST /proxy

Mengontrol instans Proksi Dev yang sedang berjalan. Untuk memulai dan menghentikan perekaman dari skrip atau alur CI, lihat Merekam dari skrip dan CI.

Contoh: mulai merekam

Permintaan:

POST http://localhost:8897/proxy
Authorization: Bearer <token>
content-type: application/json

{
  "recording": true
}

Respons:

200 OK

{
  "recording": true,
  "configFile": "/Users/user/dev-proxy/devproxyrc.json"
}

Contoh: hentikan perekaman

Permintaan:

POST http://localhost:8897/proxy
Authorization: Bearer <token>
content-type: application/json

{
  "recording": false
}

Respons:

200 OK

{
  "recording": false,
  "configFile": "/Users/user/dev-proxy/devproxyrc.json"
}

Berhenti merekam dan membuat laporan

Menghentikan perekaman tidak lebih dari berhenti menangkap permintaan. Saat Anda mengirim {"recording": false} saat Dev Proxy merekam, Dev Proxy meneruskan permintaan yang direkam ke semua plugin yang diaktifkan, dalam urutan yang tercantum dalam file konfigurasi. Ini sama dengan menekan s di konsol tempat Dev Proxy berjalan. Selama langkah ini:

  • Plugin pelaporan menganalisis permintaan yang direkam dan menghasilkan laporan.
  • Wartawan mengonversi laporan menjadi file. Setiap wartawan menulis satu file untuk setiap laporan, bernama <plugin>_<reporter>.<extension>, misalnya, ExecutionSummaryPlugin_MarkdownReporter.md. <plugin> adalah nama instans plugin yang menghasilkan laporan, dan <reporter> merupakan nama instans reporter. Jika file dengan nama tersebut sudah ada, reporter menambahkan tanda waktu, misalnya, ExecutionSummaryPlugin_MarkdownReporter_20261105114500.md.
  • Plugin generator, seperti OpenApiSpecGeneratorPlugin, tulis file yang dihasilkan.

Dev Proxy menulis file-file ini ke direktori kerjanya saat ini, yang merupakan direktori tempat Anda memulai Dev Proxy.

API merespons setelah semua plugin selesai memproses permintaan yang direkam. Tergantung pada plugin yang Anda gunakan, misalnya, plugin yang memanggil model bahasa, langkah ini dapat memakan waktu cukup lama, jadi pastikan klien HTTP Anda tidak kehabisan waktu terlalu dini. Ketika respons tiba, file laporan ditulis ke disk.

Dev Proxy juga mencatat kemajuan pemrosesan permintaan yang direkam:

Pesan log Meaning
DONE Semua plugin selesai memproses permintaan yang direkam.
No requests to process Plugin tidak menemukan permintaan yang direkam untuk dianalisis.
An error occurred in a plugin Plugin gagal. Dev Proxy berlanjut dengan plugin dan log DONE berikutnya ketika semua plugin selesai.

Jika Dev Proxy tidak merekam saat Anda mengirim {"recording": false}, Dev Proxy tidak memproses permintaan apa pun, tidak menulis file apa pun, dan tidak mencatat DONE.

Tip

Jika Anda menghentikan Dev Proxy menggunakan POST /proxy/stopproxy saat merekam, Dev Proxy juga memproses permintaan yang direkam sebelum keluar. Namun, API tersebut segera merespons, jadi Anda perlu menunggu proses Dev Proxy keluar untuk mengetahui bahwa laporan sudah siap. Untuk mengetahui dengan tepat kapan laporan siap, hentikan perekaman terlebih dahulu, tunggu respons, lalu hentikan Proksi Dev.

Untuk skrip lengkap yang memulai Dev Proxy, mengontrol perekaman melalui API, dan menunggu Proksi Dev selesai, lihat Menggunakan Dev Proxy dalam skenario CI/CD.

POST /proxy/jwtToken

Menghasilkan JSON Web Token (JWT).

Permintaan:

POST http://localhost:8897/proxy/jwtToken
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Dev Proxy",
  "audiences": [
    "https://myserver.com"
  ],
  "issuer": "dev-proxy",
  "roles": [
    "admin"
  ],
  "scopes": [
    "Post.Read",
    "Post.Write"
  ],
  "claims": {
    "claim1": "value",
    "claim2": "value"
  },
  "validFor": 60
}

Catatan

Klaim terdaftar (misalnya, iss, , sub, audexp, nbf, iat, , jti) secara otomatis ditambahkan ke token. Jika Anda menentukan salah satu klaim ini dalam permintaan, API mengabaikan nilai yang Anda berikan.

Respons:

200 OK

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6IkRldiBQcm94eSIsInN1YiI6IkRldiBQcm94eSIsImp0aSI6IjkyZjM5YzciLCJzY3AiOlsiUG9zdC5SZWFkIiwiUG9zdC5Xcml0ZSJdLCJyb2xlcyI6ImFkbWluIiwiY2xhaW0xIjoidmFsdWUiLCJjbGFpbTIiOiJ2YWx1ZSIsImF1ZCI6Imh0dHBzOi8vbXlzZXJ2ZXIuY29tIiwibmJmIjoxNzI3MTk4MjgyLCJleHAiOjE3MjcyMDE4ODIsImlhdCI6MTcyNzE5ODI4MiwiaXNzIjoiZGV2LXByb3h5In0.E_Gj9E58OrAh9uHgc-TW8DYfq8YHFrhaUTpKA4yXEIg"
}

GET /proxy/logs

Mengembalikan output log Proksi Dev. Setara dengan logs perintah. Titik akhir ini hanya tersedia ketika Dev Proxy berjalan dalam mode dilepaskan. Jika tidak, API mengembalikan 404 Not Found.

Parameter pencarian Deskripsi Default
lines Jumlah baris yang akan dikembalikan dari akhir log 50
follow Ketika true, mengalirkan baris log baru sebagai peristiwa yang dikirim server false
since Mengembalikan hanya baris yang dicatat sejak tanggal dan waktu yang ditentukan. Gunakan durasi (misalnya, 30s, , 1h5m, 1d) atau tanggal dan waktu ISO 8601 (misalnya, 2026-01-24T14:00:00 atau 2026-01-24T14:00:00Z). Jika tanda waktu tidak menyertakan offset zona waktu, Dev Proxy menggunakan zona waktu lokal. n/a

Parameter since memfilter baris log berdasarkan tanggal dan waktu lengkapnya, baik saat mengembalikan baris log maupun saat melakukan streaming. Dev Proxy memfilter setiap permintaan pada saat dimulai, sehingga permintaan yang dimulai sebelum waktu yang ditentukan tidak dikembalikan, bahkan jika selesai nanti.

Secara default, API mengembalikan baris log sebagai teks biasa. Untuk mendapatkan array entri log JSON, atur Accept header ke application/json. Untuk mengalirkan baris log sebagai peristiwa yang dikirim server, atur Accept header ke text/event-stream atau atur follow ke true.

Permintaan:

GET http://localhost:8897/proxy/logs?lines=10
Authorization: Bearer <token>

Respons:

200 OK
content-type: text/plain

[last 10 lines of the Dev Proxy log]

POST /proxy/mockrequest

Menaikkan permintaan tiruan. Setara dengan menekan w di konsol tempat Dev Proxy berjalan. API merespons setelah permintaan tiruan selesai.

Permintaan:

POST http://localhost:8897/proxy/mockrequest
Authorization: Bearer <token>

Respons:

204 No Content

GET /proxy/rootCertificate?format=crt

Mengunduh kunci publik sertifikat akar dalam format PEM (Privacy Enhanced Mail) yang digunakan Dev Proxy untuk mendekripsi permintaan HTTPS. API ini berguna ketika Anda ingin mempercayai sertifikat akar pada host Anda saat menjalankan Dev Proxy dalam kontainer Docker.

Saat ini, satu-satunya format yang didukung adalah crt. API mengembalikan kesalahan Permintaan Buruk 400 jika Anda menentukan format lain atau tidak menentukan format sama sekali.

Permintaan:

GET http://localhost:8897/proxy/rootCertificate?format=crt
Authorization: Bearer <token>

Respons:

content-type: application/x-x509-ca-cert

-----BEGIN CERTIFICATE-----
[base64 encoded certificate]
-----END CERTIFICATE-----

POST /proxy/stopproxy

Dengan anggun mematikan Dev Proxy. Jika Dev Proxy merekam, Dev Proxy berhenti merekam dan menghasilkan laporan sebelum keluar. API segera merespons, sebelum Dev Proxy selesai dimatikan.

Permintaan:

POST http://localhost:8897/proxy/stopproxy
Authorization: Bearer <token>

Respons:

202 Accepted

Dev Proxy kembali 202 Accepted segera setelah mulai dimatikan. Respons tidak berarti bahwa Dev Proxy telah keluar. Selama matikan, Dev Proxy:

  1. Berhenti menerima permintaan proksi baru. Jika Dev Proxy terdaftar sebagai proksi sistem, proksi tersebut memulihkan pengaturan proksi sistem sebelumnya. Proksi Dev menunggu hingga lima detik agar koneksi terbuka ditutup, lalu menutup koneksi yang tersisa.
  2. Berhenti merekam, jika rekaman aktif, dan menjalankan plugin pelaporan pada permintaan yang direkam, sama seperti ketika Anda berhenti merekam diri Anda sendiri. Setelah plugin selesai, Dev Proxy menulis laporan dan log DONE.
  3. Menghapus informasi instansnya, jadi devproxy status dan devproxy stop tidak lagi mencantumkannya.
  4. Keluar dengan kode 0keluar .

Dev Proxy tidak menghapus sertifikat akarnya dari penyimpanan sertifikat tepercaya saat dimatikan. Untuk menghapus sertifikat, gunakan penghapusan sertifikasi.

Matikan biasanya membutuhkan waktu beberapa detik. Ini bisa memakan waktu lebih lama ketika melaporkan plugin memproses rekaman besar. Setelah penonaktifan dimulai, API tidak lagi dapat dijangkau, jadi jangan jajak pendapat API untuk memeriksa apakah Proksi Dev telah keluar. Sebagai gantinya, gunakan salah satu opsi ini:

  • Tunggu ID proses (PID) yang devproxy --detach dicetak keluar.
  • Jalankan devproxy status --pid <pid> hingga mengembalikan kode 1keluar , yang berarti bahwa instans tidak lagi berjalan. Untuk informasi selengkapnya, lihat status.
  • Jika Anda merekam, periksa log Dev Proxy untuk DONE pesan, yang log Dev Proxy setelah plugin pelaporan selesai. Misalnya, lihat Menggunakan Dev Proxy dalam skenario CI/CD.

Misalnya, untuk menunggu instans Dev Proxy yang terlepas keluar di Linux atau macOS:

# DEVPROXY_PID is the PID that devproxy --detach printed
# TOKEN is the API token from devproxy api token
curl -X POST http://localhost:8897/proxy/stopproxy -H "Authorization: Bearer $TOKEN"

while ./devproxy/devproxy status --pid $DEVPROXY_PID > /dev/null 2>&1; do
  sleep 1
done

Hindari mengakhiri proses Proksi Dev secara paksa, misalnya, dengan menggunakan kill -9. Saat Anda mengakhiri proses dengan cara ini, Dev Proxy tidak menghapus pengaturan proksi sistem perekaman atau pemulihan. Untuk menghentikan Dev Proxy dari baris perintah, gunakan stop, yang memanggil API ini dan menunggu hingga 10 detik agar Proksi Dev keluar.

Model

ProxyInfo

Informasi tentang instans Dev Proxy yang sedang berjalan.

Properti Tipe Deskripsi
recording boolean Apakah proksi sedang merekam permintaan
configFile string Jalur ke file konfigurasi yang digunakan Dev Proxy (baca-saja)

JwtOptions

Opsi untuk menghasilkan token JWT.

Properti Tipe Deskripsi
name string Nama pengguna untuk membuat token untuk
audiences string[] Audiens untuk membuat token untuk
issuer string Penerbit token
roles string[] Klaim peran untuk ditambahkan ke token
scopes string[] Klaim cakupan untuk ditambahkan ke token
claims KeyValuePair Klaim untuk ditambahkan ke token
validFor number Durasi (dalam menit) di mana token valid
signingKey string Kunci yang digunakan untuk menandatangani token. Panjangnya harus minimal 32 karakter. Jika tidak ditentukan, menggunakan kunci yang dihasilkan secara acak.

JwtInfo

Informasi tentang token JWT.

Properti Tipe Deskripsi
token string Token JWT

Baca juga

  • Terakhir diperbarui pada