Exchange Online 管理 API の使用を開始する

注:

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

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

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

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

Exchange Online 管理 API は、REST ベースで特定の PowerShell コマンドレットを実行する方法を提供し、従来の Exchange Web サービス (EWS) シナリオを置き換えます。詳細については、「Exchange Online 管理 API の概要」を参照してください。

前提条件: 認証とアクセス許可を設定する

Exchange Online 管理 API の最初の呼び出しを行う前に、アプリまたはスクリプトがorganizationに安全にアクセスできるように、認証とアクセス許可を設定する必要があります。完全な手順については、「Exchange Online 管理 API の認証と承認」を参照してください。

手順の要約を次に示します。

Microsoft Entra ID にアプリを登録する: 委任アクセスまたはアプリのみアクセス用のアプリ登録を作成します。
API のアクセス許可を付与する:
- 委任:Exchange.ManageV2。
- アプリのみ: Exchange.ManageAsAppV2。
管理者の同意を取得する: アクセス許可が organization レベルで同意されていることを確認します。
RBAC ロールの割り当て: 管理するオブジェクトを対象とするユーザー (委任) またはサービスプリンシパル (アプリのみ) にロールを割り当てます。
アクセストークンを取得する: 委任されたフローまたはアプリ専用のフローを使用して、有効な OAuth トークンを取得します。
Know your organization context: 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 エンドポイント内でのサポートされるパラメーターを指定する CmdletInput エンベロープを含める必要があります。

サポートされているコマンドレットとパラメーターの詳細については、「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 Bad Request」が発生します。許可されているコマンドレットとパラメーターについては、エンドポイント固有のドキュメントを常にチェックしてください。

最初の呼び出しの例

要求の構造とヘッダーを理解したので、最初の呼び出しを成功させましょう。この例では、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 と、組織レベルのプロパティ ( MailTipsAllTipsEnabled や MailTipsExternalRecipientsTipsEnabled など) を含む JSON ペイロード。

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's システムメールボックスのルーティングキーを使用します。例:
```
X-AnchorMailbox: APP:SystemMailbox{bb558c35-97f1-4cb9-8ff7-d53741dc928c}@contoso.onmicrosoft.com
```
  注:
  
  システムメールボックス GUID の値はすべての組織で同じであり、 bb558c35-97f1-4cb9-8ff7-d53741dc928cです。

改ページ

一部のExchange Online 管理 API エンドポイントは大きな結果を返します。ページネーションをサポートするエンドポイントは、個々のエンドポイントのドキュメントで明確に識別されます。ページネーションは、より小さなチャンクで結果を取得し、タイムアウトや調整を回避するのに役立ちます。

1 ページあたりのアイテム数を指定するには、要求本文で 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
    }
  }
}

フォローアップページ:

@odata.nextLink 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>、および <routing key> を適切な値に置き換えて、メールボックスの表示名とプライマリ 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 Unauthorized

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

403 Forbidden

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

400 Bad Request

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

ベース URL が正しくない

原因: 環境のベース URL が正しくありません。
修正:organization に適したベース URL を使用します。

ページネーションの問題

原因: ページングされた呼び出し間でパラメーターを変更しているか、 @odata.nextLinkが無視されている。
修正:
- すべてのページでパラメーターの一貫性を維持します。
- 常に @odata.nextLink URL に POST してください。
- ResultSize パラメーターを使用しない場合、API の既定値は、1 ページあたり 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 Bad Request を回避します。
ルーティングと環境の認識:
- Use the correct base URL for your organization.
- ルーティングエラーを回避するために、すべての要求に X-AnchorMailbox を含めます。

次の手順

最終更新: 2026-09-25