Proxy API

Important

Ponieważ wersja 3.3.1, każde żądanie interfejsu API serwera proxy deweloperów wymaga nagłówka Authorization: Bearer <token> ; żądania bez prawidłowego zwrotu 401 Unauthorizedtokenu.

Serwer proxy dev jest dostarczany z internetowym interfejsem API, który umożliwia programową interakcję z serwerem proxy. Interfejs API jest dostępny na adresie IP i porcie określonym w ustawieniach serwera proxy.

Serwer proxy deweloperów generuje unikatowy token dla każdego uruchomionego wystąpienia i przechowuje go w pliku dostępnym tylko dla użytkownika, który uruchomił wystąpienie. Pobierz token przy użyciu polecenia devproxy status lub devproxy api token. Gdy zmienna CI środowiskowa jest ustawiona, użyj polecenia devproxy api token , ponieważ serwer proxy deweloperów pomija token ze stanu i danych wyjściowych uruchamiania.

Aby użyć znanego tokenu zamiast wygenerowanego, na przykład gdy inne narzędzie uruchamia serwer proxy deweloperów i wywołuje jego interfejs API, ustaw DEV_PROXY_API_TOKEN zmienną środowiskową przed uruchomieniem serwera proxy deweloperskiego lub przekaż go przy użyciu --env opcji . Wartość musi mieć długość co najmniej 32 znaków, a nie liczyć dopełnienia końcowego = i może zawierać tylko litery ASCII, cyfry i znaki -, , ~_+., i /, opcjonalnie, po = których następuje wypełnienie. Serwer proxy deweloperów przycina wokół białych znaków. Jeśli wartość jest nieprawidłowa, serwer proxy deweloperów nie uruchamia się i kończy działanie z powodu błędu. Serwer proxy deweloperów nadal przechowuje token, więc devproxy status, devproxy api tokeni devproxy stop nadal działa.

Uwzględnij token w nagłówku Authorization :

Authorization: Bearer <token>

Żądania bez prawidłowego tokenu zwracają wartość 401 Unauthorized. Żądania przeglądarki muszą również pochodzić z źródła wymienionego w ustawieniu apiAllowedOrigins . Inne źródła zwracają wartość 403 Forbidden.

Operacje

Na poniższej liście przedstawiono dostępne operacje interfejsu API.

GET /proxy

Zwraca wystąpienie obiektu ProxyInfo z informacjami o aktualnie uruchomionym wystąpieniu serwera proxy dewelopera.

Przykład: uzyskiwanie informacji o aktualnie uruchomionym wystąpieniu serwera proxy dev

Żądanie:

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

Reakcja:

200 OK

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

POST /proxy

Steruje aktualnie uruchomionym wystąpieniem serwera proxy dewelopera. Aby rozpocząć i zatrzymać nagrywanie ze skryptu lub potoku ciągłej integracji, zobacz Rejestrowanie ze skryptów i ciągłej integracji.

Przykład: rozpoczynanie nagrywania

Żądanie:

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

{
  "recording": true
}

Reakcja:

200 OK

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

Przykład: zatrzymywanie rejestrowania

Żądanie:

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

{
  "recording": false
}

Reakcja:

200 OK

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

Zatrzymywanie rejestrowania i generowanie raportów

Zatrzymywanie nagrywania nie tylko zatrzymuje przechwytywanie żądań. Po wysłaniu {"recording": false} , gdy serwer proxy deweloperów rejestruje, serwer proxy deweloperów przekazuje zarejestrowane żądania do wszystkich wtyczki z włączoną obsługą, w kolejności, w której są one wymienione w pliku konfiguracji. Jest to takie samo, jak naciśnięcie klawisza s w konsoli, w której działa serwer proxy deweloperów. W tym kroku:

  • Wtyczki raportowania analizują zarejestrowane żądania i tworzą raporty.
  • Reporterzy konwertują raporty na pliki. Każdy reporter zapisuje jeden plik dla każdego raportu o nazwie <plugin>_<reporter>.<extension>, na przykład ExecutionSummaryPlugin_MarkdownReporter.md. <plugin> to nazwa wystąpienia wtyczki, które wygenerowało raport, i <reporter> jest nazwą wystąpienia reportera. Jeśli plik o tej nazwie już istnieje, reporter dołącza znacznik czasu, na przykład ExecutionSummaryPlugin_MarkdownReporter_20261105114500.md.
  • Wtyczki generatora, takie jak , OpenApiSpecGeneratorPluginzapisują generowane pliki.

Serwer proxy deweloperów zapisuje te pliki w bieżącym katalogu roboczym, czyli katalogu, z którego uruchomiono serwer proxy deweloperów.

