Proxy API

Dev Proxy include un'API Web che consente di interagire con il proxy a livello di codice. L'API è disponibile nell'indirizzo IP e nella porta specificata nelle impostazioni proxy.

Dev Proxy genera un token univoco per ogni istanza in esecuzione e lo archivia in un file accessibile solo all'utente che ha avviato l'istanza. Ottenere il token usando devproxy status o devproxy api token. Quando la CI variabile di ambiente è impostata, usare devproxy api token perché Dev Proxy omette il token dall'output di stato e avvio.

Per usare un token noto anziché un token generato, ad esempio quando un altro strumento avvia Dev Proxy e chiama l'API, impostare la DEV_PROXY_API_TOKEN variabile di ambiente prima di avviare Dev Proxy o passarla usando l'opzione --env . Il valore deve contenere almeno 32 caratteri, senza contare la spaziatura interna finale = e può contenere solo lettere ASCII, cifre e i caratteri -, ~_+., , e /, facoltativamente seguiti dalla = spaziatura interna. Dev Proxy taglia gli spazi vuoti circostanti. Se il valore non è valido, Dev Proxy non viene avviato e viene chiuso con un errore. Dev Proxy archivia ancora il token, quindi devproxy status, devproxy api tokene devproxy stop continua a funzionare.

Includere il token nell'intestazione Authorization :

Authorization: Bearer <token>

Le richieste senza un token valido restituiscono 401 Unauthorized. Le richieste del browser devono provenire anche da un'origine elencata nell'impostazione apiAllowedOrigins . Altre origini restituiscono 403 Forbidden.

Operazioni

L'elenco seguente mostra le operazioni API disponibili.

GET /proxy

Restituisce un'istanza di ProxyInfo con informazioni sull'istanza di Dev Proxy attualmente in esecuzione.

Esempio: Ottenere informazioni sull'istanza del proxy di sviluppo attualmente in esecuzione

Richiesta:

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

Risposta:

200 OK

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

POST /proxy

Controlla l'istanza di Dev Proxy attualmente in esecuzione. Per avviare e arrestare la registrazione da uno script o da una pipeline CI, vedere Registrare da script e CI.

Esempio: avviare la registrazione

Richiesta:

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

{
  "recording": true
}

Risposta:

200 OK

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

Esempio: arrestare la registrazione

Richiesta:

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

{
  "recording": false
}

Risposta:

200 OK

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

Arrestare la registrazione e generare report

L'arresto della registrazione non interrompe l'acquisizione delle richieste. Quando si invia {"recording": false} durante la registrazione di Dev Proxy, Dev Proxy passa le richieste registrate a tutti i plug-in abilitati, nell'ordine in cui sono elencate nel file di configurazione. Questa operazione equivale a premere s nella console in cui è in esecuzione Dev Proxy. Durante questo passaggio:

• I plug-in di creazione di report analizzano le richieste registrate e producono report.
• I giornalisti converte i report in file. Ogni reporter scrive un file per ogni report, denominato <plugin>_<reporter>.<extension>, ad esempio ExecutionSummaryPlugin_MarkdownReporter.md. <plugin> è il nome dell'istanza del plug-in che ha prodotto il report e <reporter> è il nome dell'istanza del reporter. Se esiste già un file con tale nome, il reporter aggiunge un timestamp, ExecutionSummaryPlugin_MarkdownReporter_20261105114500.mdad esempio .
• I plug-in del generatore, ad esempio OpenApiSpecGeneratorPlugin, scrivono i file generati.

Dev Proxy scrive questi file nella directory di lavoro corrente, ovvero la directory da cui è stato avviato Dev Proxy.

L'API risponde dopo che tutti i plug-in completano l'elaborazione delle richieste registrate. A seconda dei plug-in usati, ad esempio, plug-in che chiamano un modello linguistico, questo passaggio può richiedere un po', quindi assicurarsi che il client HTTP non timeout troppo presto. Quando arriva la risposta, i file di report vengono scritti su disco.

Dev Proxy registra anche lo stato di elaborazione delle richieste registrate:

Se Il proxy di sviluppo non viene registrato quando si invia {"recording": false}, Dev Proxy non elabora alcuna richiesta, non scrive alcun file e non registra DONE.

Per uno script completo che avvia Dev Proxy, controlla la registrazione tramite l'API e attende il completamento del proxy di sviluppo, vedere Usare il proxy di sviluppo in scenari CI/CD.

POST /proxy/jwtToken

Genera un token JSON Web (JWT).

Richiesta:

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
}

Risposta:

200 OK

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

GET /proxy/logs

Restituisce l'output del log del proxy di sviluppo. Equivalente al logs comando . Questo endpoint è disponibile solo quando Dev Proxy viene eseguito in modalità disconnessa. In caso contrario, l'API restituisce 404 Not Found.

