SharePoint インデクサーを使用してアクセス許可メタデータを取り込み、ユーザー アクセス権に基づいて検索結果をフィルター処理する (プレビュー)

SharePointアクセス許可メタデータ インジェスト (プレビュー) では、Azure AI 検索 インデクサーを使用して、アクセス制御リスト (ACL) などのアクセス許可メタデータと、Microsoft 365のSharePointの他のコンテンツを保持します。 インデクサーは、インデックスが作成された各ドキュメントのメタデータとしてアクセス許可を格納します。 クエリ時に、ユーザーはアクセス許可を持つドキュメントのみを受け取ります。

前提 条件

• Azure AI 検索は、任意のリージョンの課金対象レベル (Basic 以降) に適用されます。

• Microsoft 365 のサイト、ライブラリ、フォルダー、およびアクセス許可が設定されたファイル内の SharePoint。

• この記事で説明する ACL 固有の要件を適用して、SharePoint インデクサーのドキュメントのすべての構成手順を完了します。

• Microsoft Entraアプリケーションのアクセス許可と、シナリオに適した資格情報を構成します。 ACL ごとのアクセス許可のシナリオを参照してください。 ACL インジェストには、アプリケーションのアクセス許可が必要です。 委任されたアクセス許可はサポートされていません。 アプリケーション許可と委任された許可のどちらにするかについては、アクセス許可の設定を選択するを参照してください。

• REST API バージョン 2026-08-01-preview または同等のプレビュー SDK パッケージ。

制限

• ACL の増分更新には、2026-05-01-preview REST API 以降が必要です。 以前のプレビュー API バージョンでは、システムは各項目の最初のインジェストでのみ ACL をキャプチャします。 後でアクセス許可を変更するには、明示的なインデックス再作成が必要です。 移行手順については、「 インデックス付きコンテンツとソース コンテンツの間でアクセス許可を同期する」を参照してください。

• 親スコープのアクセス許可の変更は、後続のインデクサーの実行時に自動的には取得されません。 更新オプションについては、「 インデックス付きコンテンツとソース コンテンツの間でアクセス許可を同期する」を参照してください。

• Azure ポータルでは、この機能はサポートされていません。

• このプレビューでは、次の機能はサポートされていません。

  • SharePoint Information Management ポリシーユーザー アクセスに適用できます。 システムは、クエリ時にこれらのポリシーを評価、取り込み、または尊重しません。

  • "すべてのユーザー" または "組織内のユーザー" を対象にした共有可能なリンク。"特定のユーザー" を対象にしたリンクのみがサポートされます。

  • SharePoint グループ (所有者、メンバー、閲覧者グループなど) は、2026-05-01-preview REST API 以降でサポートされています。 SharePoint グループのサポートを構成するを参照してください。 以前のプレビュー API バージョンでは、Microsoft Entra グループに対応付けられる SharePoint グループのみがサポートされます。

• 次のインデクサー機能では、SharePointから作成されたインデックス付きドキュメントでのアクセス許可の継承はサポートされていません。 スキルセットまたはインデクサーでこれらの機能のいずれかを使用する場合、ドキュメント レベルのアクセス許可はインデックス付きコンテンツに含まれません。

  • カスタム Web API スキル

  • エージェント検索でのイメージ サービス (プレビュー) に必要な資産ストアを含むナレッジ ストア。 そのため、SharePoint ACL を取り込むナレッジ ソースでは、画像配信はサポートされていません。

  • インデクサー エンリッチメント キャッシュ

  • デバッグ セッション

SharePointアクセス許可モデルのサポート

このプレビューでは、ドキュメント、リスト アイテム、および最新の ASPX サイト ページの基本的な ACL がサポートされています。

サポートされているグループリレーションシップ

Microsoft Entraグループ推移性は、Microsoft Entra内で適用されます。 SharePoint グループのメンバーである Microsoft Entra グループは展開されません。

階層型アクセス許可の評価方法

SharePoint権限は、継承が解除されない限り、Site → Library → Folder → File の階層を継承します。

