Использование индексатора SharePoint для приема метаданных разрешений и фильтрации результатов поиска на основе прав доступа пользователей (предварительная версия)

При приеме метаданных разрешений SharePoint (предварительная версия) используется индексатор Поиск с использованием ИИ Azure для сохранения метаданных разрешений, таких как списки управления доступом (ACL), наряду с другим содержимым из SharePoint в Microsoft 365. Индексатор сохраняет разрешения в виде метаданных для каждого индексированного документа. Во время запроса пользователи получают только документы, к которых у них есть разрешение на доступ.

Необходимые условия

• Поиск с использованием ИИ Azure на оплачиваемом уровне (базовый или выше) в любом регионе.

• SharePoint в Microsoft 365 сайтах, библиотеках, папках и файлах с настроенными разрешениями.

• Выполните все действия по настройке в документации по индексатору SharePoint, применяя требования для ACL, описанные в этой статье.

• Настройте Microsoft Entra разрешения приложения и учетные данные, соответствующие вашему сценарию. См. сценарий «Права доступа по ACL». Прием ACL требует разрешений приложения. Делегированные разрешения не поддерживаются. Сведения о выборе между разрешениями приложения и делегированными разрешениями см. в разделе Выбор конфигурации разрешений.

• REST API версии 2026-08-01-preview или эквивалентный пакет sdk для предварительной версии.

Ограничения

• Для инкрементальных обновлений ACL требуется REST API версии 2026-05-01-preview или более поздней. В предыдущих предварительных версиях API система фиксирует ACL только при первой загрузке каждого элемента. Последующие изменения разрешений требуют явного переиндексирования. Инструкции по миграции см. в разделе "Синхронизация разрешений" между индексированных и исходным содержимым.

• Изменения разрешений в родительской области видимости не учитываются автоматически при последующих запусках индексатора. Параметры обновления см. в разделе "Синхронизация разрешений" между индексированных и исходным содержимым.

• Портал Azure не поддерживает эту функцию.

• В этой предварительной версии не поддерживаются следующие функции:

  • политики SharePoint Information Management применимы к доступу пользователей. Система не оценивает, не обрабатывает и не учитывает эти политики во время выполнения запроса.

  • Ссылки, доступные для совместного использования, могут быть настроены для "Любых пользователей" или "Людей в вашей организации". Поддерживаются только ссылки, настроенные для "Определенных людей".

  • Группы SharePoint (например, группы Owners, Members и Visitors) поддерживаются начиная с версии REST API 2026-05-01-preview. См. раздел Настройка поддержки групп SharePoint. В более ранних предварительных версиях API поддерживаются только группы SharePoint, которые сопоставляются с группами Microsoft Entra.

• Следующие функции индексатора не поддерживают наследование разрешений в индексированных документах, исходящих из SharePoint. Если вы используете какие-либо из этих функций в наборе навыков или индексаторе, разрешения на уровне документа не включаются в индексированное содержимое.

  • Навык пользовательского веб-API

  • Хранилище знаний, включая хранилище ресурсов, необходимое для обслуживания изображений (предварительная версия) в агентическом извлечении. Поэтому выдача изображений не поддерживается для источников знаний, которые используют ACL SharePoint.

  • Кэш обогащения индексатора

  • Сеансы отладки

Поддержка модели разрешений SharePoint

Эта предварительная версия поддерживает базовые списки управления доступом для документов, элементов списка и современных страниц сайта ASPX.

Поддерживаемые отношения между группами

Транзитивность групп в Microsoft Entra действует в пределах Microsoft Entra. Он не расширяет Microsoft Entra группы, которые являются членами групп SharePoint.

Как оцениваются иерархические разрешения

Разрешения в SharePoint наследуются в иерархии Сайт → Библиотека → Папка → Файл, если наследование не нарушено.

Во время обработки индексатор собирает идентификаторы пользователей и групп (ID) на каждом уровне и вычисляет действующий список управления доступом (ACL) для каждого файла.

Разрешения по сценарию ACL

Разрешения приложения Microsoft Entra и тип учетных данных, необходимые для приема списков управления доступом (ACL), зависят от того, какие типы элементов и групп вы индексируете. При регистрации приложения все разрешения добавляются в разделе ">Разрешения API", а федеративные учетные данные добавляются в разделе "Сертификаты и секреты>федеративных учетных данных". Пошаговые инструкции и снимки экрана см. в разделах Шаг 3: Создание регистрации приложения Microsoft Entra и Настройка зарегистрированного приложения с управляемой идентификацией.