Il since parametro filtra le righe di log in base alla data e all'ora complete, sia quando vengono restituite le righe di log che durante lo streaming. Dev Proxy filtra ogni richiesta al momento dell'avvio, quindi una richiesta avviata prima dell'ora specificata non viene restituita, anche se è stata completata in un secondo momento.

Per impostazione predefinita, l'API restituisce le righe di log come testo normale. Per ottenere una matrice JSON di voci di log, impostare l'intestazione Accept su application/json. Per trasmettere le righe di log come eventi inviati dal server, impostare l'intestazione Accepttext/event-stream su o impostare su followtrue.

Richiesta:

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

Risposta:

200 OK
content-type: text/plain

[last 10 lines of the Dev Proxy log]

POST /proxy/mockrequest

Genera una richiesta fittizia. Equivalente alla pressione di w nella console in cui è in esecuzione Dev Proxy. L'API risponde dopo il completamento della richiesta fittizia.

Richiesta:

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

Risposta:

204 No Content

GET /proxy/rootCertificate?format=crt

Scarica la chiave pubblica del certificato radice in formato PEM (Privacy Enhanced Mail) usata da Dev Proxy per decrittografare le richieste HTTPS. Questa API è utile quando si vuole considerare attendibile il certificato radice nell'host durante l'esecuzione di Dev Proxy in un contenitore Docker.

Al momento, l'unico formato supportato è crt. L'API restituisce un errore 400 Richiesta non valida se si specifica un altro formato o non si specifica un formato.

Richiesta:

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

Risposta:

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

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

POST /proxy/stopproxy

Arresta normalmente il proxy di sviluppo. Se dev Proxy sta registrando, interrompe la registrazione e genera i report prima di uscire. L'API risponde immediatamente, prima che il proxy di sviluppo finisca l'arresto.

Richiesta:

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

Risposta:

202 Accepted

Il proxy di sviluppo viene restituito 202 Accepted non appena inizia l'arresto. La risposta non significa che Dev Proxy sia stato chiuso. Durante l'arresto, Dev Proxy:

1. Interrompe l'accettazione di nuove richieste proxy. Se Dev Proxy è registrato come proxy di sistema, ripristina le impostazioni del proxy di sistema precedenti. Dev Proxy attende fino a cinque secondi prima che le connessioni aperte si chiudano e quindi chiuda le connessioni rimanenti.
2. Arresta la registrazione, se la registrazione è attiva ed esegue i plug-in di report sulle richieste registrate, come quando si arresta la registrazione manualmente. Al termine dei plug-in, Dev Proxy scrive i report e i log DONE.
3. Rimuove le informazioni sull'istanza, devproxy stop quindi devproxy status non viene più elencata.
4. Esce con codice 0di uscita.

Il proxy di sviluppo non rimuove il certificato radice dall'archivio certificati attendibile all'arresto. Per rimuovere il certificato, usare cert remove.

L'arresto richiede in genere alcuni secondi. La creazione di report dei plug-in può richiedere più tempo durante l'elaborazione di una registrazione di grandi dimensioni. Dopo l'avvio dell'arresto, l'API non è più raggiungibile, quindi non eseguire il polling dell'API per verificare se Dev Proxy è uscito. Usare invece una delle opzioni seguenti:

• Attendere che l'ID processo (PID) venga devproxy --detach stampato per uscire.
• Eseguire devproxy status --pid <pid> fino a quando non restituisce il codice 1di uscita , il che significa che l'istanza non è più in esecuzione. Per altre informazioni, vedere status.
• Se si esegue la registrazione, controllare il log del proxy di sviluppo per il DONE messaggio, che dev proxy registra al termine dei plug-in di report. Per un esempio, vedere Usare il proxy di sviluppo in scenari CI/CD.

Ad esempio, per attendere l'uscita di un'istanza di Dev Proxy scollegata in Linux o 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

Evitare di terminare forzatamente il processo del proxy di sviluppo, ad esempio usando kill -9. Quando si termina il processo in questo modo, Dev Proxy non scarica le impostazioni del proxy di sistema di registrazione o ripristino. Per arrestare Dev Proxy dalla riga di comando, usare stop, che chiama questa API e attende fino a 10 secondi per la chiusura del proxy di sviluppo.

Modelli

ProxyInfo

Informazioni sull'istanza del proxy di sviluppo attualmente in esecuzione.

JwtOptions

Opzioni per la generazione di un token JWT.

JwtInfo

Informazioni su un token JWT.

Vedere anche

• Record dagli script e dall'integrazione continua
• Usa Dev Proxy negli scenari CI/CD