インジェスト中、インデクサーは各レベルでユーザーとグループの識別子 (ID) を収集し、各ファイルの有効な ACL を計算します。

ACL ごとのアクセス許可シナリオ

ACL インジェストに必要なMicrosoft Entraアプリケーションのアクセス許可と資格情報の種類は、インデックスを作成する項目の種類とグループの種類によって異なります。 アプリの登録では、すべてのアクセス許可が API のアクセス許可で追加されます>アクセス許可を追加すると、フェデレーション資格情報が証明書とシークレット>Federated 資格情報の下に追加されます。 詳細な手順とスクリーンショットについては、「手順 3: Microsoft Entra アプリケーションの登録を作成するおよび登録済みアプリケーションをマネージド ID で構成するを参照してください。

フェデレーション資格情報は、クライアント シークレットではなく、信頼されたマネージド ID を使用してアプリを認証します。 同じフェデレーション資格情報は、SharePoint サイト グループのインジェスト (インデクサー) とクエリ時間の評価の両方を対象とします。 セットアップ手順については、 マネージド ID を使用した登録済みアプリケーションの構成に関するページを参照してください。

ACL インジェストを有効にする前に

登録済みのMicrosoft Entra アプリケーションで次の手順を実行します。

1. 前の表のシナリオは、インデックスを作成する予定の内容 (ドキュメント ライブラリ ファイル、リスト アイテム、ASPX サイト ページ) と、SharePointサイト グループを受け入れる必要があるかどうかに基づいて特定します。
2. Microsoft Entra 管理センターでアプリの登録を開き、API アクセス許可>アクセス許可の追加 に移動します。
3. シナリオに一覧表示されているMicrosoft Graphアクセス許可を追加します。 管理者の同意を付与します。
4. シナリオにSharePointアクセス許可も必要な場合は、アクセス許可の追加をもう一度選択し、SharePoint API を選択し、Sites.FullControl.All (または Sites.Selected) を追加します。 管理者の同意を付与します。
5. 資格情報を設定します:
   • Microsoft Graphのみのシナリオでは、クライアント シークレット (Certificates&secretsClient シークレット) またはフェデレーション資格情報を使用できます。
   • SharePointアクセス許可を含むシナリオでは、フェデレーション資格情報を Certificates & secretsFederated credentials に追加します。 マネージド ID を使用した登録済みアプリケーションの構成を参照してください。
6. ターゲット SharePoint サイトへのアクセス権をアプリケーションに付与します (スコープ付きアクセスに Sites.Selected を使用する場合は特に重要です)。インデックスを作成するコンテンツとアクセス許可を読み取ることができます。

正しいMicrosoft Entra識別子を見つける

各識別子は、Azure ポータル内の異なる場所に表示され、特定の構成フィールドにマップされます。 このセクションは、フェデレーション資格情報を使用SharePoint ACL インジェストを構成する場合のリファレンスとして使用します。 これらの識別子は、SharePoint グループ サポートの構成およびデータ ソースの接続文字列で参照されます。

フェデレーション資格証明のアプリケーション ID

データ ソースの接続文字列の federatedCredentialId とインデックス定義の FederatedCredentialApplicationId には、インジェスト アプリの ID ではなく、マネージド ID 自体のアプリケーション (クライアント) ID を使用します。

システム割り当てマネージド ID:

1. Azure AI 検索 サービスに移動します。
2. [ セキュリティとネットワーク>Identity] を選択します。
3. システム割り当て タブで、オブジェクト (プリンシパル) ID を控えておきます。
4. Microsoft Entra ID>Manage>Enterprise アプリケーションに移動します。
5. 検索サービス名を検索するか、 オブジェクト (プリンシパル) ID を 検索ボックスに貼り付けます。
6. 結果を選択し、[ プロパティ] を開きます。 ここに示す アプリケーション ID を コピーします。これは、データ ソース内の FederatedCredentialApplicationId の値であり、インデックスに federatedCredentialId 。

ユーザー割り当てマネージド ID:

