Exchange Online 관리 API 시작

참고

이 문서에 설명된 기능은 현재 미리 보기로 제공되며, 모든 조직에서 사용할 수 없으며 변경될 수 있습니다.

이 문서에서는 첫 번째 성공적인 Exchange Online 관리 API 호출을 만드는 방법을 보여 줍니다. 모든 엔드포인트에 적용되는 주요 동작 및 패턴을 설명합니다.

이 문서는 다음 작업을 수행하는 데 도움이 됩니다.

Exchange Online 관리 API를 호출하는 요청(헤더 및 본문)을 구성하는 방법입니다.
각 환경에 사용할 지원되는 환경 및 기본 URL입니다.
페이지 매김 및 속성 선택 작동 방식.
라우팅에 X-AnchorMailbox 를 사용하는 시기 및 방법.
일반적인 문제 및 모범 사례.

Exchange Online 관리 API는 특정 PowerShell cmdlet을 실행하는 REST 기반 방법을 제공하여 레거시 EWS(Exchange Web Services) 시나리오를 대체합니다. 자세한 내용은 Exchange Online 관리 API 개요를 참조하세요.

필수 구성 요소: 인증 및 권한 설정

Exchange Online 관리 API를 처음 호출하려면 먼저 앱 또는 스크립트가 organization 안전하게 액세스할 수 있도록 인증 및 권한을 설정해야 합니다. 전체 지침은 Exchange Online 관리 API에 대한 인증 및 권한 부여를 참조하세요.

요약된 단계는 다음과 같습니다.

Microsoft Entra ID 앱 등록: 위임된 액세스 또는 앱 전용 액세스에 대한 앱 등록을 만듭니다.
API 권한 부여:
- 위임됨: Exchange.ManageV2.
- 앱 전용: Exchange.ManageAsAppV2.
관리자 동의 가져오기: 권한이 organization 수준에서 동의되었는지 확인합니다.
RBAC 역할 할당: 관리하는 개체를 포함하는 사용자(위임됨) 또는 서비스 주체(앱 전용)에 역할을 할당합니다.
액세스 토큰 획득: 위임된 또는 앱 전용 흐름을 사용하여 유효한 OAuth 토큰을 가져옵니다.
organization 컨텍스트 파악: TenantID(GUID) 및 기본 URL을 식별합니다.

지원되는 환경 및 기본 URL

Exchange Online 관리 API는 모든 Exchange Online 환경에서 사용할 수 있습니다. 각 환경은 요청에 다른 기본 URL을 사용하므로 다음 표에 설명된 대로 환경에 올바른 URL을 사용해야 합니다.

환경	기본 URL
Microsoft 365 또는 Microsoft 365 GCC	`https://outlook.office365.com`
21Vianet에서 운영하는 Office 365(중국)	`https://outlook.office365.cn`
Microsoft 365 GCC High	`https://outlook.office365.us`
Microsoft 365 DoD	`https://outlook-dod.office365.us`

최종 요청 URL은 사용자 환경에 따라 달라지며 다음 구문을 사용하여 TenantID 및 엔드포인트 이름을 포함합니다.

POST <BaseUrl>/adminapi/v2.0/<TenantID>/<EndpointName>

예시:

POST https://outlook.office365.com/adminapi/v2.0/0550b473-9fd2-4dbb-a058-a1640b4bf458/OrganizationConfig

요청 모델(헤더 및 본문)

모든 Exchange Online 관리 API 호출은 POST 메서드를 사용하고 일관된 요청 모델을 따릅니다. 본문에는 선택한 REST 엔드포인트 내에서 cmdlet 이름 및 지원되는 매개 변수를 지정하는 CmdletInput 봉투가 포함되어야 합니다.

지원되는 cmdlet 및 매개 변수에 대한 자세한 내용은 Exchange Online 관리 API 엔드포인트 참조를 참조하세요.

필수 헤더:
- 권한 부여: Bearer <access_token>.
- Content-Type: application/json
- X-AnchorMailbox: 예정된 X-AnchorMailbox 라우팅 힌트 섹션에 설명된 대로 라우팅 키 값입니다.