Interfejs API odpowiada po zakończeniu przetwarzania zarejestrowanych żądań przez wszystkie wtyczki. W zależności od używanych wtyczek, na przykład wtyczek wywołujących model językowy, ten krok może zająć trochę czasu, więc upewnij się, że klient HTTP nie upłynął zbyt wcześnie. Po nadejściu odpowiedzi pliki raportu są zapisywane na dysku.

Serwer proxy deweloperów rejestruje również postęp przetwarzania zarejestrowanych żądań:

Wiadomość logu Meaning
DONE Wszystkie wtyczki zakończyły przetwarzanie zarejestrowanych żądań.
No requests to process Wtyczka nie znalazła żadnych zarejestrowanych żądań do analizy.
An error occurred in a plugin Wtyczka nie powiodła się. Serwer proxy deweloperów kontynuuje każdą wtyczkę i dzienniki DONE po zakończeniu wszystkich wtyczek.

Jeśli serwer proxy dev nie rejestruje podczas wysyłania {"recording": false}, serwer proxy dewelopera nie przetwarza żadnych żądań, nie zapisuje żadnych plików i nie rejestruje DONE.

Wskazówka

Jeśli zatrzymasz używanie serwera proxy deweloperów podczas POST /proxy/stopproxy rejestrowania, serwer proxy dewelopera przetwarza również zarejestrowane żądania przed jego zamknięciem. Jednak ten interfejs API odpowiada natychmiast, więc musisz poczekać na zakończenie procesu serwera proxy deweloperskiego, aby wiedzieć, że raporty są gotowe. Aby dowiedzieć się dokładnie, kiedy raporty są gotowe, najpierw zatrzymaj nagrywanie, zaczekaj na odpowiedź, a następnie zatrzymaj serwer proxy deweloperów.

Aby uzyskać pełny skrypt, który uruchamia serwer proxy deweloperów, kontroluje rejestrowanie za pośrednictwem interfejsu API i czeka na zakończenie tworzenia serwera proxy, zobacz Używanie serwera proxy deweloperskiego w scenariuszach ciągłej integracji/ciągłego wdrażania.

POST /proxy/jwtToken

Generuje token internetowy JSON (JWT).

Żądanie:

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
}

Uwaga

Zarejestrowane oświadczenia (na przykład iss, , sub, audexp, nbf, , iat) jtisą automatycznie dodawane do tokenu. Jeśli określisz dowolne z tych oświadczeń w żądaniu, interfejs API ignoruje podane wartości.

Reakcja:

200 OK

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

GET /proxy/logs

Zwraca dane wyjściowe dziennika serwera proxy dev. logs Odpowiednik polecenia . Ten punkt końcowy jest dostępny tylko wtedy, gdy serwer proxy deweloperów działa w trybie odłączonym. W przeciwnym razie interfejs API zwraca wartość 404 Not Found.

Parametr zapytania Opis Domyślny
lines Liczba wierszy, które mają być zwracane z końca dziennika 50
follow Gdy trueprogram przesyła strumieniowo nowe wiersze dziennika jako zdarzenia wysyłane przez serwer false
since Zwraca tylko wiersze zarejestrowane od określonej daty i godziny. Użyj czasu trwania (na przykład , 30s, 5m, 1h1d) lub daty i godziny ISO 8601 (na przykład 2026-01-24T14:00:00 lub 2026-01-24T14:00:00Z). Jeśli znacznik czasu nie zawiera przesunięcia strefy czasowej, serwer proxy dewelopera używa lokalnej strefy czasowej. n/a

since Parametr filtruje wiersze dziennika według pełnej daty i godziny, zarówno podczas zwracania wierszy dziennika, jak i podczas ich przesyłania strumieniowego. Serwer proxy deweloperski filtruje każde żądanie o czas rozpoczęcia, więc żądanie, które zostało uruchomione przed upływem określonego czasu, nie zostanie zwrócone, nawet jeśli zakończy się później.

Domyślnie interfejs API zwraca wiersze dziennika jako zwykły tekst. Aby uzyskać tablicę JSON wpisów dziennika, ustaw Accept nagłówek na application/json. Aby przesyłać strumieniowo wiersze dziennika jako zdarzenia wysyłane przez serwer, ustaw Accept nagłówek na text/event-stream lub ustaw wartość followtrue.

Żądanie:

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

Reakcja:

200 OK
content-type: text/plain

[last 10 lines of the Dev Proxy log]

POST /proxy/mockrequest

Zgłasza pozorne żądanie. Odpowiednik naciśnięcia w w konsoli, w której działa serwer proxy deweloperów. Interfejs API odpowiada po zakończeniu pozorowego żądania.

