Управление производственными API в AceDataCloud

Производственный API-ключ — это не просто секретная строка. Это точка контроля для того, кто может вызывать что, сколько они могут потреблять, как долго длится доступ, какое приложение платит и как можно отследить инцидент.

AceDataCloud предоставляет эти средства контроля на четырех связанных уровнях:

Выпуск учетных данных — создание ключа для конкретного Приложения.
Политика баланса Приложения — определение того, откуда списывается использование и что происходит при низкой квоте.
Наблюдаемость использования — отслеживание статуса, стоимости, задержки, API, Приложения и учетных данных.
Жизненный цикл учетных данных — обновление ограничений, ротация секретов и отзыв доступа.

Цикл контроля управления производственными API

Это руководство объединяет отдельные API управления платформы в одну практическую операционную модель.

¶ Сначала разделите два типа учетных данных

AceDataCloud использует разные учетные данные для разных поверхностей:

Учетные данные	Используются для	Типичный хост
Токен аккаунта / Токен платформы	Управление аккаунтом: Приложения, учетные данные, балансы, использование, заказы	`platform.acedata.cloud/api/v1/**`
Учетные данные API	Вызов бизнес-API для сервиса	`api.acedata.cloud/**`

Они не взаимозаменяемы. Учетные данные бизнес-API не следует использовать для вызова конечных точек управления, а Токен платформы не следует встраивать в приложение в качестве его ключа бизнес-API.

Это разделение создает полезную границу безопасности:

Храните Токены платформы в строго контролируемой операционной среде.
Предоставляйте каждой нагрузке собственные Учетные данные API.
Позволяйте службам времени выполнения вызывать только необходимые им бизнес-API.
Позволяйте CI или административной службе выполнять управление учетными данными и балансом.

¶ Выпускайте одни учетные данные на нагрузку и среду

Создайте учетные данные с помощью POST https://platform.acedata.cloud/api/v1/credentials/, используя Токен аккаунта.

Минимальный запрос, ориентированный на производство, может включать отображаемое имя, независимый лимит потребления, срок действия и список разрешенных API:

curl -X POST 'https://platform.acedata.cloud/api/v1/credentials/' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d "{
    \"application_id\": \"${APPLICATION_ID}\",
    \"name\": \"prod-support-agent\",
    \"limited_amount\": 100,
    \"expired_at\": \"2027-01-01T00:00:00Z\",
    \"allowed_api_ids\": [\"${CHAT_API_ID}\"],
    \"metadata\": {\"environment\": \"production\", \"owner\": \"support-platform\"}
  }"

Контракт создания поддерживает:

Поле	Цель управления
`application_id`	Привязывает использование к целевому Приложению
`name`	Делает нагрузку идентифицируемой при аудитах
`limited_amount`	Устанавливает независимый лимит использования учетных данных; `null` означает отсутствие независимого лимита
`expired_at`	Устанавливает автоматический доступ, ограниченный по времени
`allowed_api_ids`	Ограничивает учетные данные выбранными API
`host`	Хранит информацию о хосте учетных данных там, где это применимо
`for_user_id`	Позволяет владельцу Приложения выпускать делегированные учетные данные для другого пользователя
`tags` / `metadata`	Записывает контекст среды, команды, системы или тикета изменения

Пустой массив allowed_api_ids нормализуется как отсутствие ограничений. Не отправляйте пустой массив, если ваше намерение — «ничего не разрешать». Используйте реальный список разрешенных API.

Сервисы API/Agent обычно возвращают учетные данные Token. Прокси-сервисы обычно возвращают идентификацию по имени пользователя/паролю, а Прокси-Приложение допускает только одни учетные данные.

Считайте ответ на создание конфиденциальным. Немедленно сохраните секрет в менеджере паролей или менеджере секретов и не записывайте ответ в журналы. Клиенты не должны полагаться на то, что открытые секреты останутся доступными для последующего получения; API жизненного цикла могут возвращать замаскированные значения.

¶ Используйте лимиты как средства контроля радиуса поражения, а не только для бюджетирования