Body:

{
  "CmdletInput": {
    "CmdletName": "<Cmdlet Name>",
    "Parameters": {
      /* parameters supported for this cmdlet in the endpoint & their value */
    }
  }
}

참고

엔드포인트에 대해 지원되지 않는 cmdlet 또는 매개 변수를 전달하면 400 잘못된 요청 오류가 발생합니다. 허용되는 cmdlet 및 매개 변수에 대한 엔드포인트의 특정 설명서를 항상 검사.

첫 번째 호출 예제

이제 요청 구조와 헤더를 알게 되었으므로 첫 번째 성공적인 호출을 만들어 보겠습니다. 이 예제에서는 Microsoft 365 기본 URL을 사용하고 organization 구성을 검색합니다.

POST https://outlook.office365.com/adminapi/v2.0/12345678-90ab-cdef-1234-567890abcdef/OrganizationConfig
Authorization: Bearer <access_token>
Content-Type: application/json
X-AnchorMailbox: <appropriate routing key>

{
  "CmdletInput": {
    "CmdletName": "Get-OrganizationConfig"
  }
}

예상 결과: 200 OK 및 조직 수준 속성을 포함하는 JSON 페이로드(예: MailTipsAllTipsEnabled 및 MailTipsExternalRecipientsTipsEnabled).

X-AnchorMailbox 라우팅 힌트

X-AnchorMailbox 헤더는 모든 v2.0 관리 API 호출에 필수입니다. 요청을 올바른 백 엔드 서버로 전송하는 라우팅 힌트를 제공합니다. 라우팅 힌트가 없으면 요청을 비효율적으로 라우팅하거나 완전히 실패할 수 있습니다. 올바른 사서함 식별자를 제공하면 요청이 사서함의 홈 서버에 도달하고, 대기 시간을 줄이고, 불필요한 홉을 방지하고, 일관성을 향상시킵니다.

요청에 헤더를 추가하려면 다음 구문을 사용합니다.

X-AnchorMailbox: <routing key>

지원되는 라우팅 키 값은 다음 표에 설명되어 있습니다.

라우팅 키	형식	예제
UPN(기본 설정)	`AAD-UPN:<user@domain>`	`AAD-UPN:alex@contoso.com`
SMTP	`AAD-SMTP:<user@domain>`	`AAD-SMTP:alex@contoso.com`
Microsoft Entra 개체 ID/외부 디렉터리 개체 ID(EDOID)	`OID:<ExternalDirectoryObjectId>@<tenantId>`	`OID:80db1853-38c7-4ff3-945b-1e9a78119cb0@ab9f5dac-33ac-4f91-a9f4-8720b942f1a8`
사서함 GUID	`MBX:<mailboxGuid>@<tenantId>`	`MBX:80db1853-38c7-4ff3-945b-1e9a78119cb0@ab9f5dac-33ac-4f91-a9f4-8720b942f1a8`
시스템 사서함(앱 전용)	`APP:SystemMailbox{<systemMailboxGuid>}@<tenantIdOrOrganization>`	`APP:SystemMailbox{bb558c35-97f1-4cb9-8ff7-d53741dc928c}@contoso.onmicrosoft.com`

팁

사서함 이름 바꾸기에서 안정성을 위해 UPN을 사용합니다. 앱 전용 시나리오에 시스템 사서함 형식을 사용합니다.

라우팅 키를 사용하는 경우

