Ключи API
На этой странице
Ключи API позволяют вашему собственному программному обеспечению — или любой сторонней системе, поддерживающей BYOK (Bring Your Own Key), — использовать модели, опубликованные Performance Hub. Ключами управляют в разделе «Настройки» (значок шестеренки) → Service Access & API Keys. Для управления ими необходимо быть Organisation Administrator.
«Создавайте ключи API, чтобы стороннее программное обеспечение и системы, поддерживающие BYOK (Bring Your Own Key), могли подключаться к моделям, опубликованным Performance Hub.»
Рисунок 1. Список ключей API: метка, маскированный ключ, статус, расходы и лимиты, модели, время последнего использования и действия со строкой
Список ключей
| Столбец | Значение |
|---|---|
| Label | Необязательное имя, которое вы присвоили ключу. |
| Key | Маскированный ключ (например, phk_7Qm2…Xa9LkP) — полный секрет после создания больше никогда не показывается. |
| Status | Active, Provisioning… (недолго, пока настраивается новый ключ) или Disabled (отозван; строка затемнена). |
| Spend / limits | Расходы за все время и степень приближения к лимитам расходов, заданным для ключа. |
| Models | all или количество моделей, которыми ограничен ключ. |
| Last used | Когда ключ в последний раз выполнял запрос. |
| Actions | Edit, Rotate, Revoke (или Re-activate), Delete. |
Если вы используете Workflows, в строке Workflows вместо маскированного ключа отображается Managed service. Если ключей нет вообще, в списке отображается "No API keys yet."
Создание ключа
Нажмите Create key. Откроется панель Create API key:
Рисунок 2. Панель Create API key: метка, тип подключения, лимиты расходов, ограничения частоты, ограничение моделей и переопределение защитных механизмов
| Параметр | Поведение |
|---|---|
| Label (optional) | Имя ключа — обычно название системы, для которой он предназначен (например, Hotel Concierge App, Clinic Intake Assistant или Booking Website). Настоятельно рекомендуется — по меткам использование распределяется в Activity и Logs. |
| Connection type | API key — «Обычные ключи API остаются в списке API Keys.» External agent — «Внешние агенты отображаются в Connected Services и используют этот ключ для аутентификации.» Задается при создании ключа; позже изменить нельзя. |
| Set spend limits for this key | «Задайте любое сочетание дневных, месячных и пожизненных лимитов для этого ключа.» — Daily limit («Сбрасывается в начале каждого дня (по часовому поясу объекта).»), Monthly limit («Сбрасывается 1-го числа каждого месяца (по часовому поясу объекта).») и Lifetime cap («Общие расходы за все время существования ключа. Никогда не сбрасывается.»). |
| Rate limits (optional) | «Ограничьте количество запросов и токенов в минуту для этого ключа. Оставьте поле пустым, чтобы снять ограничение.» — Requests / min и Tokens / min. |
| Restrict models for this key | «С этим ключом можно будет использовать только выбранные модели.» Выберите из моделей, включенных для объекта. |
| Override facility guardrails for this key | «Не выбирайте ничего, чтобы явно отключить защитные механизмы для этого ключа.» Если параметр включен, ключ использует собственный набор защитных механизмов вместо набора объекта — включая вариант «none». См. Защитные механизмы. |
Нажмите Create key.
Однократный показ секрета
Новый ключ показывается один раз в диалоговом окне Copy your API key:
Рисунок 3. Новый ключ показывается один раз: скопируйте его, прежде чем закрыть диалоговое окно
«Полный ключ показывается только сейчас. Сохраните его в надежном месте.»
Скопируйте его в свой менеджер секретов, прежде чем нажать Done. После закрытия этого окна отображается только маскированная форма ключа. Если вы потеряли секрет, выполните Rotate для ключа, чтобы получить новый.
Изменение ключа
Нажмите на строку ключа (или на значок карандаша Edit), чтобы открыть панель Configure API key — с теми же параметрами, что и при создании (метка, лимиты расходов, ограничения частоты, ограничение моделей, переопределение защитных механизмов):
Рисунок 4. Панель Configure API key
Изменения вступают в силу через несколько мгновений после сохранения. Если для ключа заданы дневные или месячные лимиты, в его строке отображается использование относительно них (Today, This month, Lifetime), а при достижении лимита — значок Limit reached.
Жизненный цикл ключа: ротация, отзыв, удаление
Для каждого действия открывается диалоговое окно подтверждения, в котором точно описано, что произойдет:
| Действие | Результат | Текст подтверждения |
|---|---|---|
| Rotate | Выпускает новый секрет (показывается один раз) с теми же настройками; старый секрет сразу перестает работать. | «Будет выпущен новый ключ, а текущий ключ сразу перестанет работать.» «Вам потребуется перенастроить все сервисы, которые еще используют старый ключ. Это действие нельзя отменить.» |
| Revoke | Немедленно отключает ключ с возможностью восстановления. | «Этот ключ будет немедленно отключен, и все сервисы, которые его используют, перестанут работать. Позже его можно будет снова активировать.» |
| Re-activate | Восстанавливает отозванный ключ (с тем же секретом). | Нет — выполняется немедленно. |
| Delete | Удаляет ключ навсегда. | «Ключ будет удален навсегда, и все сервисы, которые его используют, перестанут работать. Это действие нельзя отменить.» |
Рисунок 5. Подтверждение удаления ключа API
Что выбрать: выполняйте ротацию при подозрении на утечку (сервис сохраняет настройки и историю — нужно лишь обновить секрет); отзывайте ключ, чтобы временно приостановить работу системы; удаляйте только тогда, когда интеграция больше никогда не понадобится.
Подключение с помощью ключа
Карточка Connecting to the API под списком ключей показывает базовый URL и пример запроса для вашей среды, который можно скопировать и вставить. Полное краткое руководство с примерами SDK и обработкой ошибок см. в разделе Подключение приложения.