limited_amount на уровне учетных данных полезен для сдерживания утекшего ключа или неконтролируемой нагрузки, но это лишь одна часть управления затратами.

Надежная иерархия выглядит так:

Лимит учетных данных: максимальная подверженность риску для одной нагрузки.
Баланс Приложения: квота, доступная Приложению сервиса с подпиской.
Политика глобального баланса: необязательный резервный вариант для подходящих Приложений с оплатой по мере использования.
Авторизация овердрафта: отдельная платформенная авторизация только для чтения, которую клиенты не могут включить самостоятельно.

Не считайте их эквивалентными.

Например, даже когда у Приложения есть доступная квота, лимит отдельных учетных данных все равно может заблокировать нагрузку. И наоборот, включение совместного использования глобального баланса может позволить подходящему Приложению продолжать работу после того, как его собственного баланса недостаточно, — но это не отменяет лимиты учетных данных, проверки отключения или истечения срока действия.

¶ Отслеживайте баланс с единицей измерения и статусом

Запросите Приложение с помощью:

curl --fail-with-body \
  "https://platform.acedata.cloud/api/v1/applications/${APPLICATION_ID}" \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"

Операционно важные поля включают:

remaining_amount — текущая квота Приложения; отрицательное значение указывает на квоту, ожидающую урегулирования.
used_amount — накопленное использование, указанное для Приложения.
service.unit — единица измерения, такая как Credit, Count или Token.
disabled — отключено ли Приложение.
expired_at — истек ли доступ по подписке.
allow_overdraft — указание только для чтения на одобренный администратором овердрафт.

Никогда не предполагайте, что сумма указана в долларах США. Пороги оповещений должны быть определены в фактической единице измерения сервиса.

Один лишь положительный баланс не доказывает доступность. Ваша проверка работоспособности должна оценивать баланс, disabled, истечение срока действия, лимиты учетных данных и статус сервиса. Для Прокси-сервисов синхронизация баланса может быть приостановлена или завершиться по тайм-ауту, и в этом случае может быть возвращен последний сохраненный баланс.

Краткая проверка на Python:

import os
import requests

minimum = float(os.getenv("MINIMUM_BALANCE", "10"))
url = f"https://platform.acedata.cloud/api/v1/applications/{os.environ['APPLICATION_ID']}"
headers = {"Authorization": f"Bearer {os.environ['PLATFORM_TOKEN']}"}

response = requests.get(url, headers=headers, timeout=10)
response.raise_for_status()
application = response.json()

remaining = application.get("remaining_amount")
unit = application.get("service", {}).get("unit", "unknown")

if application.get("disabled"):
    raise RuntimeError("Application is disabled")
if application.get("expired_at"):
    print("Check whether the Application expiry has passed:", application["expired_at"])
if remaining is None:
    raise RuntimeError("No balance is available for this Application")
if not application.get("allow_overdraft", False) and float(remaining) < minimum:
    raise RuntimeError(f"Low balance: {remaining} {unit}")

Для нескольких сервисов получите список Приложений один раз и оценивайте каждый элемент локально вместо опроса каждой конечной точки сведений о Приложении с высокой частотой.

¶ Явно решите, разрешено ли совместное использование глобального баланса

Подходящие Приложения с оплатой по мере использования можно настроить на использование глобального баланса аккаунта, когда их собственного баланса недостаточно:

curl -X POST \
  "https://platform.acedata.cloud/api/v1/applications/${APPLICATION_ID}/update-allow-consume-global/" \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{"allow_consume_global": true}'

Используйте возвращенное значение allow_consume_global как источник истины. Не предполагайте, что запрошенное значение было сохранено.

Важные ограничения:

Приложения Period не могут потреблять глобальный баланс; сервер сохраняет для поля значение false.
Требуются принадлежащие вам application_id и Токен аккаунта.
Если allow_overdraft=true, Приложение с оплатой по мере использования может продолжать списывать средства со своего собственного баланса ниже нуля и не переключится на глобальный баланс только потому, что его собственного баланса недостаточно.
Когда происходит резервное переключение, поведение овердрафта определяется глобальным Приложением, которое фактически платит.