특정 사서함에 바인딩하는 작업: 특정 사서함(/Mailbox , /MailboxFolderPermission)을 대상으로 하는 호출의 경우 대상 사서함의 라우팅 키를 사용합니다. 예시:
```
X-AnchorMailbox: UPN:alex@contoso.com
```
특정 사서함 대상이 없는 다른 모든 작업: 시나리오에 따라 다음 키 중 하나를 사용합니다.
- 위임된(사용자) 흐름: API를 실행하는 관리자의 라우팅 키를 사용합니다. 예시:
```
X-AnchorMailbox: UPN:admin@contoso.com
```
- 앱 전용 흐름: organization 시스템 사서함에 라우팅 키를 사용합니다. 예시:
```
X-AnchorMailbox: APP:SystemMailbox{bb558c35-97f1-4cb9-8ff7-d53741dc928c}@contoso.onmicrosoft.com
```
  참고
  
  시스템 사서함 GUID 값은 모든 조직에서 동일하며 입니다 bb558c35-97f1-4cb9-8ff7-d53741dc928c.

페이지 매김

일부 Exchange Online 관리 API 엔드포인트는 큰 결과를 반환합니다. 페이지 매김을 지원하는 엔드포인트는 개별 엔드포인트 설명서에서 명확하게 식별됩니다. 페이지 매김을 사용하면 더 작은 청크에서 결과를 검색하고 시간 제한 또는 제한을 방지할 수 있습니다.

페이지당 항목 수를 지정하려면 요청 본문에서 ResultSize 매개 변수를 사용합니다.
더 많은 결과를 사용할 수 있는 경우 응답에는 연속 URL이 있는 @odata.nextLink 속성이 포함됩니다.
다음 페이지를 가져오려면 동일한 헤더 및 인증을 @odata.nextLink 사용하여 URL에 POST합니다.

ResultSize 매개 변수를 사용하지 않는 경우 API는 기본적으로 최대 1,000개의 항목을 반환합니다. 단일 요청에서 모든 항목을 검색하려면 값 Unlimited 이 지원되는 경우 ResultSize 매개 변수 값을 사용합니다.

페이지를 매긴 모범 사례에 다음 방법을 사용합니다.

페이지 전체의 요청에 대해 매개 변수를 일관되게 유지합니다.
**생성된 @odata.nextLink 는 생성 시간으로부터 5~10분 동안만 유효합니다. 만료된 링크를 사용하려고 하면 요청이 실패할 수 있습니다. 오류를 방지하려면 속성을 받은 후 5분 이내에 페이지를 매긴 호출을 @odata.nextLink 완료합니다.

요청 예제:

POST https://outlook.office365.com/adminapi/v2.0/<TenantID>/Mailbox
Authorization: Bearer <access_token>
Content-Type: application/json
X-AnchorMailbox: <Routing key>

{
  "CmdletInput": {
    "CmdletName": "Get-Mailbox",
    "Parameters": {
      "ResultSize": 50
    }
  }
}

후속 페이지:

URL에 POST( @odata.nextLink 동일한 메서드 사용).
페이지 간에 매개 변수를 변경하지 마세요.

$select 있는 속성 선택

Exchange Online 관리 API는 모든 엔드포인트에서 $select 쿼리 매개 변수를 지원합니다. 를 사용하여 $select 응답 페이로드에 필요한 속성만 반환합니다. 이 전략은 응답 크기를 줄이고 클라이언트의 구문 분석 오버헤드를 최소화하는 데 도움이 됩니다.

절에 $select 지정된 속성이 유효하지 않으면 서비스는 해당 속성을 건너뛰고 나머지 유효한 속성을 반환합니다.

엔드포인트 URL에 쿼리 매개 변수로 추가 $select 합니다. 쉼표로 여러 속성을 구분합니다.

POST https://<base-url>/adminapi/v2.0/<TenantID>/<EndpointName>?$select=Property1,Property2,...

예를 들어 TenantID, access_token 및 라우팅 키를> 사서함에 대한 표시 이름 및 기본 SMTP 주소만 반환하는 적절한 값으로 바꿉<니다.<><>

POST https://outlook.office365.com/adminapi/v2.0/<TenantID>/Mailbox?$select=DisplayName,PrimarySmtpAddress
Authorization: Bearer <access_token>
Content-Type: application/json
X-AnchorMailbox: <routing key>

{
  "CmdletInput": {
    "CmdletName": "Get-Mailbox"
  }
}

일반적인 문제 및 해결 방법

