Первый запрос к API

Начните с чтения. Этот сценарий не создаёт записи и помогает отдельно проверить адрес, ключ и права.

Что подготовить

Адрес своей тестовой системы с HTTPS.
Ключ с objects:read и правами владельца на нужные записи.
PowerShell 7 для примера ниже. Версию можно посмотреть командой $PSVersionTable.PSVersion. Обычный Windows PowerShell 5.1 не поддерживает показанный способ передачи ключа.

Если ключа ещё нет, начните со статьи Ключи и права API. Пароль от входа в NGENSIA здесь не подойдёт. Ключ — отдельный секрет: по нему другая программа выполняет разрешённые действия от имени его владельца.

1. Укажите адрес и введите ключ

Откройте PowerShell 7 на своём компьютере, не консоль Groovy внутри NGENSIA. Замените адрес примера адресом своей тестовой системы. Не отправляйте рабочий ключ на чужой сайт.

powershell

$ngensiaUrl = 'https://service.example.invalid'
$ngensiaToken = Read-Host 'Вставьте ключ API NGENSIA' -AsSecureString

Вставляйте ключ только после появления приглашения и нажмите Enter. Он не отображается открытым текстом и не становится частью введённой команды. Не добавляйте слово Bearer: PowerShell добавит его сам. Не сохраняйте ключ в статье, скриншоте или файле примера.

2. Прочитайте первые 25 записей

powershell

$result = Invoke-RestMethod -Method Get `
  -Uri "$ngensiaUrl/api/v1/objects?page=1&pageSize=25" `
  -Authentication Bearer -Token $ngensiaToken
$result.data.rows | Select-Object id, revision, values

Это запрос на чтение: он не создаёт заявки и не меняет их. id — идентификатор записи для следующих запросов, revision — её текущая версия, values — значения полей. Чтобы развернуть ответ, выполните $result | ConvertTo-Json -Depth 8; не публикуйте результат, если он содержит рабочие данные.

Способ ввода и передачи ключа описан в справочнике PowerShell. Для автоматического подключения используйте хранилище секретов вашей среды, а не интерактивный ввод.

3. Оцените результат

При успехе сервер вернёт HTTP 200. Ниже допустимый ответ без доступных записей, сокращённый до основных полей:

json

{
  "data": {"rows": [], "page": 1, "pageSize": 25},
  "meta": {"correlationId": "CORRELATION_ID", "apiVersion": "v1"}
}

Пустой список сам по себе не означает ошибку: записей может не быть или владелец ключа не имеет к ним доступа. Для диагностики запросите известную разрешённую запись по её ID.

После проверки закройте окно PowerShell или удалите переменную с ключом: Remove-Variable ngensiaToken. Это не отзывает ключ на сервере; ненужный тестовый ключ отзовите в разделе интеграций.

Если не получилось

Проверьте адрес без обхода TLS-проверки. При HTTP 401 проверьте срок и состояние ключа. При HTTP 403 проверьте scope и права владельца. Сохраните correlationId для администратора, но не полный Authorization header.

Первый запрос к API ​

Что подготовить ​

1. Укажите адрес и введите ключ ​

2. Прочитайте первые 25 записей ​

3. Оцените результат ​

Если не получилось ​