Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
Important
Начиная с версии 3.3.1, каждый запрос API прокси-сервера разработки требует Authorization: Bearer <token> заголовка; запросы без допустимого возврата 401 Unauthorizedмаркера.
Прокси-сервер разработки поставляется с веб-API, который позволяет программно взаимодействовать с прокси-сервером. API доступен по IP-адресу и порту, указанному в параметрах прокси-сервера.
Прокси-сервер разработки создает уникальный маркер для каждого запущенного экземпляра и сохраняет его в файле, доступном только пользователю, который запустил экземпляр. Получение маркера с помощью devproxy status или devproxy api token.
CI Если задана переменная среды, используйтеdevproxy api token, так как прокси-сервер разработки пропускает маркер из состояния и выходных данных запуска.
Чтобы использовать известный маркер вместо созданного, например при запуске прокси-сервера разработки и вызове API другого средства, задайте DEV_PROXY_API_TOKEN переменную среды перед запуском прокси-сервера разработки или перед его передачей --env с помощью параметра. Значение должно иметь по крайней мере 32 символов длиной, не подсчитывая конечную = заполнение, и может содержать только буквы ASCII, цифры и символы-, _.+~и/, при необходимости, за которым следует = заполнение. Прокси-сервер разработки обрезает пространство пробелов. Если значение недопустимо, прокси-сервер разработки не запускается и завершается ошибкой. Прокси-сервер разработки по-прежнему сохраняет маркер, поэтому devproxy statusdevproxy api tokenи devproxy stop продолжает работать.
Добавьте маркер в Authorization заголовок:
Authorization: Bearer <token>
Запросы без допустимого возврата 401 Unauthorizedмаркера. Запросы браузера также должны поступать из источника, указанного в параметре apiAllowedOrigins . Другие источники возвращаются 403 Forbidden.
Операции
В следующем списке показаны доступные операции API.
GET /proxy
Возвращает экземпляр ProxyInfo с информацией о текущем экземпляре прокси-сервера разработки.
Пример. Получение сведений о текущем экземпляре прокси-сервера разработки
Запрос:
GET http://localhost:8897/proxy
Authorization: Bearer <token>
Ответ:
200 OK
{
"recording": false,
"configFile": "/Users/user/dev-proxy/devproxyrc.json"
}
POST /proxy
Управляет текущим экземпляром прокси-сервера разработки. Сведения о запуске и остановке записи из скрипта или конвейера CI см. в разделе "Запись" из скриптов и CI.
Пример: начало записи
Запрос:
POST http://localhost:8897/proxy
Authorization: Bearer <token>
content-type: application/json
{
"recording": true
}
Ответ:
200 OK
{
"recording": true,
"configFile": "/Users/user/dev-proxy/devproxyrc.json"
}
Пример: остановка записи
Запрос:
POST http://localhost:8897/proxy
Authorization: Bearer <token>
content-type: application/json
{
"recording": false
}
Ответ:
200 OK
{
"recording": false,
"configFile": "/Users/user/dev-proxy/devproxyrc.json"
}
Остановка записи и создание отчетов
Остановка записи делает больше, чем остановить запись запросов. При отправке {"recording": false} во время записи прокси-сервера разработки прокси-сервер разработчика передает записанные запросы всем включенным подключаемым модулям в том порядке, в который они перечислены в файле конфигурации. Это то же самое, что и нажатие клавиши s в консоли, где запущен прокси-сервер разработки. На этом шаге:
- Подключаемые модули отчетов анализируют записанные запросы и создают отчеты.
-
Репортеры преобразуют отчеты в файлы. Каждый репортер записывает один файл для каждого отчета, например
ExecutionSummaryPlugin_MarkdownReporter.mdс именем<plugin>_<reporter>.<extension>.<plugin>— имя экземпляра подключаемого модуля, создающего отчет, и<reporter>является именем экземпляра репортера. Если файл с таким именем уже существует, репортер добавляет метку времени, напримерExecutionSummaryPlugin_MarkdownReporter_20261105114500.md. - Подключаемые модули генератора, например
OpenApiSpecGeneratorPlugin, записывают файлы, которые они создают.
Прокси-сервер разработки записывает эти файлы в текущий рабочий каталог, который является каталогом, с которого вы запустили прокси-сервер разработки.
API отвечает после завершения обработки записанных запросов подключаемыми модулями. В зависимости от используемых подключаемых модулей, например подключаемых модулей, вызывающих языковую модель, этот шаг может занять некоторое время, поэтому убедитесь, что http-клиент не истекает слишком рано. При поступлении ответа файлы отчета записываются на диск.
Прокси-сервер разработки также регистрирует ход обработки записанных запросов:
| Лог-сообщение | Meaning |
|---|---|
DONE |
Все подключаемые модули завершили обработку записанных запросов. |
No requests to process |
Подключаемый модуль не обнаружил записанных запросов для анализа. |
An error occurred in a plugin |
Сбой подключаемого модуля. Прокси-сервер разработки продолжается с помощью следующего подключаемого модуля и журналов DONE после завершения всех подключаемых модулей. |
Если прокси-сервер разработки не записывается при отправке {"recording": false}, прокси-сервер разработки не обрабатывает никакие запросы, не записывает файлы и не записывает журналы DONE.
Tip
При остановке использования POST /proxy/stopproxy прокси-сервера разработки во время записи прокси-сервер разработки также обрабатывает записанные запросы перед выходом. Однако этот API немедленно отвечает, поэтому необходимо дождаться завершения процесса прокси-сервера разработки, чтобы узнать, что отчеты готовы. Чтобы точно знать, когда отчеты готовы, сначала остановите запись, дождитесь ответа, а затем остановите прокси разработки.
Полный сценарий, запускающий прокси-сервер разработки, управляет записью через API и ожидает завершения прокси-сервера разработки, см. в сценариях CI/CD с помощью прокси-сервера разработки.
POST /proxy/jwtToken
Создает веб-токен JSON (JWT).
Запрос:
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
}
Примечание.
Зарегистрированные утверждения (например, iss, subaudexpnbf, , iat) jtiавтоматически добавляются в маркер. Если в запросе указано любое из этих утверждений, API игнорирует предоставленные значения.
Ответ:
200 OK
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6IkRldiBQcm94eSIsInN1YiI6IkRldiBQcm94eSIsImp0aSI6IjkyZjM5YzciLCJzY3AiOlsiUG9zdC5SZWFkIiwiUG9zdC5Xcml0ZSJdLCJyb2xlcyI6ImFkbWluIiwiY2xhaW0xIjoidmFsdWUiLCJjbGFpbTIiOiJ2YWx1ZSIsImF1ZCI6Imh0dHBzOi8vbXlzZXJ2ZXIuY29tIiwibmJmIjoxNzI3MTk4MjgyLCJleHAiOjE3MjcyMDE4ODIsImlhdCI6MTcyNzE5ODI4MiwiaXNzIjoiZGV2LXByb3h5In0.E_Gj9E58OrAh9uHgc-TW8DYfq8YHFrhaUTpKA4yXEIg"
}
GET /proxy/logs
Возвращает выходные данные журнала прокси-сервера разработки.
logs Эквивалент команды. Эта конечная точка доступна только в том случае, если прокси-сервер разработки работает в отсоединяемом режиме. В противном случае API возвращается 404 Not Found.
| Параметр запроса | Описание | Default |
|---|---|---|
lines |
Количество строк, возвращаемых из конца журнала | 50 |
follow |
При trueпотоковой передаче новых строк журнала в виде событий, отправленных сервером |
false |
since |
Возвращает только строки, зарегистрированные с указанной даты и времени. Используйте длительность (например, , 30s5m, 1h, ) 1dили iso 8601 дата и время (например, 2026-01-24T14:00:00 или 2026-01-24T14:00:00Z). Если метка времени не включает смещение часового пояса, прокси-сервер разработки использует локальный часовой пояс. |
n/a |
Параметр since фильтрует строки журнала по их полной дате и времени, как при возврате строк журнала, так и при потоковой передаче. Прокси-сервер разработки фильтрует каждый запрос по времени его запуска, поэтому запрос, который запускается до указанного времени, не возвращается, даже если он завершится позже.
По умолчанию API возвращает строки журнала в виде обычного текста. Чтобы получить массив json записей журнала, задайте для заголовка значение Acceptapplication/json. Чтобы потоковая передача строк журнала в виде событий, отправляемых сервером, задайте для заголовка Accepttext/event-stream значение или значение followtrue.
Запрос:
GET http://localhost:8897/proxy/logs?lines=10
Authorization: Bearer <token>
Ответ:
200 OK
content-type: text/plain
[last 10 lines of the Dev Proxy log]
POST /proxy/mockrequest
Вызывает макетный запрос. Эквивалент нажатия клавиши w в консоли, в которой запущен прокси-сервер разработки. API отвечает после завершения запроса макета.
Запрос:
POST http://localhost:8897/proxy/mockrequest
Authorization: Bearer <token>
Ответ:
204 No Content
GET /proxy/rootCertificate?format=crt
Скачивает открытый ключ корневого сертификата в формате PEM (конфиденциальность расширенной почты), который прокси-сервер разработки использует для расшифровки HTTPS-запросов. Этот API полезен, если вы хотите доверять корневому сертификату на узле при запуске прокси-сервера разработки в контейнере Docker.
На данный момент единственным поддерживаемым форматом является crt. API возвращает ошибку 400 bad request, если указать любой другой формат или не указывать формат вообще.
Запрос:
GET http://localhost:8897/proxy/rootCertificate?format=crt
Authorization: Bearer <token>
Ответ:
content-type: application/x-x509-ca-cert
-----BEGIN CERTIFICATE-----
[base64 encoded certificate]
-----END CERTIFICATE-----
POST /proxy/stopproxy
Корректно завершает работу прокси-сервера разработки. Если прокси-сервер разработки записывает запись, он останавливает запись и создает отчеты перед выходом. API сразу же отвечает, прежде чем прокси-сервер разработки завершит работу.
Запрос:
POST http://localhost:8897/proxy/stopproxy
Authorization: Bearer <token>
Ответ:
202 Accepted
Прокси-сервер разработки возвращается 202 Accepted сразу после завершения работы. Ответ не означает, что прокси-сервер разработки завершил работу. Во время завершения работы прокси-сервер разработки:
- Останавливает прием новых запросов прокси-сервера. Если прокси-сервер разработки зарегистрирован в качестве системного прокси-сервера, он восстанавливает предыдущие параметры системного прокси-сервера. Прокси-сервер разработки ожидает до пяти секунд, пока открытые подключения будут закрыты, а затем закрывает все оставшиеся подключения.
- Останавливает запись, если запись включена, и запускает подключаемые модули отчетов для записанных запросов, то же самое, что и при остановке записи самостоятельно. После завершения подключаемых модулей прокси-сервер разработки записывает отчеты и журналы
DONE. - Удаляет сведения о экземпляре и
devproxy statusdevproxy stopбольше не перечисляет его. - Завершает работу с кодом
0выхода.
Прокси-сервер разработки не удаляет корневой сертификат из доверенного хранилища сертификатов при завершении работы. Чтобы удалить сертификат, используйте удаление сертификата.
Завершение работы обычно занимает несколько секунд. Это может занять больше времени, когда подключаемые модули отчетов обрабатывают большую запись. После завершения работы API больше недоступен, поэтому не опрашивать API, чтобы проверить, завершен ли прокси-сервер разработки. Вместо этого используйте один из следующих вариантов:
- Дождитесь завершения работы идентификатора процесса (PID
devproxy --detach). - Запустите
devproxy status --pid <pid>, пока он не возвращает код1выхода, то есть экземпляр больше не работает. Дополнительные сведения см. в разделе о состоянии. - Если вы записывали запись, проверьте журнал прокси-сервера разработки для
DONEсообщения, которое выполняется после завершения подключаемых модулей отчетов. Пример см. в статье "Использование прокси-сервера разработки" в сценариях CI/CD.
Например, чтобы дождаться выхода отсоединяемого экземпляра прокси-сервера разработки в Linux или 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
Избегайте принудительного завершения процесса прокси-сервера разработки, например с помощью kill -9. По завершении процесса прокси-сервер разработки не очищает параметры записи или восстановления системного прокси-сервера. Чтобы остановить прокси-сервер разработки из командной строки, используйте остановку, которая вызывает этот API и ожидает завершения работы прокси-сервера разработки до 10 секунд.
Модели
ProxyInfo
Сведения о текущем экземпляре прокси-сервера разработки.
| Свойство | Type | Описание |
|---|---|---|
recording |
boolean |
Указывает, записывает ли прокси-сервер запросы |
configFile |
string |
Путь к файлу конфигурации, используемому прокси-сервером разработки (только для чтения) |
JwtOptions
Параметры создания токена JWT.
| Свойство | Type | Описание |
|---|---|---|
name |
string |
Имя пользователя, для создания маркера для |
audiences |
string[] |
Аудитории, для создания маркера для |
issuer |
string |
Издатель маркера |
roles |
string[] |
Утверждение роли для добавления в токен |
scopes |
string[] |
Утверждение области для добавления в токен |
claims |
KeyValuePair |
Утверждения для добавления в токен |
validFor |
number |
Длительность (в минутах), для которой маркер действителен |
signingKey |
string |
Ключ, используемый для подписи маркера. Должно быть не менее 32 символов длиной. Если не указано, используется случайный ключ. |
JwtInfo
Сведения о токене JWT.
| Свойство | Type | Описание |
|---|---|---|
token |
string |
Токен JWT |
См. также
Совместная работа с нами на GitHub
Источник этого содержимого можно найти на GitHub, где также можно создавать и просматривать проблемы и запросы на вытягивание. Дополнительные сведения см. в нашем руководстве для участников.