Żądanie:

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

Reakcja:

204 No Content

GET /proxy/rootCertificate?format=crt

Pobiera klucz publiczny certyfikatu głównego w formacie PEM (Privacy Enhanced Mail), którego serwer proxy dewelopera używa do odszyfrowywania żądań HTTPS. Ten interfejs API jest przydatny, gdy chcesz ufać certyfikatowi głównemu na hoście podczas uruchamiania serwera proxy deweloperskiego w kontenerze platformy Docker.

W tej chwili jedynym obsługiwanym formatem jest crt. Interfejs API zwraca błąd 400 Nieprawidłowe żądanie, jeśli określisz inny format lub w ogóle nie określisz formatu.

Żądanie:

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

Reakcja:

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

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

POST /proxy/stopproxy

Bezpiecznie zamyka serwer proxy deweloperów. Jeśli serwer proxy deweloperów rejestruje, zatrzymuje nagrywanie i generuje raporty przed jego zamknięciem. Interfejs API reaguje natychmiast, zanim serwer proxy deweloperów zakończy zamykanie.

Żądanie:

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

Reakcja:

202 Accepted

Serwer proxy deweloperów jest zwracany 202 Accepted natychmiast po rozpoczęciu zamykania. Odpowiedź nie oznacza, że serwer proxy deweloperów zakończył działanie. Podczas zamykania serwer proxy deweloperów:

  1. Zatrzymuje akceptowanie nowych żądań serwera proxy. Jeśli serwer proxy deweloperów jest zarejestrowany jako serwer proxy systemu, przywraca poprzednie ustawienia serwera proxy systemu. Serwer proxy deweloperski czeka do pięciu sekund na zamknięcie otwartych połączeń, a następnie zamyka wszystkie pozostałe połączenia.
  2. Zatrzymuje nagrywanie, jeśli nagrywanie jest włączone i uruchamia wtyczki raportowania na zarejestrowanych żądaniach, tak samo jak podczas zatrzymywania rejestrowania samodzielnie. Po zakończeniu wtyczki serwer proxy deweloperów zapisuje raporty i dzienniki DONE.
  3. Usuwa informacje o wystąpieniu, devproxy stop więc devproxy status nie wyświetla już ich listy.
  4. Kończy działanie z kodem 0zakończenia .

Serwer proxy deweloperów nie usuwa certyfikatu głównego z zaufanego magazynu certyfikatów po zamknięciu. Aby usunąć certyfikat, użyj polecenia cert remove.

Zamknięcie zwykle trwa kilka sekund. Może to potrwać dłużej, gdy wtyczki raportowania przetwarzają duże nagranie. Po uruchomieniu zamykania interfejs API nie jest już osiągalny, więc nie sonduj interfejsu API, aby sprawdzić, czy serwer proxy deweloperów zakończył działanie. Zamiast tego użyj jednej z następujących opcji:

Aby na przykład poczekać na zamknięcie odłączonego wystąpienia serwera proxy deweloperskiego w systemie Linux lub 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

Unikaj wymuszania procesu tworzenia serwera proxy, na przykład przy użyciu polecenia kill -9. Po zakończeniu tego procesu serwer proxy deweloperów nie opróżni ustawień serwera proxy systemu rejestrowania ani przywracania. Aby zatrzymać serwer proxy dev z wiersza polecenia, użyj polecenia stop, który wywołuje ten interfejs API i czeka do 10 sekund, aż serwer proxy dewelopera zakończy działanie.

Modele

ProxyInfo

Informacje o aktualnie uruchomionym wystąpieniu serwera proxy dev.

Właściwość Typ Opis
recording boolean Czy serwer proxy aktualnie rejestruje żądania
configFile string Ścieżka do pliku konfiguracji używanego przez serwer proxy dewelopera (tylko do odczytu)

JwtOptions

Opcje generowania tokenu JWT.

Właściwość Typ Opis
name string Nazwa użytkownika do utworzenia tokenu dla
audiences string[] Odbiorcy do utworzenia tokenu dla
issuer string Wystawca tokenu
roles string[] Oświadczenie roli do dodania do tokenu
scopes string[] Oświadczenie zakresu do dodania do tokenu
claims KeyValuePair Oświadczenia do dodania do tokenu
validFor number Czas trwania (w minutach), dla którego token jest prawidłowy
signingKey string Klucz używany do podpisywania tokenu. Musi mieć długość co najmniej 32 znaków. Jeśli nie zostanie określony, użyje losowo wygenerowanego klucza.

JwtInfo

Informacje o tokenie JWT.

Właściwość Typ Opis
token string Token JWT

Informacje dodatkowe

  • Ostatnia aktualizacja o