Microsoft Entra同期 API の概要

名前空間: microsoft.graph

重要

Microsoft Graph の /beta バージョンの API は変更される可能性があります。 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。 v1.0 で API を使用できるかどうかを確認するには、Version セレクターを使用します。

Microsoft Entra ID 同期 ("プロビジョニング" とも呼ばれます) を使用すると、次のいずれかの ID のプロビジョニング (作成、メンテナンス) とプロビジョニング解除 (削除) を自動化できます。

• Microsoft Entra IDする Active Directory
• Workday to Microsoft Entra ID
• Dropbox、Salesforce、ServiceNow などのクラウド アプリケーションへのMicrosoft Entra ID

Microsoft Graph の同期 API を使用して、次のような ID 同期をプログラムで管理できます。

• 同期ジョブの作成、開始、および停止
• ジョブの同期スキーマに変更を加える
• 現在の同期状態を確認する

Microsoft Entra IDでの同期の詳細については、次を参照してください。

• Microsoft Entra IDを使用して SaaS アプリケーションへのユーザー プロビジョニングとプロビジョニング解除を自動化する
• Microsoft Entra 管理センターでのエンタープライズ アプリのユーザー アカウント プロビジョニングの管理

サンプル テナントまたは独自のテナントの Graph エクスプローラーで API を試すこともできます。

同期ジョブ

同期ジョブは、バックグラウンドで定期的に実行し、あるディレクトリの変更をポーリングし、別のディレクトリにプッシュすることで同期を実行します。 同期ジョブは、常にテナント内のアプリケーションの特定のインスタンスに固有です。 同期ジョブのセットアップの一環として、ターゲット ディレクトリ内のオブジェクトの読み取りと書き込みを許可し、ジョブの同期スキーマをカスタマイズする必要があります。

詳細については、「 同期ジョブ」を参照してください。

同期スキーマ

同期スキーマは、同期するオブジェクトと、それらの同期方法を定義します。 同期スキーマには、特定の同期ジョブのセットアップ情報の大部分が含まれています。 通常、一部の 属性マッピングをカスタマイズするか、スコープ フィルターを 追加して、特定の条件を満たすオブジェクトのみを同期します。

同期スキーマには、次のコンポーネントが含まれています。

• ディレクトリ定義
• 同期規則
• オブジェクト マッピング

詳細については、「 同期スキーマ」を参照してください。

同期テンプレート

同期テンプレートは、特定のアプリケーションに対して事前に構成された同期設定を提供します。 これらの設定 (最も重要なのは、 同期スキーマ) は、テンプレートに基づく すべての同期ジョブ に既定で使用されます。 テンプレートは、アプリケーション開発者によって指定されます。

詳細については、「 同期テンプレート」を参照してください。

同期 API の操作

同期 API の操作には、主に 、synchronizationJob リソースと synchronizationSchema リソースへのアクセスが含まれます。 synchronizationJob リソースを見つけるには、同期ジョブが属しているサービス プリンシパル オブジェクトの ID を把握する必要があります。 次の例では、 synchronizationJob リソースと synchronizationSchema リソースを操作する方法を示します。

Authorization

Microsoft Entra同期 API を操作するために、Microsoft Graph では次の詳細なアクセス許可がサポートされています。

• Synchronization.Read.All
• Synchronization.ReadWrite.All
• Application.ReadWrite.OwnedBy
• Application.Read.All
• Application.ReadWrite.All

次の最小特権Microsoft Entraディレクトリ ロール:

• アプリケーション管理者
• クラウド アプリケーション管理者
• ハイブリッド ID 管理者

各 API を呼び出すために必要な権限の詳細については、それぞれの API リファレンス ドキュメントを参照してください。

表示名でサービス プリンシパル オブジェクトを検索する

次の例は、表示名でサービス プリンシパル オブジェクトを検索する方法を示しています。

要求

GET https://graph.microsoft.com/beta/servicePrincipals?$select=id,appId,displayName&$filter=startswith(displayName, 'salesforce')

Response

HTTP/1.1 200 OK

{
   "value":[
      {
         "id":"bc0dc311-87df-48ac-91b1-259bd2c3a31c",
         "appId":"f7808c5e-cb57-4e37-8094-406d302c0f8d",
         "displayName":"Salesforce"
      },
      {
         "id":"d813d7d7-0f41-4edc-b284-d0dfaf399d15",
         "appId":"219561ee-1480-4c67-9aa6-63d861fae3ef",
         "displayName":"salesforce 3"
      }
   ]
}

アプリ ID でサービス プリンシパル オブジェクトを検索する

次の例は、アプリ ID でサービス プリンシパル オブジェクトを検索する方法を示しています。

要求

GET https://graph.microsoft.com/beta/servicePrincipals?$select=id,appId,displayName&$filter=AppId eq '219561ee-1480-4c67-9aa6-63d861fae3ef'

Response

HTTP/1.1 200 OK

{
    "value": [
        {
            "id": "d813d7d7-0f41-4edc-b284-d0dfaf399d15",
            "appId": "219561ee-1480-4c67-9aa6-63d861fae3ef",
            "displayName": "salesforce 3"
        }
    ]
}

既存の同期ジョブを一覧表示する

次の例では、既存の同期ジョブを一覧表示する方法を示します。

要求

GET https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs
GET https://graph.microsoft.com/beta/servicePrincipals/60443998-8cf7-4e61-b05c-a53b658cb5e1/synchronization/jobs

Response

HTTP/1.1 200 OK

{
    "value": [
        {
            "id": "SfSandboxOutDelta.e4bbf44533ea4eabb17027f3a92e92aa",
            "templateId": "SfSandboxOutDelta",
            "schedule": {
                "expiration": null,
                "interval": "PT20M",
                "state": "Active"
            },
            "status": {}
        }
    ]
}

同期ジョブの状態を取得する

次の例では、同期ジョブの状態を取得する方法を示します。

要求

GET https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs/{jobId}

GET https://graph.microsoft.com/beta/servicePrincipals/60443998-8cf7-4e61-b05c-a53b658cb5e1/synchronization/jobs/SfSandboxOutDelta.e4bbf44533ea4eabb17027f3a92e92aa

Response

HTTP/1.1 200 OK

{
    "id": "SfSandboxOutDelta.e4bbf44533ea4eabb17027f3a92e92aa",
    "templateId": "SfSandboxOutDelta",
    "schedule": {
        "expiration": null,
        "interval": "PT20M",
        "state": "Active"
    },
    "status": {}
}

同期スキーマを取得する

次の例では、同期スキーマを取得する方法を示します。

要求

GET https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs/{jobId}/schema

Response

HTTP/1.1 200 OK

{
    "directories": [],
    "synchronizationRules": []
}

関連コンテンツ

• ディレクトリ拡張機能属性を使用した同期の構成
• カスタム ターゲット属性との同期を構成する