1. ユーザー割り当てマネージド ID リソースに移動します。
2. [設定]>[プロパティ] の順に選択します。
3. クライアント ID をコピーします。これは、データ ソース内のFederatedCredentialApplicationIdとインデックス内のfederatedCredentialIdの値です。

ACL インジェストとクエリ時間の適用用に検索サービスを構成する

次の手順では、検索サービスで ACL インジェストを構成し、クエリ時に ACL の受け入れを有効にします。

ACL フィールドを設定する場所を選択する

ACL メタデータ フィールドをマップする場所は、インデクサーがソース項目ごとに 1 つのドキュメントを書き込むか、ソース項目ごとに複数のチャンクを書き込むかによって異なります。

チャンク化されたすべてのシナリオでは、すべてのチャンクに ACL フィールドが含まれている必要があります。 アクセス許可フィルターはドキュメントごとに適用されるため、ACL フィールドが欠けているチャンクは正しい呼び出し元に返せません。

1. データ ソースの構成

このセクションは、基本手順ステップ 4: データソースの作成との差分です。 indexerPermissionOptions で を設定して、SharePoint ドキュメントから userIds および groupIds のインデックスを作成できるようにします。

{
  "name": "my-sharepoint-acl-datasource",
  "type": "sharepoint",
  "indexerPermissionOptions": ["userIds", "groupIds"],
  "credentials": {
    "connectionString": "<connection-string>;"
  },
  "container": {
    "name": "<library-name>",
    "query": "<optional-folder-path>"
  }
}

2. インデックス定義にアクセス許可フィールドを追加する

ACL を格納し、クエリ時間のフィルター処理をサポートするために、 インデックス スキーマ定義 にフィールドを追加します。

{
  "fields": [
    { "name": "UserIds",  "type": "Collection(Edm.String)", "permissionFilter": "userIds",  "filterable": true, "retrievable": false },
    { "name": "GroupIds", "type": "Collection(Edm.String)", "permissionFilter": "groupIds", "filterable": true, "retrievable": false }
  ],
  "permissionFilterOption": "enabled"
}

値 retrievable 検証するには、開発中にのみ属性を true に設定します。 インデックスの再構築を必要とせず、取得可能な値を true から false に変更できます。

3. スキルセットでインデックス プロジェクションを構成する (該当する場合)

チャンクが有効になっている場合、 projectionMode が skipIndexingParentDocumentsされている場合、親ドキュメントはインデックスに書き込まれません。 indexProjections.selectors[].mappings を介して、ACL メタデータを各チャンクに引き継ぎます。

インデクサーで、統合ベクター化を有効にするときにテキスト分割スキルなどのデータ チャンクを含むスキルセットを使用する場合は、インデックス プロジェクションを使用して ACL プロパティを各チャンクにマップしてください。 次の例の // 行は説明的な注釈であり、有効な JSON ではありません。 要求を送信する前に、それらを削除します。

PUT https://{service}.search.windows.net/skillsets/{skillset}?api-version=2026-08-01-preview
{
  "name": "my-skillset",
  "skills": [
    {
      "@odata.type": "#Microsoft.Skills.Text.SplitSkill",
      "name": "#split",
      "context": "/document",
      "inputs": [{ "name": "text", "source": "/document/content" }],
      "outputs": [{ "name": "textItems", "targetName": "chunks" }]
    }
    // ... (other skills such as embeddings, entity recognition, etc.)
  ],
  "indexProjections": {
    "selectors": [
      {
        "targetIndexName": "chunks-index",
        "parentKeyFieldName": "parentId",          // must exist in target index
        "sourceContext": "/document/chunks/*",     // match your split output path
        "mappings": [
          { "name": "chunkId",           "source": "/document/chunks/*/id" },     // if you create an id per chunk
          { "name": "content",           "source": "/document/chunks/*/text" },   // chunk text
          { "name": "parentId",          "source": "/document/id" },              // parent doc id
          { "name": "UserIds",  "source": "/document/metadata_user_ids" },
          { "name": "GroupIds",  "source": "/document/metadata_group_ids" },
          { "name": "SharePointSiteUrl", "source": "/document/metadata_spo_site_url" } // include when the index has sharePointConnectorAppRegistration (SharePoint groups support)
        ]
      }
    ],
    "parameters": {
      "projectionMode": "skipIndexingParentDocuments"
    }
  }
}

