Exchange Online 管理 API のメールボックス エンドポイント

注:

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

Exchange Online 管理 API のメールボックス エンドポイントでは、代理人の代理送信を表示および管理できます。

一般的なユース ケースは次のとおりです。

  • メールボックスを一覧表示するか、特定のメールボックスの詳細を取得します。
  • 代理人のオプションの表示名を含め、SendOnBehalfTo の代理人構成を検査します。
  • 完全な代理人リストを上書きするか、段階的な変更 (追加/削除) を行って、代理人の代理送信を更新します。

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

エンドポイント URL

POST https://outlook.office365.com/adminapi/v2.0/<TenantID>/Mailbox

ヒント

サポートされている環境とベース URL で説明されているように、環境のベース URL を使用します。

モデルの要求

ヘッダー

Authorization: Bearer <auth token>
Content-Type: application/json
X-AnchorMailbox: <routing hint>

X-AnchorMailbox 値については、「X-AnchorMailbox ルーティング ヒント」を参照してください。

Body

  • Get-Mailbox:

    {
  "CmdletInput": {
    "CmdletName": "Get-Mailbox",
    "Parameters": {
      "Identity": "alex@contoso.com",                        //optional
      "ResultSize": <Integer | "Unlimited">,                 //optional (pagination)
      "IncludeGrantSendOnBehalfTowithDisplayNames": true     //optional
    }
  }
}

  • Set-Mailbox (上書き代理人):

    {
  "CmdletInput": {
    "CmdletName": "Set-Mailbox",
    "Parameters": {
      "Identity": "alex@contoso.com",      //required
      "GrantSendOnBehalfTo": [             //required
        "delegate1@contoso.com",
        "delegate2@contoso.com"
      ]
    }
  }
}

  • Set-Mailbox (Add/remove delegates (delegates の追加と削除):

    {
  "CmdletInput": {
    "CmdletName": "Set-Mailbox",
    "Parameters": {
      "Identity": "alex@contoso.com",                //required
      "GrantSendOnBehalfTo": {                       //required
        "add": ["delegate3@contoso.com"],
        "remove": ["delegate1@contoso.com"],
        "@odata.type": "#Exchange.GenericHashTable"
      }
    }
  }
}

改ページ

Get-Mailbox コマンドレットの ResultSize パラメーターは、ページネーションを制御します。 既定では、最大 1,000 件の結果が返されます。

さらに結果を使用できる場合、応答には継続 URL を含む @odata.nextLink プロパティが含まれます。 次のページをフェッチするには、同じ本文で @odata.nextLink 内の URL に対して新しい POST 要求を発行します。

プロパティの選択

このエンドポイントは、応答で特定のプロパティのみを返すように $select クエリ パラメーターをサポートしています。

サポートされているコマンドレットとパラメーター

次の一覧では、このエンドポイントでサポートされているコマンドレットとパラメーターについて説明します。 このエンドポイントの本文にある他のコマンドレットはエラーを結果として生成します。

  • Get-Mailbox:

    次の表で説明されている Get-Mailbox のパラメータのみが、REST エンドポイント経由で使用できます。

    パラメーター 必須 型 説明
    Identity 省略可能 文字列 情報を取得するメールボックスを指定します。 有効な値は、名前、識別名、エイリアス、ユーザー プリンシパル名 (UPN)、GUID、またはその他の一意識別子です。 省略して ResultSize の対象にすると、コマンドレットはすべてのメールボックスを返します。
    ResultSize 省略可能 整数または無制限 返される結果の数を制限します。 有効な値は、整数 (10 など) または値 "Unlimited" です。
    IncludeGrantSendOnBehalfToWithDisplayNames 省略可能 ブール型 値 True には、SendOnBehalfTo デリゲート エントリとその表示名が含まれます。

    注: このパラメーターは段階的なロールアウト段階であり、すべての組織で使用できるわけではありません。

  • Set-Mailbox:

    次の表に示す Set-Mailbox のパラメーターのみが、REST エンドポイント経由で使用できます。

    パラメーター 必須 型 説明
    Identity 省略可能 文字列 ターゲット メールボックスを指定します。 有効な値は、名前、識別名、エイリアス、UPN、GUID、またはその他の一意識別子です。
    GrantSendOnBehalfTo 必須 コレクションまたはハッシュ テーブル
    • 上書き: 完全なデリゲート リストの SMTP アドレスのリスト。 たとえば、「 ["bob@contoso.com","carol@contoso.com"] 」のように入力します。
    • 追加/削除: デリゲート リストを変更するための add 配列や remove 配列を含むハッシュ テーブル。 たとえば、「 { "add" : ["dave@contoso.com"], remove : ["carol@contoso.com"] } 」のように入力します。

応答の概要

注:

プレビュー中、エンドポイントには、API 応答に完全な Get-Mailbox コマンドレット出力が含まれます。 一般リリースへの移行中は、応答はこのセクションに記載されているコア プロパティ (EWS と同等のシナリオに必要なプロパティ) に制限されます。 このセクションに記載されているプロパティのみを使用することをお勧めします。 使用可能なプロパティに対する変更を文書化します。

  • Get-Mailbox 応答は、JSON オブジェクトまたはメールボックス プロパティを持つリスト配列です。 次のプロパティが取得されます。

    • ID: メールボックスの正規識別子 (通常はエイリアスまたは識別名)。
    • ID: メールボックス オブジェクトのサービス識別子。
    • 名前: メールボックスの一意の Exchange 表示名。
    • DisplayName: わかりやすい表示名です。
    • UserPrincipalName: メールボックスに関連付けられているアカウント。
    • エイリアス: 一意のメールボックス エイリアス。
    • ExternalDirectoryObjectId: メールボックスの Microsoft Entra ID オブジェクト GUID。
    • RecipientType: 使用可能なメールボックス値については、「 RecipientType」を参照してください。
    • RecipientTypeDetails: 可能なメールボックス値については、「 RecipientTypeDetails」を参照してください。
    • EmailAddresses: 受信者のすべてのプロキシ アドレス (SMTP: および SMTP: エントリを含む)。
    • PrimarySmtpAddress: 受信者のプライマリ SMTP アドレス ( EmailAddresses の SMTP: 値に対応)。
    • MaxSendSize: メールボックスが送信できる最大メッセージ サイズ。
    • GrantSendOnBehalfTo: メールボックスの代理アクセス許可を付与された代理人 (SMTP アドレス) の一覧。
    • GrantSendOnBehalfToWithDisplayNames: 代理人の表示名を含む同じリスト (要求された場合)。

  • Set-Mailbox コマンドレットは、成功時にHTTP 200 OKを返します。 正常な更新には、応答本文は必要ありません。

例

  • 例 1: 単純な Get-Mailbox (ページ リスト):

    この例では、organization の最初の 10 個のメールボックスを一覧表示します。 @odata.nextLink を使用して続行します。

    POST /adminapi/v2.0/<TenantID>/Mailbox HTTP/1.1
Host: outlook.office365.com
Authorization: Bearer <auth token>
Content-Type: application/json
X-AnchorMailbox: <Routing Hint>

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

  • 例 2: 特定のメールボックスの Get-Mailbox で、代理人の表示名を含める:

    この例では、メールボックスの詳細と、表示名を持つ SendOnBehalfTo 代理人を返します。

    POST /adminapi/v2.0/<TenantID>/Mailbox HTTP/1.1
Host: outlook.office365.com
Authorization: Bearer <auth token>
Content-Type: application/json
X-AnchorMailbox: <Routing Hint>

{
  "CmdletInput": {
    "CmdletName": "Get-Mailbox",
    "Parameters": {
      "Identity": "alex@contoso.com",
      "IncludeGrantSendOnBehalfTowithDisplayNames": true
    }
  }
}

  • 例 3: Set-Mailbox: 代理人リストを上書きします。

    この例では、指定されたメールボックスの SendOnBehalfTo リストを指定された代理人で上書きします。

    結果は 200 OK です。 delegate1@contoso.com メールボックス上の既存の SendOnBehalfTo 代理人の一部またはすべてを置き換え delegate2@contoso.com 。

    POST /adminapi/v2.0/<TenantID>/Mailbox HTTP/1.1
Host: outlook.office365.com
Authorization: Bearer <auth token>
Content-Type: application/json
X-AnchorMailbox: <Routing Hint>

{
  "CmdletInput": {
    "CmdletName": "Set-Mailbox",
    "Parameters": {
      "Identity": "alex@contoso.com",
      "GrantSendOnBehalfTo@odata.type": "#Collection(String)",
      "GrantSendOnBehalfTo": [
        "delegate1@contoso.com",
        "delegate2@contoso.com"
      ]
    }
  }
}

  • 例 4: Set-Mailbox: 既存の代理人リストに代理人を追加します。

    この例では、既存の代理人を維持したまま、新しい SendOnBehalfTo 代理人を指定されたメールボックスに追加します。

    結果は 200 OK です。 delegate3@contoso.com と delegate4@contoso.com が、メールボックス上の既存の代理人のリストに追加されます。

    POST /adminapi/v2.0/<TenantID>/Mailbox HTTP/1.1
Host: outlook.office365.com
Authorization: Bearer <auth token>
Content-Type: application/json
X-AnchorMailbox: <Routing Hint>

{
  "CmdletInput": {
    "CmdletName": "Set-Mailbox",
    "Parameters": {
      "Identity": "alex@contoso.com",
      "GrantSendOnBehalfTo": {
        "add": [
          "delegate3@contoso.com",
          "delegate4@contoso.com"
        ],
        "@odata.type": "#Exchange.GenericHashTable"
      }
    }
  }
}
  • 最終更新: