Proxy-API

Important

Seit v3.3.1 erfordert jede Dev Proxy-API-Anforderung den Authorization: Bearer <token> Header; Anforderungen ohne gültige Tokenrückgabe 401 Unauthorized.

Dev Proxy enthält eine Web-API, mit der Sie programmgesteuert mit dem Proxy interagieren können. Die API ist für die in den Proxyeinstellungen angegebene IP-Adresse und der Port verfügbar.

Dev Proxy generiert ein eindeutiges Token für jede ausgeführte Instanz und speichert es in einer Datei, auf die nur der Benutzer zugreifen kann, der die Instanz gestartet hat. Abrufen des Tokens mithilfe devproxy status oder devproxy api token. Wenn die CI Umgebungsvariable festgelegt ist, verwenden Sie devproxy api token , da Dev Proxy das Token aus dem Status und der Startausgabe ausgelassen.

Wenn Sie ein bekanntes Token anstelle eines generierten Tokens verwenden möchten, z. B. wenn ein anderes Tool Dev Proxy startet und seine API aufruft, legen Sie die DEV_PROXY_API_TOKEN Umgebungsvariable fest, bevor Sie Dev Proxy starten oder mit der --env Option übergeben. Der Wert muss mindestens 32 Zeichen lang sein, ohne nachgestellten = Abstand zu zählen, und kann nur ASCII-Buchstaben, Ziffern und die Zeichen -, , _., /~+und optional gefolgt von = Abstand enthalten. Dev Proxy schneidet umgebende Leerzeichen ab. Wenn der Wert ungültig ist, wird Der Dev Proxy nicht gestartet und mit einem Fehler beendet. Dev Proxy speichert weiterhin das Token, also devproxy status, devproxy api tokenund devproxy stop funktionieren weiterhin.

Schließen Sie das Token in den Authorization Header ein:

Authorization: Bearer <token>

Anforderungen ohne gültige Tokenrückgabe 401 Unauthorized. Browseranforderungen müssen auch von einem Ursprung stammen, der in der apiAllowedOrigins Einstellung aufgeführt ist. Andere Ursprünge werden zurückgegeben 403 Forbidden.

Vorgänge

In der folgenden Liste sind verfügbare API-Vorgänge aufgeführt.

`GET /proxy`

Gibt eine Instanz mit ProxyInfo Informationen zur derzeit ausgeführten Dev Proxy-Instanz zurück.

Beispiel: Abrufen von Informationen zur derzeit ausgeführten Dev Proxy-Instanz

Anforderung:

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

Antwort:

200 OK

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

`POST /proxy`

Steuert die derzeit ausgeführte Dev Proxy-Instanz. Informationen zum Starten und Beenden der Aufzeichnung von einem Skript oder einer CI-Pipeline finden Sie unter "Aufzeichnen von Skripts und CI".

Beispiel: Starten der Aufzeichnung

Anforderung:

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

{
  "recording": true
}

Antwort:

200 OK

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

Beispiel: Beenden der Aufzeichnung

Anforderung:

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

{
  "recording": false
}

Antwort:

200 OK

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

Beenden der Aufzeichnung und Generieren von Berichten

Das Beenden der Aufzeichnung bewirkt mehr als das Beenden der Erfassung von Anforderungen. Wenn Sie während der Aufzeichnung von Dev Proxy senden {"recording": false} , übergibt Dev Proxy die aufgezeichneten Anforderungen an alle aktivierten Plug-Ins, in der Reihenfolge, in der sie in der Konfigurationsdatei aufgeführt sind. Dies entspricht dem Drücken von S in der Konsole, in der Dev Proxy ausgeführt wird. Während dieses Schritts:

Reporting Plugins analysieren die aufgezeichneten Anforderungen und erstellen Berichte.
Reporter wandeln die Berichte in Dateien um. Jeder Reporter schreibt eine Datei für jeden Bericht, <plugin>_<reporter>.<extension>genannt , zum Beispiel ExecutionSummaryPlugin_MarkdownReporter.md. <plugin> ist der Name der Plugin-Instanz, die den Bericht erstellt hat, und <reporter> ist der Name der Reporterinstanz. Wenn bereits eine Datei mit diesem Namen vorhanden ist, hängt der Reporter beispielsweise ExecutionSummaryPlugin_MarkdownReporter_20261105114500.mdeinen Zeitstempel an.
Generator-Plug-Ins wie die OpenApiSpecGeneratorPlugin, schreiben die von ihnen generierten Dateien.

