Поделиться через

API действий экспорта

В этом документе описаны контракты API и ожидаемые схемы выходных данных для API экспорта Security Copilot Администратор.

API-интерфейсы экспорта предоставляют администраторам рабочих областей возможность экспортировать запросы и ответы на запросы в формате с разбивкой на страницы.

Проверка подлинности и авторизация

  • Авторизация: проверка подлинности маркера носителя
  • Необходимые разрешения: владелец или администратор рабочей области

Проверка подлинности с помощью субъекта-службы

  1. Создайте регистрацию приложения (например, используйте имя, например mysecuritycopilotexportapp).

Примечание.

Это могут сделать только существующие владельцы.

  1. Добавление нового субъекта-службы в качестве владельца в Security Copilot назначения ролей

    См. Security Copilot роли и назначения. Security Copilot поддерживает назначение разрешений группам с возможностью назначения ролей (RAG), поэтому создайте RAG, а затем добавьте в него субъект-службу следующим образом:

  2. Получите маркер носителя для субъекта-службы.

    Пример использования Azure CLI и секрета клиента:

    # Login as service principal (supports no-subscription tenants)
az login --service-principal -u 94e67e0c-7c41-4f5b-b5ae-f5b5918e2382 -p <client-secret> --tenant 536279f6-15cc-45f2-be2d-61e352b51eef --allow-no-subscriptions

# Retrieve access token for Security Copilot (v1 resource pattern)
az account get-access-token --resource https://api.securitycopilot.microsoft.com

Ссылки:

Проверка подлинности от имени пользователя

Убедитесь, что вы являетесь владельцем, как на шаге 2, и получите маркер носителя с областью действия Security Copilot.

Пример использования Azure CLI (шаблон версии 2 с /.default):

az account get-access-token --scope https://api.securitycopilot.microsoft.com/.default

Справочные материалы:

Получение маркера доступа (CLI) и .default область.

Ответ от имени владельца

Для не владельцев для вызовов API возвращается следующий ответ:

{
  "message": "Your role doesn\u0027t have access to the info requested. Contact a Security Administrator to change your role or try again with a different account. Learn more about copilot",
  "code": "403",
  "traceId": "0HNF1M54NKVJ3:00000041",
  "error": {
    "message": "Your role doesn\u0027t have access to the info requested. Contact a Security Administrator to change your role or try again with a different account. Learn more about copilot",
    "copilotErrorId": "doesNotHaveAccessToSecurityCopilot",
    "code": "403",
    "innerError": {
      "message": null,
      "date": "2025-08-22T19:32:04.4726177Z",
      "correlationId": "aaaa0000-bb11-2222-33cc-444444dddddd"
    },
    "traceId": "0HNF1M54NKVJ3:00000041"
  }
}

Конечные точки API

1. API экспорта Запросы

Конечная точка

https://api.securitycopilot.microsoft.com/exports/prompts

GET /exports/prompts

Параметры запроса

Н/Д

Пример запроса

GET /exports/prompts?sessionCount=500&startDate=2024-01-01T00:00:00Z&endDate=2024-12-31T23:59:59Z
Authorization: Bearer <token>

Схема ответа

Ответ на успешное выполнение - (200 OK)

{
  "workspaceId": "string",
  "workspaceName": "string",
  "tenantId": "string",
  "prompts": [
    {
      // Prompt object schema (see Framework.Models.Prompt)
    }
  ],
  "sessionsContinuationToken": "string?",
  "totalCount": "integer?",
  "sessionCount": "integer"
}

Коды ошибок и сообщения

Код состояния Код ошибки Сообщение об ошибке
400 Неправильный запрос (Bad Request) Недопустимые параметры или отсутствующие сведения о рабочей области или клиенте
404 Не найдено (Not Found) API Администратор экспорта не включены
500 Внутренняя ошибка сервера (Internal Server Error) Ошибка сервера во время экспорта

2. API экспорта оценок

Конечная точка

https://api.securitycopilot.microsoft.com/exports/evaluations

