내보내기 활동 API

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

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

인증 및 권한 부여

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

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

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

   • Microsoft Entra ID 빠른 시작: 앱 등록(포털)을 사용합니다.

   • CLI를 선호하는 경우 자습서: Azure CLI(서비스 주체 만들기)를 통해 ID를 만듭니다.

   • 필요에 따라 앱 등록에 자격 증명 추가: 자격 증명 추가(클라이언트 암호/인증서). 단계별 클라이언트 비밀 만들기는 클라이언트 암호 만들기(명시적 단계) 또는 포털 가이드, 앱 등록 및 서비스 주체 만들기(포털)를 참조하세요.

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

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

   • 역할 할당 가능 그룹 만들기

   • 그룹에 SP 추가(선택): 포털- 그룹 관리(구성원 추가) 또는 API— Microsoft Graph: 그룹 구성원 추가

3. 서비스 주체에 대한 전달자 토큰을 검색합니다.

   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
   

참조:

• SP(CLI)로 로그인
• 액세스 토큰 가져오기(CLI)
• .defaultscope 설명

사용자로 인증

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"
}

오류 코드 및 메시지

2. 평가 내보내기 API

끝점

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

GET /exports/evaluations

쿼리 매개 변수

요청 예제

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"
}

오류 코드 및 메시지

데이터 모델

기본 응답 속성

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

페이지 매김

두 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

참조

• 앱 등록(포털)
• SP 만들기(CLI 자습서)
• 자격 증명 추가(클라이언트 암호/인증서)
• 클라이언트 암호 만들기(명시적 단계)
• (Alt) 포털에서 클라이언트 암호 만들기
• Security Copilot 역할 & 할당)
• 그룹에 서비스 주체 추가(포털)
• 그룹에 서비스 주체 추가(API)
• SP(CLI)로 로그인
• 액세스 토큰 가져오기(CLI)