Dev Proxy schreibt diese Dateien in das aktuelle Arbeitsverzeichnis, also das Verzeichnis, aus dem Sie Dev Proxy gestartet haben.

Die API antwortet, nachdem alle Plug-Ins die Verarbeitung der aufgezeichneten Anforderungen abgeschlossen haben. Abhängig von den Plug-Ins, die Sie verwenden, z. B. Plug-Ins, die ein Sprachmodell aufrufen, kann dieser Schritt eine Weile dauern. Stellen Sie daher sicher, dass Ihr HTTP-Client nicht zu früh auszeit. Wenn die Antwort eingeht, werden die Berichtsdateien auf den Datenträger geschrieben.

Dev Proxy protokolliert außerdem den Fortschritt der Verarbeitung der aufgezeichneten Anforderungen:

Protokollmeldung	Dies bedeutet
`DONE`	Alle Plug-Ins haben die Verarbeitung der aufgezeichneten Anforderungen abgeschlossen.
`No requests to process`	Ein Plug-In hat keine aufgezeichneten Anforderungen zur Analyse gefunden.
`An error occurred in a plugin`	Fehler bei einem Plug-In. Dev Proxy wird mit dem nächsten Plug-In fortgesetzt und protokolliert `DONE` , wenn alle Plug-Ins abgeschlossen sind.

Wenn Dev Proxy beim Senden {"recording": false}nicht aufgezeichnet wird, verarbeitet Dev Proxy keine Anforderungen, schreibt keine Dateien und protokolliert DONEnicht.

Tipp

Wenn Sie die Verwendung von POST /proxy/stopproxy Dev Proxy während der Aufzeichnung beenden, verarbeitet Dev Proxy auch die aufgezeichneten Anforderungen, bevor er beendet wird. Diese API reagiert jedoch sofort, sodass Sie warten müssen, bis der Dev Proxy-Prozess beendet wird, um zu wissen, dass die Berichte bereit sind. Um genau zu wissen, wann die Berichte bereit sind, beenden Sie zuerst die Aufzeichnung, warten Sie auf die Antwort, und beenden Sie dann Dev Proxy.

Ein vollständiges Skript, das Dev Proxy startet, steuert die Aufzeichnung über die API und wartet, bis der Dev-Proxy abgeschlossen ist, finden Sie unter Verwenden des Dev-Proxys in CI/CD-Szenarien.

`POST /proxy/jwtToken`

Generiert ein JSON-Webtoken (JWT).

Anforderung:

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
}

Hinweis

Registrierte Ansprüche (z. Biss. , , sub, audexp, nbf, iat, jti) werden automatisch zum Token hinzugefügt. Wenn Sie einen dieser Ansprüche in der Anforderung angeben, ignoriert die API die von Ihnen bereitgestellten Werte.

Antwort:

200 OK

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

`GET /proxy/logs`

Gibt die Ausgabe des Dev-Proxyprotokolls zurück. Entspricht dem logs Befehl. Dieser Endpunkt ist nur verfügbar, wenn Dev Proxy im getrennten Modus ausgeführt wird. Andernfalls gibt die API zurück 404 Not Found.

Query parameter (Abfrageparameter)	Beschreibung	Vorgabe
`lines`	Anzahl der Zeilen, die vom Ende des Protokolls zurückgegeben werden sollen	`50`
`follow`	Wenn `true`, streamt neue Protokollzeilen als servergesendete Ereignisse	`false`
`since`	Gibt nur Zeilen zurück, die seit dem angegebenen Datum und der angegebenen Uhrzeit protokolliert werden. Verwenden Sie eine Dauer (z`30s`. B. , , `5m`, `1d1h`) oder ein ISO 8601-Datum und eine Uhrzeit (z. B`2026-01-24T14:00:00`. oder `2026-01-24T14:00:00Z`). Wenn der Zeitstempel keinen Zeitzonenoffset enthält, verwendet Dev Proxy die lokale Zeitzone.	n/a