GET /exports/evaluations

Параметры запроса

Параметр Тип Обязательный По умолчанию Описание
sessionCount integer Нет 100 Количество сеансов для получения (диапазон: 1–1000).
continuationToken string Нет null Маркер для разбиения на страницы.
startDate DateTimeOffset Нет null Фильтр даты начала (включительно, формат ISO).
endDate DateTimeOffset Нет null Фильтр даты окончания (включительно, формат ISO).
orderByDescending boolean Нет false Упорядочение результатов по убыванию.

Пример запроса

GET /exports/evaluations?sessionCount=200&continuationToken=abc123
Authorization: Bearer <token>

Схема ответа

Ответ на успешное выполнение - (200 OK)

{
  "workspaceId": "string",
  "workspaceName": "string",
  "tenantId": "string",
  "evaluations": [
    {
      // Evaluation object schema
    }
  ],
  "sessionsContinuationToken": "string?",
  "totalCount": "integer?",
  "sessionCount": "integer"
}

Коды ошибок и сообщения

Код состояния Код ошибки Сообщение об ошибке
400 Неправильный запрос (Bad Request) Недопустимые параметры или отсутствующие сведения о рабочей области или клиенте
404 Не найдено (Not Found) API Администратор экспорта не включены
500 Внутренняя ошибка сервера (Internal Server Error) Ошибка сервера во время экспорта

Модели данных

Свойства базового ответа

Оба api экспорта возвращают ответы со следующими общими свойствами:

Свойство Тип Описание
workspaceId string Экспортируемый идентификатор рабочей области
workspaceName string Имя экспортируемой рабочей области
tenantId string Экспортируемый идентификатор клиента
sessionsContinuationToken string? Маркер для следующей страницы (значение NULL, если нет дополнительных данных)
totalCount integer? Общее количество элементов на текущей странице
sessionCount integer Количество сеансов, используемых для этого запроса

Разбивка на страницы

Оба API поддерживают разбиение на страницы на основе курсора:

  1. Первоначальный запрос: Выполните запрос без continuationToken.
  2. Последующие запросы: Используйте sessionsContinuationToken из предыдущего ответа.
  3. Конец данных: Если sessionsContinuationToken имеет значение NULL, данные больше не доступны.

Пример разбиения на страницы

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

GET /exports/prompts?sessionCount=100

Ответ включает продолжениеToken

{
  "sessionsContinuationToken": "[{\"compositeToken\":{\"token\":null,\"range\":{\"min\":\"05C1D1D5378D58\",\"max\":\"05C1D3CFCBB964\"}},\"resumeValues\":[\"2025-08-01T23:49:27.8981554+00:00\"],\"rid\":\"xQAMAIZUJBs7BEAAAADABQ==\",\"skipCount\":1}]",
  "prompts": [...],
  // ... other properties
}

Следующий запрос с использованием маркера (в кодировке URL-адреса)

GET /exports/prompts?sessionCount=100&continuationToken=%5B%7B%22compositeToken%22%3A%7B%22token%22%3Anull%2C%22range%22%3A%7B%22min%22%3A%2205C1D1D5378D58%22%2C%22max%22%3A%2205C1D3CFCBB964%22%7D%7D%2C%22resumeValues%22%3A%5B%222025-08-01T23%3A49%3A27.8981554%2B00%3A00%22%5D%2C%22rid%22%3A%22xQAMAIZUJBs7BEAAAADABQ%3D%3D%22%2C%22skipCount%22%3A1%7D%5D

Примечание.

  • Если у субъекта-службы нет подписок, az login можно сообщить, что они не найдены. В этом случае включите --allow-no-subscriptions.
  • Для маркеров можно использовать ( --resource https://api.securitycopilot.microsoft.com v1) или --scope https://api.securitycopilot.microsoft.com/.default (v2) в зависимости от потока проверки подлинности. См. статью Получение маркера доступа (CLI) и .default область.

Ссылки

  • Last updated on