UserIds、GroupIds、および SharePointSiteUrl マッピングは、SharePoint インデクサー (/document/metadata_*) によって出力されたソース レベルのメタデータを読み取り、各チャンクに値を書き込みます。

4. ACL のインデクサー フィールド マッピングを構成する

インデクサー フィールド マッピングは、インデクサーがソース アイテムごとに 1 つのドキュメントを書き込む場合 (チャンクなし)、またはチャンク インデックスと共に別の親インデックスを保持する場合に使用します。 スキルセットが projectionMode: skipIndexingParentDocuments を使用してドキュメントを単一のターゲット インデックスにチャンク化する場合、ここに示すフィールド マッピングは、チャンク インデックスについては前の手順の indexProjections.mappings によって置き換えられます。

必要な indexer 構成に加えて、SharePointの生のメタデータ ACL フィールドをインデックスフィールドにマッピングしてください。

{
  "fieldMappings": [
    { "sourceFieldName": "metadata_user_ids",  "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids", "targetFieldName": "GroupIds" }
  ]
}

5. インデクサーを実行する

ACL メタデータは、インデクサーの実行時に取り込まれます。 インデクサーを作成または更新した後 ( 「手順 6: インデクサーを作成する」を参照)、インデクサーがコンテンツと共に ACL を取り込むよう実行をトリガーします。

POST https://[service name].search.windows.net/indexers/[indexer-name]/run?api-version=2026-08-01-preview
api-key: [admin key]

既にアイテムのインデックスが作成されている既存のインデクサーで ACL インジェストを有効にした場合は、/resyncを使用してoptions: ["permissions"]を呼び出してそれらの項目の ACL をバックフィルするか、特定の項目を再抽出/resetdocsします。

6.ACL インジェストを確認する

ACL 値が正しく設定されていることを確認するには:

1. インデックス定義で、retrievable と true の UserIds を一時的に GroupIds に設定してください。 retrievableを変更する場合、インデックスの再構築は必要ありません。
2. 昇格読み取りクエリを実行してUserIdsとGroupIdsを選択し、各コレクションが空でないことを確認します。 チャンク化されたシナリオでは、各チャンクに両方のフィールドが含まれていることを確認してください。
3. 検証後に retrievable を false に戻します。

SharePoint グループのサポートを構成する

2026-05-01-preview REST API 以降、SharePoint インデクサーはサイト グループ メンバーシップ (所有者、メンバー、訪問者、カスタム サイト グループ) SharePoint取り込むことができます。 クエリ時にこれらのグループが優先されます。 SharePoint グループ ID は、Microsoft Entra グループ オブジェクト ID と区別するために、metadata_group_ids プレフィックス付きで spg: フィールドに出力されます。

このチュートリアルはこの手順内で完結しています。手順を順に実行して、インデックスとインデクサーのフィールド マッピングを構成し、SharePoint サイト グループの適用を使用してインデックスに対してクエリを実行します。

次のコンポーネントが連携して、SharePoint サイト グループの解決を可能にします。

1.前提条件

• SharePointインデクサーは、ACL インジェスト用に既に構成されています。 ACL のインデクサー フィールド マッピングの構成を参照してください。
• フェデレーション ID 資格情報を使用した Microsoft Entra のアプリ登録。 マネージド ID を使用した登録済みアプリケーションの構成を参照してください。
• REST API 2026-05-01-preview 以降。

2. インデックスを構成する

sharePointConnectorAppRegistration構成とSharePointSiteUrl フィールドをUserIdsフィールドとGroupIdsアクセス許可フィルター フィールドと共に追加して、完全なインデックス図形を 1 か所に配置します。 permissionFilterOption: "enabled"を維持します。