Федеративные учетные данные используются для аутентификации приложения с помощью доверенной управляемой идентичности вместо клиентского секрета. Те же федеративные учетные данные используются как для приема данных (индексатором), так и для оценки групп сайтов SharePoint во время выполнения запроса. Инструкции по настройке см. в разделе "Настройка зарегистрированного приложения с помощью управляемого удостоверения".

Перед включением приема данных ACL

Выполните следующие действия в зарегистрированном приложении Microsoft Entra:

1. Определите сценарий в предыдущей таблице на основе того, что планируется индексировать (файлы библиотек документов, элементы списка, страницы сайта ASPX) и следует ли учитывать группы сайтов SharePoint.
2. Откройте регистрацию приложения в Центр администрирования Microsoft Entra и перейдите к разрешениям API>Add a permission.
3. Добавьте разрешения Microsoft Graph, перечисленные в вашем сценарии. Предоставьте согласие администратора.
4. Если для сценария также требуются разрешения SharePoint, выберите Add a permission еще раз, выберите API SharePoint и добавьте Sites.FullControl.All (или Sites.Selected). Предоставьте согласие администратора.
5. Настройте учетные данные:
   • Для сценариев, использующих только Microsoft Graph, можно использовать либо секрет клиента (Certificates & secrets>Client secrets), либо федеративные учетные данные.
   • Для любого сценария, включающего разрешения SharePoint, добавьте учетные данные федерации в раздел Сертификаты и секреты>Учетные данные федерации. См. статью "Настройка зарегистрированного приложения с помощью управляемого удостоверения".
6. Предоставьте приложению доступ к целевым сайтам SharePoint (особенно важно при использовании Sites.Selected для ограниченного доступа), чтобы он смог прочитать содержимое и разрешения, которые требуется индексировать.

Поиск правильных идентификаторов Microsoft Entra

Каждый идентификатор отображается в другом расположении на портале Azure и сопоставляется с определенным полем конфигурации. Используйте этот раздел как справочный материал при настройке загрузки ACL SharePoint с использованием федеративных учетных данных. Эти идентификаторы упоминаются в Настройка поддержки групп SharePoint и в строке подключения источника данных.

Идентификатор приложения федеративных учетных данных

Для FederatedCredentialApplicationId в строке подключения источника данных и federatedCredentialId в определении индекса используйте идентификатор собственного приложения (клиента) управляемой идентификации, а не идентификатор приложения для приема данных.

Системное управляемое удостоверение:

1. Перейдите в службу Поиск с использованием ИИ Azure.
2. Выберите Безопасность и сеть>Идентификация.
3. На вкладке "Назначаемая системой " обратите внимание на идентификатор объекта (субъекта).
4. Перейдите в Microsoft Entra ID>Управление>Корпоративные приложения.
5. Найдите имя службы поиска или вставьте идентификатор объекта (субъекта) в поле поиска.
6. Выберите результат и откройте свойства. Скопируйте идентификатор приложения , показанный здесь, что является значением FederatedCredentialApplicationId в источнике данных и federatedCredentialId в индексе.

Управляемая идентичность, назначаемая пользователем:

1. Перейдите к ресурсу управляемой идентификации, назначенной пользователем.
2. Выберите Параметры>Свойства.
3. Скопируйте идентификатор клиента, который является значением FederatedCredentialApplicationId в источнике данных и federatedCredentialId в индексе.

Настройте службу поиска для приема ACL и применения проверок доступа во время выполнения запросов

Эти шаги настраивают службу поиска для приема ACL и обеспечения их соблюдения во время запросов.

Выбор места для заполнения полей ACL

Где вы сопоставляете поля метаданных ACL, зависит от того, записывает ли индексатор один документ на исходный элемент или несколько блоков на исходный элемент.

Во всех сценариях с разбиением на части каждая часть должна содержать поля ACL. Фильтры прав доступа применяются к каждому документу, поэтому фрагмент без полей ACL не может быть возвращён правильному вызывающему объекту.

1. Конфигурация источника данных

Этот раздел дополняет базовое руководство Шаг 4: Создание источника данных. Установите в определении источника данных , чтобы разрешить индексирование и из документов SharePoint.

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

2. Добавление полей разрешений в определение индекса

Добавьте поля в определение схемы индекса для хранения списков управления доступом и поддержки фильтрации во время запроса.