Глобальный резервный вариант улучшает непрерывность, но также расширяет финансовый радиус поражения. Включайте его как осознанную политику на уровне сервиса, а не как удобство по умолчанию.

¶ Отслеживайте каждый производственный вызов по учетным данным

AceDataCloud хранит записи вызовов API и сводки биллинга за последние 60 дней. Тела запросов и ответов хранятся 30 дней; записи за дни 30–60 сохраняют сводки, но больше не возвращают полные тела metadata.request и metadata.response.

Запросите последние записи по адресу:

curl --get 'https://platform.acedata.cloud/api/v1/usage/apis/' \
  --data-urlencode "application_id=${APPLICATION_ID}" \
  --data-urlencode "credential_id=${CREDENTIAL_ID}" \
  --data-urlencode 'perspective=both' \
  --data-urlencode 'limit=100' \
  --data-urlencode 'ordering=-created_at' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"

Полезные фильтры включают application_id, api_id, credential_id, status_code и временные границы ISO 8601. Параметр perspective разделяет три представления:

billing — вызовы, оплачиваемые текущим аккаунтом.
actor — вызовы, фактически инициированные текущим аккаунтом.
both — объединение по умолчанию оплаченных и инициированных вызовов. Ключевыми полями для реагирования на инциденты являются:

Поле	Операционное использование
`credential_id`	Идентификация скомпрометированной или неисправно работающей нагрузки
`trace_id`	Расследование одного запроса от начала до конца
`status_code`	Разделение успешных и неуспешных вызовов
`elapsed`	Отслеживание задержки
`used_amount`	Использование, рассчитанное по исходным правилам
`original_amount`	Использование до скидок Application
`deducted_amount`	Итоговая сумма, фактически списанная
`remaining_amount`	Квота Application после списания
`actor_user_id` / `user_id`	Разграничение вызывающего лица и учетной записи, ответственной за оплату

Для крупных запросов используйте более короткие интервалы — предпочтительно один день или меньше — и добавляйте фильтры. Если идентичный запрос уже выполняется, API может вернуть 429 usage_query_in_progress; соблюдайте Retry-After с отсрочкой. Ошибка 503 usage_query_timeout является сигналом сузить запрос, а не немедленно повторять его.

¶ Создайте процесс ротации и реагирования на инциденты до того, как он понадобится

Практический сценарий реагирования:

Идентифицируйте учетные данные по записи об использовании или конфигурации сервиса.
Сдержите компрометацию, снизив их лимит, изменив срок действия, сузив allowed_api_ids или отозвав их.
Замените секрет и обновите менеджер секретов.
Разверните новое значение в нагрузке без его записи в журналы.
Проверьте успешные вызовы с ожидаемым идентификатором учетных данных.
Просмотрите недавние записи по учетным данным, статусу, API и идентификатору трассировки.
Отзовите устаревшие учетные данные после подтверждения перехода.

Создавайте отдельные учетные данные для разработки, промежуточной среды, производства, запланированных заданий и сторонних интеграций. Это делает ротацию локальной, а атрибуцию — понятной. Один общий ключ «production» максимизирует как риск простоя, так и неоднозначность расследования.

¶ Рекомендуемый базовый уровень контроля

Для каждой производственной нагрузки:

¶ Управление — это цикл

Выдача учетных данных, мониторинг баланса и трассировка использования не должны управляться как отдельные задачи. Вместе они образуют непрерывный цикл контроля:

выдавайте узко → отслеживайте оплачивающее Application → трассируйте фактические вызовы → быстро заменяйте или отзывайте.

API управления AceDataCloud предоставляют поля, необходимые для реализации этого цикла без смешения доступа к управлению, доступа во время выполнения, квоты и атрибуции биллинга. Результат — не просто более безопасный API-ключ; это производственная система с ограниченной подверженностью рискам и объяснимым использованием.

Управление производственным API в AceDataCloud: учетные данные, контроль баланса и мониторинг использования