PUT https://{service}.search.windows.net/indexes/{index}?api-version=2026-08-01-preview
{
  "name": "my-sharepoint-acl-index",
  "sharePointConnectorAppRegistration": {
      "applicationId": "<ingestion-app-client-id>",
      "federatedCredentialId": "<managed-identity-application-id>",
     "tenantId": "<sharepoint-tenant-id>"
  },
  "fields": [
    { "name": "UserIds",           "type": "Collection(Edm.String)", "permissionFilter": "userIds",  "filterable": true, "retrievable": false },
    { "name": "GroupIds",          "type": "Collection(Edm.String)", "permissionFilter": "groupIds", "filterable": true, "retrievable": false },
    { "name": "SharePointSiteUrl", "type": "Edm.String", "sharepointSiteUrl": true, "filterable": false, "retrievable": false }
  ],
  "permissionFilterOption": "enabled"
}

3. インデクサー フィールド マッピングを構成する

SharePointメタデータ フィールドを、1 つの結合されたマッピング ブロック内のインデックス フィールドにマップします。 最初の 2 つのマッピングは、標準 ACL インジェストに使用されるマッピングと同じです。3 番目のマッピングでは、SharePointグループの解決がアクティブになります。

{
  "fieldMappings": [
    { "sourceFieldName": "metadata_user_ids",             "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids",            "targetFieldName": "GroupIds" },
    { "sourceFieldName": "metadata_spo_site_url",  "targetFieldName": "SharePointSiteUrl" }
  ]
}

スキルセットがドキュメントをチャンクに分割する場合は（たとえば、統合ベクトル化のために Text Split スキルを使用して）、代わりに SharePointSiteUrl を通じて indexProjections.mappings を各チャンクに投影します。 ACL フィールドを設定する場所の選択を参照してください。

4. インデックスのクエリを実行する

クライアント側の変更は必要ありません。 同じx-ms-query-source-authorization トークンは、Microsoft EntraとSharePointサイト グループの両方の適用をアクティブにします。 検索サービスは、インデックス上の sharePointConnectorAppRegistration を使用して、SharePoint グループのメンバーシップをサーバー側で解決します。

要求の形状については、general クエリの例およびSharePoint固有のサンプルとSharePointサイト グループの適用を参照してください。

5. 確認する

SharePoint グループ ID がインデックスに取り込まれていることを確認するには、elevated-read クエリを実行して GroupIds を選択し、応答で spg: で始まる値を探します。

インデックス付きコンテンツとソース コンテンツの間でアクセス許可を同期する

2026-05-01-preview REST API 以降では、インデクサーの実行が成功するたびに、一意のアクセス許可を持つ項目の ACL の変更が検出され、更新されます。 インデクサーはSharePoint変更トークンを使用して、コンテンツの変更を取得するのと同じ方法で、ロールの割り当ての追加と削除を段階的に取得します。

一部のシナリオでは、引き続き明示的な更新が必要です。

特定のドキュメントをリセットする

特定の ドキュメントをリセット して、コンテンツと ACL を完全に再び取り込むことができます。

POST https://{service}.search.windows.net/indexers/{indexer}/resetdocs?api-version=2026-08-01-preview
{
  "documentKeys": ["doc123", "doc456"]
}

完全なデータ ソース間で ACL を再同期する

最初のインジェスト後 に、完全なデータ セット ACL コンテンツを再同期 できます。 この操作を完全に成功させるには、完了後に インデクサーを実行 する必要があります。

POST https://{service}.search.windows.net/indexers/{indexer}/resync?api-version=2026-08-01-preview
{
  "options": ["permissions"]
}

データと ACL のインデックスを作成した後、 インデックスに対してクエリを実行できます。

Troubleshooting

ACL メタデータのインデックスが作成された後にクエリ時間の結果が見つからない、予期しない、または失敗した場合は、「SharePointアクセス許可のフィルター処理のトラブルシューティング」を参照してください。

関連コンテンツ

• SharePoint コンテンツを Azure AI 検索 (プレビュー) にインデックス化します
• クエリ時間 ACL の適用