이 섹션에서는 Exchange Online 관리 API로 작업할 때 발생할 수 있는 빈번한 문제에 대해 설명합니다.

401 권한 없음

원인:
- OAuth 토큰이 없거나, 잘못되었거나, 만료되었습니다.
- 잘못된 scope.
수정 사항:
- 앱에 올바른 범위가 할당되었는지 확인합니다.
  - 위임됨: Exchange.ManageV2.
  - 앱 전용: Exchange.ManageAsAppV2.
- 원래 토큰이 만료된 경우 새 토큰을 획득합니다.
- 요청에 올바른 TenantID 및 앱 등록 세부 정보가 전달되는지 확인합니다.

403 금지

원인: RBAC 역할이 없거나 scope 외부에서 개체를 관리하려고 합니다.
수정 사항:
- 사용자(위임됨) 또는 서비스 주체(앱 전용)에 필요한 RBAC 역할을 할당합니다.
- 개체가 관리 scope 내에 있는지 확인합니다.

400 잘못된 요청

원인: 지원되지 않거나 형식이 잘못 지정된 매개 변수입니다.
수정 사항:
- 엔드포인트 및 cmdlet 조합에 대한 cmdlet 세부 정보를 확인합니다.
- REST 엔드포인트에서 cmdlet에서 지원하는 매개 변수만 포함합니다.

잘못된 기본 URL

원인: 사용자 환경에 대한 잘못된 기본 URL입니다.
수정:organization 올바른 기본 URL을 사용합니다.

페이지 매김 문제

원인: 페이징된 호출 간에 매개 변수를 변경하거나 를 무시합니다 @odata.nextLink.
수정 사항:
- 모든 페이지에서 매개 변수를 일관되게 유지합니다.
- 항상 URL에 게시합니다 @odata.nextLink .
- ResultSize 매개 변수를 사용하지 않는 경우 API는 기본적으로 페이지당 1,000개의 항목으로 설정됩니다.

라우팅 오류

원인: 사서함 범위 작업에 대한 X-AnchorMailbox 헤더가 없거나 잘못되었습니다.
수정 사항:
- 사서함 UPN(기본 설정) 또는 SMTP 주소와 함께 X-AnchorMailbox 를 포함합니다.
- 요청을 보내기 전에 값의 유효성을 검사합니다.

모범 사례

이 섹션의 지침에 따라 Exchange Online 관리 API를 안정적이고 효율적으로 사용할 수 있습니다.

인증 및 보안:
- 프로덕션 워크로드에 인증서 또는 관리 ID를 사용하여 앱 전용 인증을 사용합니다.
- 필요한 권한(Exchange.ManageV2 또는 Exchange.ManageAsAppV2)만 요청합니다.
- 위험을 줄이기 위해 최소 RBAC 역할을 할당합니다.
요청 디자인:
- Get-* cmdlet을 비롯한 모든 작업에 항상 POST를 사용합니다.
- 엔드포인트에서 cmdlet에 대해 지원되는 매개 변수만 포함합니다.
- 모든 작업에 X-AnchorMailbox 를 사용합니다.
성능 최적화:
- 를 사용하여 $select 응답 페이로드 크기를 줄입니다.
- 큰 데이터 세트에 대한 페이지 매김과 결합 $select 합니다.
- ResultSize 매개 변수를 사용합니다. 그렇지 않으면 API는 기본적으로 페이지당 1,000개의 항목으로 설정됩니다.
복원력 및 오류 처리:
- 제한에 대한 재시도 논리(HTTP 429)를 구현하고 Retry-After를 적용합니다.
- 문제 해결을 위한 오류 응답의 로그 요청 ID입니다.
- 400 잘못된 요청을 방지하기 위해 요청을 보내기 전에 매개 변수의 유효성을 검사합니다.
라우팅 및 환경 인식:
- organization 올바른 기본 URL을 사용합니다.
- 라우팅 오류를 방지하기 위해 모든 요청에 대해 X-AnchorMailbox 를 포함합니다.

다음 단계

Last updated on 2025-11-17