Der since Parameter filtert Protokollzeilen nach dem vollständigen Datum und der Uhrzeit, sowohl beim Zurückgeben von Protokollzeilen als auch beim Streamen. Dev Proxy filtert jede Anforderung nach dem Start, sodass eine Anforderung, die vor der angegebenen Zeit gestartet wurde, nicht zurückgegeben wird, auch wenn sie später beendet wurde.

Standardmäßig gibt die API die Protokollzeilen als Nur-Text zurück. Um ein JSON-Array von Protokolleinträgen abzurufen, legen Sie den Accept Header auf application/json. Wenn Sie Protokollzeilen als servergesendete Ereignisse streamen möchten, legen Sie den Accept Header auf text/event-stream oder legen sie follow auf truefest.

Anforderung:

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

Antwort:

200 OK
content-type: text/plain

[last 10 lines of the Dev Proxy log]

`POST /proxy/mockrequest`

Löst eine simulierte Anforderung aus. Entspricht dem Drücken von w in der Konsole, in der Dev Proxy ausgeführt wird. Die API antwortet, nachdem die simulierte Anforderung abgeschlossen wurde.

Anforderung:

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

Antwort:

204 No Content

`GET /proxy/rootCertificate?format=crt`

Lädt den öffentlichen Schlüssel des Stammzertifikats im PEM-Format (Privacy Enhanced Mail) herunter, den Dev Proxy zum Entschlüsseln von HTTPS-Anforderungen verwendet. Diese API ist hilfreich, wenn Sie dem Stammzertifikat auf Ihrem Host vertrauen möchten, während Sie Dev Proxy in einem Docker-Container ausführen.

Derzeit ist crtdas einzige unterstützte Format . Die API gibt einen Fehler vom Typ 400 Ungültige Anforderung zurück, wenn Sie ein anderes Format angeben oder überhaupt kein Format angeben.

Anforderung:

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

Antwort:

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

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

`POST /proxy/stopproxy`

Schalten Sie Dev-Proxy ordnungsgemäß herunter. Wenn Dev Proxy aufgezeichnet wird, beendet es die Aufzeichnung und generiert Berichte , bevor er beendet wird. Die API reagiert sofort, bevor das Herunterfahren des Dev-Proxys abgeschlossen ist.

Anforderung:

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

Antwort:

202 Accepted

Der Dev-Proxy wird zurückgegeben 202 Accepted , sobald er mit dem Herunterfahren beginnt. Die Antwort bedeutet nicht, dass Dev Proxy beendet wurde. Während des Herunterfahrens: Dev Proxy:

Beendet die Annahme neuer Proxyanforderungen. Wenn Dev Proxy als Systemproxy registriert ist, werden die vorherigen Systemproxyeinstellungen wiederhergestellt. Dev Proxy wartet bis zu fünf Sekunden, bis offene Verbindungen geschlossen werden, und schließt dann alle verbleibenden Verbindungen.
Beendet die Aufzeichnung, wenn die Aufzeichnung aktiviert ist, und führt die Berichterstellungs-Plug-Ins für die aufgezeichneten Anforderungen aus, genauso wie wenn Sie die Aufzeichnung selbst beenden. Nach Abschluss der Plug-Ins schreibt Dev Proxy die Berichte und Protokolle DONE.
Entfernt die Instanzinformationen, sodass devproxy statusdevproxy stop sie nicht mehr aufgeführt werden.
Exits with exit code 0.

Dev Proxy entfernt sein Stammzertifikat nicht aus dem vertrauenswürdigen Zertifikatspeicher beim Herunterfahren. Verwenden Sie zum Entfernen des Zertifikats das Zertifikat.

Das Herunterfahren dauert in der Regel einige Sekunden. Es kann länger dauern, wenn Plug-Ins eine große Aufzeichnung verarbeiten. Nach dem Starten des Herunterfahrens ist die API nicht mehr erreichbar. Fragen Sie daher die API nicht ab, um zu überprüfen, ob der Dev-Proxy beendet wurde. Verwenden Sie stattdessen eine der folgenden Optionen:

Warten Sie auf die Prozess-ID (PID), die devproxy --detach zum Beenden gedruckt wird.
Führen Sie den devproxy status --pid <pid> Ausführungscode 1aus, was bedeutet, dass die Instanz nicht mehr ausgeführt wird. Weitere Informationen finden Sie unter Status.
Wenn Sie aufgezeichnet wurden, überprüfen Sie das Dev Proxy-Protokoll auf die DONE Nachricht, die Dev Proxy protokolliert, nachdem die Berichts-Plug-Ins abgeschlossen wurden. Ein Beispiel finden Sie unter Verwenden des Dev-Proxys in CI/CD-Szenarien.

So warten Sie beispielsweise, bis eine getrennte Dev Proxy-Instanz auf Linux oder macOS beendet wird:

# 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

Vermeiden Sie die erzwungene Beendigung des Dev Proxy-Prozesses, z. B. mithilfe von kill -9. Wenn Sie den Prozess auf diese Weise beenden, löscht Dev Proxy die Aufzeichnungs- oder Wiederherstellen der Systemproxyeinstellungen nicht. Um den Dev-Proxy über die Befehlszeile zu beenden, verwenden Sie "Stop", der diese API aufruft und bis zu 10 Sekunden wartet, bis Der Dev-Proxy beendet wird.

Modelle

`ProxyInfo`

Informationen zur derzeit ausgeführten Dev Proxy-Instanz.

Eigenschaft	Typ	Beschreibung
`recording`	`boolean`	Gibt an, ob der Proxy zurzeit Anforderungen aufzeichnet
`configFile`	`string`	Pfad zur Konfigurationsdatei, die Dev Proxy verwendet (schreibgeschützt)

`JwtOptions`

Optionen zum Generieren eines JWT-Tokens.

Eigenschaft	Typ	Beschreibung
`name`	`string`	Der Name des Benutzers, für den das Token erstellt werden soll
`audiences`	`string[]`	Die Zielgruppen, für die das Token erstellt werden soll
`issuer`	`string`	Der Aussteller des Tokens
`roles`	`string[]`	Ein Rollenanspruch, der dem Token hinzugefügt werden soll
`scopes`	`string[]`	Ein Bereichsanspruch, der dem Token hinzugefügt werden soll
`claims`	`KeyValuePair`	Ansprüche, die dem Token hinzugefügt werden sollen
`validFor`	`number`	Die Dauer (in Minuten), für die das Token gültig ist
`signingKey`	`string`	Der Schlüssel, der zum Signieren des Tokens verwendet werden soll. Muss mindestens 32 Zeichen lang sein. Wenn nicht angegeben, wird ein zufällig generierter Schlüssel verwendet.

`JwtInfo`

Informationen zu einem JWT-Token.

Eigenschaft	Typ	Beschreibung
`token`	`string`	Das JWT-Token

Siehe auch

Feedback

War diese Seite hilfreich?

Zuletzt aktualisiert um 2026-11-05

Proxy-API

Vorgänge

GET /proxy

Beispiel: Abrufen von Informationen zur derzeit ausgeführten Dev Proxy-Instanz

POST /proxy

Beispiel: Starten der Aufzeichnung

Beispiel: Beenden der Aufzeichnung

Beenden der Aufzeichnung und Generieren von Berichten

POST /proxy/jwtToken

GET /proxy/logs

POST /proxy/mockrequest

GET /proxy/rootCertificate?format=crt

POST /proxy/stopproxy

Modelle

ProxyInfo

JwtOptions

JwtInfo

Siehe auch

Feedback

Zusätzliche Ressourcen

`GET /proxy`

`POST /proxy`

`POST /proxy/jwtToken`

`GET /proxy/logs`

`POST /proxy/mockrequest`

`GET /proxy/rootCertificate?format=crt`

`POST /proxy/stopproxy`

`ProxyInfo`

`JwtOptions`

`JwtInfo`