다음을 통해 공유

내보내기 활동 API

이 문서에서는 Security Copilot 관리 내보내기 API에 대한 API 계약 및 예상 출력 데이터 스키마에 대해 설명합니다.

내보내기 API는 작업 영역 관리자에게 페이지를 매긴 형식으로 프롬프트 및 프롬프트 응답을 내보낼 수 있는 기능을 제공합니다.

인증 및 권한 부여

  • 권한 부여: 전달자 토큰 인증
  • 필요한 권한: 작업 영역 소유자/관리

서비스 주체를 사용하여 인증

  1. 앱 등록을 만듭니다 (예: 와 같은 mysecuritycopilotexportapp이름 사용).

참고

기존 소유자만 이 작업을 수행할 수 있습니다.

  1. Security Copilot 역할 할당에서 새 서비스 주체를 소유자로 추가합니다.

    역할 및 할당 Security Copilot 참조하세요. Security Copilot RAG(역할 할당 가능 그룹)에 대한 권한 할당을 지원하므로 RAG를 만든 다음 다음과 같이 SP(서비스 주체)를 추가합니다.

  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를 사용하는 예제(와 함께 /.defaultv2 패턴):

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

참조:

액세스 토큰(CLI) 및 .default scope 가져옵니다.

비 소유자로서의 응답

소유자가 아닌 경우 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": "a83f0049-7f81-4a56-bf4c-f58d6ad4dd97"
    },
    "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 잘못된 요청 잘못된 매개 변수 또는 누락된 작업 영역/테넌트 정보
404 찾을 수 없음 관리 내보내기 API를 사용할 수 없음
500 내부 서버 오류 내보내기 중 서버 오류

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 잘못된 요청 잘못된 매개 변수 또는 누락된 작업 영역/테넌트 정보
404 찾을 수 없음 관리 내보내기 API를 사용할 수 없음
500 내부 서버 오류 내보내기 중 서버 오류

데이터 모델

기본 응답 속성

두 내보내기 API는 다음 공통 속성을 사용하여 응답을 반환합니다.

속성 유형 설명
workspaceId string 내보낸 작업 영역 ID
workspaceName string 내보낸 작업 영역 이름
tenantId string 내보낸 테넌트 ID
sessionsContinuationToken string? 다음 페이지에 대한 토큰(더 이상 데이터가 없는 경우 null)
totalCount integer? 현재 페이지의 총 항목 수
sessionCount integer 이 요청에 사용되는 세션 수

페이지 매김

두 API 모두 커서 기반 페이지 매김을 지원합니다.

  1. 초기 요청: 을 사용하지 않고 요청합니다 continuationToken.
  2. 후속 요청: 이전 응답에서 를 사용합니다 sessionsContinuationToken .
  3. 데이터 끝: 가 null이면 sessionsContinuationToken 더 이상 데이터를 사용할 수 없습니다.

페이지 매김 예제

첫 번째 요청

GET /exports/prompts?sessionCount=100

응답에는 continuationToken이 포함됩니다.

{
  "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.
  • 토큰의 경우 인증 흐름에 따라 (v1) 또는 --scope https://api.securitycopilot.microsoft.com/.default (v2)를 사용할 --resource https://api.securitycopilot.microsoft.com 수 있습니다. 액세스 토큰 가져오기(CLI) 및 .default scope 참조하세요.

참조

  • Last updated on