{
  "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 во время разработки, чтобы проверить значения. Вы можете изменить свойство retrievable с true на false без необходимости перестроения индекса.

3. Настройка проекций индекса в наборе навыков (если применимо)

Когда разбиение на фрагменты включено, родительский документ не записывается в индекс, когда projectionMode включено skipIndexingParentDocuments. Перенесите метаданные ACL на каждый фрагмент через indexProjections.selectors[].mappings.

Если индексатор использует набор навыков с разбиением данных на фрагменты, например навык Text Split при включении интегрированной векторизации, обязательно сопоставьте свойства 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 (списков контроля доступа)

Используйте сопоставления полей индексатора, когда индексатор записывает один документ для каждого исходного элемента (без разбиения на фрагменты) или если вы поддерживаете отдельный родительский индекс наряду с индексом фрагментов. Если ваш набор навыков разбивает документы на фрагменты в единый целевой индекс с projectionMode: skipIndexingParentDocuments, показанные здесь сопоставления полей заменяются элементом indexProjections.mappings из предыдущего шага для индекса фрагментов.

Помимо требуемой конфигурации индексатора, сопоставьте исходные поля ACL метаданных из SharePoint с полями индекса.

{
  "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

Начиная с REST API версии 2026-05-01-preview, индексатор SharePoint может принимать сведения о членстве в группах сайтов SharePoint («Владельцы», «Участники», «Посетители» и настраиваемые группы сайтов). Он учитывает эти группы при выполнении запроса. Идентификаторы групп SharePoint выводятся в поле metadata_group_ids с префиксом spg:, чтобы отличать их от идентификаторов объектов групп Microsoft Entra.

Это пошаговое руководство содержит всё необходимое: выполните шаги по порядку, чтобы настроить индекс, сопоставления полей индексатора и выполнить запрос к индексу с применением ограничений по группам сайта SharePoint.

Следующие компоненты совместно обеспечивают сопоставление групп сайта SharePoint:

1. Предварительные требования

• SharePoint индексатор уже настроен для приема ACL. См. Настройка сопоставлений полей индексатора для списков управления доступом.
• Регистрация приложения Microsoft Entra с учетными данными федеративной идентификации. См. статью "Настройка зарегистрированного приложения с помощью управляемого удостоверения".
• REST API 2026-05-01-preview или более поздняя версия.

2. Настройка индекса

Добавьте sharePointConnectorAppRegistration конфигурацию и поле SharePointSiteUrl рядом с полями фильтра разрешений UserIds и GroupIds, чтобы полная структура индекса находилась в одном месте. Сохраняйте 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 с полями индекса в одном объединенном блоке сопоставления. Первые два сопоставления — это те же сопоставления, что используются для стандартной загрузки ACL; третье сопоставление активирует разрешение групп SharePoint.

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

Если ваш набор навыков разбивает документы на фрагменты (например, с помощью навыка разделения текста для интегрированной векторизации), вместо этого спроецируйте SharePointSiteUrl на каждый фрагмент с помощью indexProjections.mappings. См. раздел "Выбор места для заполнения полей ACL".

4. Запрос индекса

Никаких изменений на стороне клиента не требуется. Один и тот же токен x-ms-query-source-authorization активирует и Microsoft Entra, и принудительное применение для группы сайтов SharePoint. Служба поиска определяет членство в группах SharePoint на стороне сервера с помощью sharePointConnectorAppRegistration в индексе.

Структуру запроса см. в примере общего запроса и в примере для SharePoint с принудительным применением групп сайта SharePoint.

5. Проверка

Чтобы подтвердить, что идентификаторы групп SharePoint попали в индекс, выполните запрос elevated-read query с выборкой GroupIds и найдите в ответе значения с префиксом spg:.

Синхронизируйте разрешения между индексированным и исходным содержимым.

Начиная с REST API 2026-05-01-preview, изменения ACL для элементов с уникальными разрешениями обнаруживаются и обновляются при каждом успешном запуске индексатора. Индексатор использует маркеры изменений SharePoint, чтобы инкрементно отслеживать добавление и удаление назначений ролей, точно так же, как он отслеживает изменения содержимого.

Для некоторых сценариев по-прежнему требуется явное обновление:

Сброс определенных документов

Вы можете сбросить определенные документы для повторного включения содержимого и списков контроля доступа.

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

Пересинхронизировать списки управления доступом по всему источнику данных

После первичной загрузки можно повторно синхронизировать ACL содержимого полного набора данных. Для полного успеха эта операция требует запуска индексатора после завершения.

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

После индексирования данных и списков управления доступом можно выполнить запрос к индексу.

Troubleshooting

Если после индексации метаданных ACL отсутствуют ожидаемые результаты, появляются неожиданные результаты или возникают сбои при получении результатов во время запроса, см. раздел Устранение неполадок фильтрации разрешений SharePoint.

Связанное содержимое

• Индексировать содержимое SharePoint в Поиск с использованием ИИ Azure (предварительная версия)
• Принудительное применение ACL во время запроса