Exchange Online 管理 API の概要

注:

この記事で説明されている機能は現在プレビュー段階であり、すべての組織で利用できるわけではありません。変更される可能性があります。

この記事では、API 呼び出しExchange Online 管理初めて成功させる方法と、すべてのエンドポイントに適用されるキーの動作とパターンについて説明します。

この記事では、次のタスクに役立ちます。

Exchange Online 管理 API を呼び出す要求 (ヘッダーと本文) を形成する方法。
各環境で使用するサポートされている環境と基本 URL。
改ページとプロパティの選択のしくみ。
ルーティングに X-AnchorMailbox を使用するタイミングと方法。
一般的な問題とベストプラクティス。

Exchange Online 管理 API は、従来の Exchange Web Services (EWS) シナリオを置き換えて、特定の PowerShell コマンドレットを実行するための REST ベースの方法を提供します。詳細については、「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 エンドポイント内でサポートされているパラメーターを指定するコマンドレットInput エンベロープが含まれている必要があります。

サポートされているコマンドレットとパラメーターの詳細については、「Exchange Online 管理 API エンドポイントリファレンス」を参照してください。

必要なヘッダー:
- 承認: Bearer <access_token>。
- Content-Type: application/json
- X-AnchorMailbox: 今後の「X-AnchorMailbox ルーティングヒント」セクションで説明されているルーティングキー値。

本文:

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

注:

エンドポイントにサポートされていないコマンドレットまたはパラメーターを渡すと、エラー 400 無効な要求が発生します。許可されるコマンドレットとパラメーターについては、エンドポイントの特定のドキュメントを常にチェックします。

最初の呼び出しの例

要求の構造とヘッダーがわかったら、最初に成功した呼び出しを行ってみましょう。この例では、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 個のエントリを返します。 1 つの要求内のすべてのエントリを取得するには、値がサポートされている場合は、ResultSize パラメーターにUnlimited値を使用します。

ページ分割のベストプラクティスには、次の方法を使用します。

ページ間の要求に対してパラメーターの一貫性を維持します。
**生成された @odata.nextLink は、生成時から 5 ~ 10 分間のみ有効です。期限切れのリンクを使用しようとすると、要求が失敗する可能性があります。エラーを回避するには、 @odata.nextLink プロパティを受信してから 5 分以内にページ分割された呼び出しを完了します。

要求の例:

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 します (同じメソッドを使用します)。
ページ間でパラメーターを変更しないでください。

$selectを使用したプロパティの選択

Exchange Online 管理 API では、すべてのエンドポイントで $select クエリパラメーターがサポートされています。 $selectを使用して、応答ペイロードに必要なプロパティのみを返します。この方法は、応答のサイズを小さくし、クライアントでの解析オーバーヘッドを最小限に抑えるのに役立ちます。

$select 句で指定されたプロパティが無効な場合、サービスはそのプロパティをスキップし、残りの有効なプロパティを返します。

$selectをクエリパラメーターとしてエンドポイント URL に追加します。複数のプロパティをコンマで区切ります。

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 トークンが見つからない、無効な、または期限切れの OAuth トークン。
- スコープが正しくありません。
修正:
- アプリに適切なスコープが割り当てられていることを確認します。
  - 委任: Exchange.ManageV2。
  - アプリのみ: Exchange.ManageAsAppV2。
- 元のトークンの有効期限が切れた場合に備え、新しいトークンを取得します。
- 要求で正しい TenantID とアプリの登録の詳細が渡されていることを確認します。

403 Forbidden

原因: RBAC ロールが見つからないか、スコープ外のオブジェクトを管理しようとしています。
修正:
- 必要な RBAC ロールをユーザー (委任) またはサービスプリンシパル (アプリ専用) に割り当てます。
- オブジェクトが管理スコープ内にあることを確認します。

400 無効な要求

原因: サポートされていないパラメーターまたは正しくない形式のパラメーター。
修正:
- エンドポイントとコマンドレットの組み合わせのコマンドレットの詳細を確認します。
- REST エンドポイントのコマンドレットでサポートされているパラメーターのみを含めます。

ベース URL が間違っている

原因: 環境のベース URL が間違っています。
修正: organizationの正しいベース URL を使用します。

改ページの問題

原因: ページングされた呼び出し間でパラメーターを変更するか、 @odata.nextLinkを無視します。
修正:
- すべてのページでパラメーターの一貫性を維持します。
- 常に、 @odata.nextLink URL に POST します。
- ResultSize パラメーターを使用しない場合、API の既定値はページあたり 1,000 エントリです。

ルーティングエラー

原因: メールボックススコープの操作 に X-AnchorMailbox ヘッダーが見つからないか、正しくありません。
修正:
- メールボックス UPN (優先) または SMTP アドレスに X-AnchorMailbox を 含めます。
- 要求を送信する前に値を検証します。

ベストプラクティス

このセクションのガイドラインに従って、Exchange Online 管理 API を確実かつ効率的に使用してください。

認証とセキュリティ:
- 運用環境のワークロードに証明書またはマネージド ID でアプリのみの認証を使用します。
- 必要なアクセス許可 (Exchange.ManageV2 または Exchange.ManageAsAppV2) のみを要求します。
- リスクを軽減するために最小限の RBAC ロールを割り当てます。
要求の設計:
- Get-* コマンドレットを含むすべての操作には常に POST を使用します。
- エンドポイントにコマンドレットでサポートされているパラメーターのみを含めます。
- すべての操作 に X-AnchorMailbox を使用します。
パフォーマンスの最適化:
- 応答ペイロードのサイズを小さくするには、 $select を使用します。
- $selectと大きなデータセットの改ページを組み合わせます。
- ResultSize パラメーターを使用します。それ以外の場合、API の既定値は 1 ページあたり 1,000 エントリです。
回復性とエラー処理:
- 調整用の再試行ロジック (HTTP 429) を実装し、Retry-After を優先します。
- トラブルシューティングのためにエラー応答から要求 ID をログに記録します。
- 400 の不適切な要求を回避するために、要求を送信する前にパラメーターを検証します。
ルーティングと環境の認識:
- organizationの正しいベース URL を使用します。
- ルーティングエラーを回避するために、すべての要求に X-AnchorMailbox を 含めます。

次の手順

Last updated on 2025-11-17