Справочник по коннектору Elastic для SharePoint Online

Этот коннектор доступен в качестве управляемого коннектора в версиях Elastic, начиная с 8.9.0 и выше. Чтобы использовать этот коннектор напрямую в Elastic Cloud, выполните все требования к управляемым коннекторам.

Чтобы использовать этот коннектор в качестве управляемого коннектора, см. управляемые коннекторы Elastic.

Для дополнительных операций см. Интерфейс коннекторов в Kibana.

Прежде чем вы сможете настроить коннектор, необходимо создать приложение OAuth в платформе SharePoint Online. Ваш коннектор будет аутентифицироваться в SharePoint как зарегистрированное приложение/клиент OAuth. В процессе вы получите значения (client ID, tenant ID и client secret), которые вам понадобятся для этапа настройки в Kibana.

Для начала войдите в SharePoint Online и перейдите в панель администратора. Убедитесь, что вы вошли в систему как учетная запись Azure Portal службы.

Выполните следующие действия:

Microsoft прекращает поддержку Azure Access Control Service (ACS). Это затрагивает конфигурацию разрешений:

Этот метод аутентификации не требует дополнительной настройки, кроме создания и загрузки сертификатов в приложение OAuth.

Обратитесь к следующей документации для настройки разрешений SharePoint.

Для настройки разрешений Sites.Selected выполните следующие действия в портале Azure Active Directory. Эти разрешения обеспечивают точный контроль доступа к определенным сайтам SharePoint.

Для назначения доступа к определенным сайтам SharePoint с использованием Sites.Selected:

Этот коннектор совместим с SharePoint Online.

Используйте следующие поля конфигурации для настройки коннектора:

Коннектор синхронизирует следующие типы объектов SharePoint:

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

В этом разделе описаны расширенные правила синхронизации для этого коннектора. Расширенные правила синхронизации определяются через JSON-фрагмент DSL, специфичный для источника.

Расширенные правила для коннектора SharePoint Online позволяют вам избежать извлечения и синхронизации устаревших данных, которые могут быть не актуальны для поиска.

Пример:

{
	"skipExtractingDriveItemsOlderThan": 60
}

Это правило не будет извлекать содержимое элементов хранилища (файлы в библиотеках документов), которые не изменялись в течение 60 дней или более.

Ограничения правил синхронизации с инкрементными синхронизациями

Изменение правил синхронизации после того, как содержимое SharePoint Online уже было проиндексировано, может привести к непредсказуемым результатам при использовании инкрементных синхронизаций.

Инкрементные синхронизации обеспечивают обновления из сторонней системы, но не изменяют существующие документы в индексе.

Для предотвращения этих проблем выполните полную синхронизацию после изменения правил синхронизации (базовые или расширенные).

Давайте рассмотрим несколько примеров, где инкрементные синхронизации могут привести к несогласованным данным в вашем индексе.

Пример: добавлено ограниченное базовое правило синхронизации после полной синхронизации

Представьте, что ваше хранилище SharePoint Online содержит следующие элементы хранилища:

/Documents/Report.doc
/Documents/Spreadsheet.xls
/Presentations/Q4-2020-Report.pdf
/Presentations/Q4-2020-Report-Data.xls
/Personal/Documents/Sales.xls

После синхронизации все эти элементы хранилища будут сохранены в вашем индексе Elasticsearch. Давайте добавим базовое правило синхронизации, фильтрующее файлы по их пути:

Exclude WHERE path CONTAINS "Documents"

Эти правила фильтрации исключат все файлы с «Документы» в их пути, оставив только файлы в директории /Presentations:

/Presentations/Q4-2020-Report.pdf
/Presentations/Q4-2020-Report-Data.xls

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

После полной синхронизации индекс будет обновлен, и файлы, исключенные правилами синхронизации, будут удалены.

Пример: удаление ограничительных базовых правил синхронизации после полной синхронизации

Представьте, что в SharePoint Online есть следующие элементы каталога:

/Documents/Report.doc
/Documents/Spreadsheet.xls
/Presentations/Q4-2020-Report.pdf
/Presentations/Q4-2020-Report-Data.xls
/Personal/Documents/Sales.xls

Перед выполнением синхронизации мы добавляем ограничительное базовое правило фильтрации:

Exclude WHERE path CONTAINS "Documents"

После полной синхронизации индекс будет содержать только файлы в каталоге /Presentations:

/Presentations/Q4-2020-Report.pdf
/Presentations/Q4-2020-Report-Data.xls

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

Пример: особый случай правил синхронизации расширенного типа

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

Однако существует особый случай. Представьте документ, которому 179 дней, и его содержимое извлечено и индексировано в Elasticsearch. Через 2 дня этому документу будет 181 день. Поскольку этот документ уже был обработан, он не будет изменён. Поэтому содержимое не будет удалено из индекса после инкрементальной синхронизации.

В этой ситуации, если вы хотите, чтобы старые документы были удалены, вам необходимо вручную очистить индекс. Например, вы можете вручную запустить запрос Elasticsearch, который удаляет содержимое элементов каталога, которым более 180 дней:

resp = client.update_by_query(
    index="INDEX_NAME",
    conflicts="proceed",
    query={
        "bool": {
            "filter": [
                {
                    "match": {
                        "object_type": "drive_item"
                    }
                },
                {
                    "exists": {
                        "field": "file"
                    }
                },
                {
                    "range": {
                        "lastModifiedDateTime": {
                            "lte": "now-180d"
                        }
                    }
                }
            ]
        }
    },
    script={
        "source": "ctx._source.body = ''",
        "lang": "painless"
    },
)
print(resp)

const response = await client.updateByQuery({
  index: "INDEX_NAME",
  conflicts: "proceed",
  query: {
    bool: {
      filter: [
        {
          match: {
            object_type: "drive_item",
          },
        },
        {
          exists: {
            field: "file",
          },
        },
        {
          range: {
            lastModifiedDateTime: {
              lte: "now-180d",
            },
          },
        },
      ],
    },
  },
  script: {
    source: "ctx._source.body = ''",
    lang: "painless",
  },
});
console.log(response);

POST INDEX_NAME/_update_by_query?conflicts=proceed
{
  "query": {
    "bool": {
      "filter": [
        {
          "match": {
            "object_type": "drive_item"
          }
        },
        {
          "exists": {
            "field": "file"
          }
        },
        {
          "range": {
            "lastModifiedDateTime": {
              "lte": "now-180d"
            }
          }
        }
      ]
    }
  },
  "script": {
    "source": "ctx._source.body = ''",
    "lang": "painless"
  }
}

Безопасность на уровне документа (DLS) позволяет ограничить доступ к документам на основе разрешений пользователя. Эта функция доступна по умолчанию для этого коннектора.

Обратитесь к настройкам на этой странице, чтобы узнать, как включить DLS для этого коннектора.

Служба извлечения содержимого по умолчанию работает на основе стандартной конвейерной линии обработки в Enterprise Search. (См. Конвейерные линии обработки для индексов поиска.)

См. Извлечение содержимого.

Самостоятельный коннектор SharePoint Online поддерживает извлечение содержимого больших файлов (> 100 МБ). Это требует:

Дополнительную информацию см. в разделе о локальном извлечении содержимого.

Список известных проблем всех коннекторов см. в разделе о известных проблемах.

См. Устранение неполадок.

См. Безопасность.

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

Чтобы использовать этот соединитель как самоуправляемый соединитель, см. Самоуправляемые соединители. Дополнительные операции см. в Интерфейсе соединителей в Kibana.

Прежде чем вы сможете настроить соединитель, необходимо создать приложение OAuth в платформе SharePoint Online. Ваш соединитель будет аутентифицироваться в SharePoint как зарегистрированное приложение/клиент OAuth. Во время этого процесса вы получите значения (client ID, tenant ID и client secret), которые понадобятся для этапа настройки в Kibana.

Для начала войдите в SharePoint Online и перейдите в свой административный щит. Убедитесь, что вы вошли как учетная запись Azure Portal службы.

Выполните следующие действия:

Microsoft снял с поддержки Azure Access Control Service (ACS). Это влияет на конфигурацию разрешений: * Арендаторы, созданные после 1 ноября 2024 года: Требуется аутентификация по сертификату * Арендаторы, созданные до 1 ноября 2024 года: Аутентификация на основе секретов должна быть переведена на аутентификацию по сертификату к 2 апреля 2026 года

Для этого метода аутентификации не требуется дополнительная настройка, кроме создания и загрузки сертификатов в приложение OAuth.

Для настройки разрешений SharePoint обратитесь к следующей документации.

Чтобы настроить разрешения Sites.Selected, выполните следующие действия в портале Azure Active Directory. Эти разрешения обеспечивают точный контроль доступа к определенным сайтам SharePoint.

Чтобы назначить доступ к определенным сайтам SharePoint с помощью Sites.Selected:

Этот коннектор совместим с SharePoint Online.

Используйте следующие поля конфигурации для настройки коннектора:

Вы можете развернуть коннектор SharePoint Online как коннектор собственной разработки с помощью Docker. Следуйте этим инструкциям.

curl https://raw.githubusercontent.com/elastic/connectors/main/config.yml.example --output ~/connectors-config/config.yml

# When connecting to your cloud deployment you should edit the host value
elasticsearch.host: http://host.docker.internal:9200
elasticsearch.api_key: <ELASTICSEARCH_API_KEY>

connectors:
  -
    connector_id: <CONNECTOR_ID_FROM_KIBANA>
    service_type: sharepoint_online
    api_key: <CONNECTOR_API_KEY_FROM_KIBANA> # Optional. If not provided, the connector will use the elasticsearch.api_key instead

docker run \
-v ~/connectors-config:/config \
--network "elastic" \
--tty \
--rm \
docker.elastic.co/enterprise-search/elastic-connectors:8.17.3 \
/app/bin/elastic-ingest \
-c /config/config.yml

Обратитесь к DOCKER.md в репозитории elastic/connectors для получения более подробной информации.

Найдите все доступные Docker-изображения в официальном репозитории.

Коннектор синхронизирует следующие типы объектов SharePoint:

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

В этом разделе описаны расширенные правила синхронизации для этого подключения. Расширенные правила синхронизации определяются с помощью JSON-фрагмента DSL, специфичного для источника.

Расширенные правила для подключения к SharePoint Online позволяют избежать извлечения и синхронизации устаревших данных, которые могут быть больше не актуальны для поиска.

Пример:

{
	"skipExtractingDriveItemsOlderThan": 60
}

Это правило не будет извлекать содержимое элементов хранилища (файлов в библиотеках документов), которые не изменялись в течение 60 дней или более.

Ограничения правил синхронизации с инкрементальными синхронизациями

Изменение правил синхронизации после индексации контента SharePoint Online может привести к непредвиденным результатам при использовании инкрементальных синхронизаций.

Инкрементальные синхронизации гарантируют обновления из сторонней системы, но не изменяют существующие документы в индексе.

Чтобы избежать этих проблем, выполните полную синхронизацию после изменения правил синхронизации (основных или расширенных).

Давайте рассмотрим несколько примеров, где инкрементальные синхронизации могут привести к несогласованным данным в вашем индексе.

Пример: Добавление ограниченного основного правила синхронизации после полной синхронизации

Представьте, что хранилище SharePoint Online содержит следующие элементы хранилища:

/Documents/Report.doc
/Documents/Spreadsheet.xls
/Presentations/Q4-2020-Report.pdf
/Presentations/Q4-2020-Report-Data.xls
/Personal/Documents/Sales.xls

После синхронизации все эти элементы хранилища будут сохранены в вашем индексе Elasticsearch. Давайте добавим основное правило синхронизации, фильтрующее файлы по пути:

Exclude WHERE path CONTAINS "Documents"

Эти правила фильтрации исключат все файлы с "Documents" в пути, оставив только файлы в каталоге /Presentations:

/Presentations/Q4-2020-Report.pdf
/Presentations/Q4-2020-Report-Data.xls

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

После полной синхронизации индекс будет обновлен, и файлы, исключенные правилами синхронизации, будут удалены.

Пример: Удаление ограниченных основных правил синхронизации после полной синхронизации

Представьте, что хранилище SharePoint Online имеет следующие элементы хранилища:

/Documents/Report.doc
/Documents/Spreadsheet.xls
/Presentations/Q4-2020-Report.pdf
/Presentations/Q4-2020-Report-Data.xls
/Personal/Documents/Sales.xls

Перед выполнением синхронизации добавим ограниченное основное правило фильтрации:

Exclude WHERE path CONTAINS "Documents"

После полной синхронизации в индексе останутся только файлы в каталоге /Presentations:

/Presentations/Q4-2020-Report.pdf
/Presentations/Q4-2020-Report-Data.xls

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

Пример: Специальный случай с расширенными правилами синхронизации

Расширенные правила синхронизации могут применяться для ограничения документов, для которых будет извлечено содержимое. Например, можно установить правило, чтобы документы старше 180 дней не извлекали содержимое.

Однако есть особый случай. Представьте документ, которому 179 дней, и его содержимое извлечено и индексировано в Elasticsearch. Через 2 дня этому документу будет 181 день. Поскольку этот документ уже был импортирован, он не будет изменён. Поэтому содержимое не будет удалено из индекса после инкрементальной синхронизации.

В этой ситуации, если вы хотите удалить старые документы, вам нужно будет вручную очистить индекс. Например, вы можете вручную запустить запрос Elasticsearch, удаляющий содержимое элементов хранилища старше 180 дней:

resp = client.update_by_query(
    index="INDEX_NAME",
    conflicts="proceed",
    query={
        "bool": {
            "filter": [
                {
                    "match": {
                        "object_type": "drive_item"
                    }
                },
                {
                    "exists": {
                        "field": "file"
                    }
                },
                {
                    "range": {
                        "lastModifiedDateTime": {
                            "lte": "now-180d"
                        }
                    }
                }
            ]
        }
    },
    script={
        "source": "ctx._source.body = ''",
        "lang": "painless"
    },
)
print(resp)

const response = await client.updateByQuery({
  index: "INDEX_NAME",
  conflicts: "proceed",
  query: {
    bool: {
      filter: [
        {
          match: {
            object_type: "drive_item",
          },
        },
        {
          exists: {
            field: "file",
          },
        },
        {
          range: {
            lastModifiedDateTime: {
              lte: "now-180d",
            },
          },
        },
      ],
    },
  },
  script: {
    source: "ctx._source.body = ''",
    lang: "painless",
  },
});
console.log(response);

POST INDEX_NAME/_update_by_query?conflicts=proceed
{
  "query": {
    "bool": {
      "filter": [
        {
          "match": {
            "object_type": "drive_item"
          }
        },
        {
          "exists": {
            "field": "file"
          }
        },
        {
          "range": {
            "lastModifiedDateTime": {
              "lte": "now-180d"
            }
          }
        }
      ]
    }
  },
  "script": {
    "source": "ctx._source.body = ''",
    "lang": "painless"
  }
}

Безопасность на уровне документов (DLS) позволяет ограничивать доступ к документам на основе разрешений пользователя. Эта функция доступна по умолчанию для этого подключения.

См. настройки на этой странице, чтобы узнать, как включить DLS для этого подключения.

Служба извлечения контента по умолчанию основана на стандартной конвейерной линии импорта Enterprise Search. (См. Конвейеры импорта для индексов поиска.)

См. Извлечение контента.

Самостоятельное подключение SharePoint Online поддерживает извлечение контента больших файлов (> 100 МБ). Для этого необходимо:

Дополнительную информацию см. в разделе локального извлечения контента.

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

Для выполнения E2E-тестирования для подключения SharePoint Online выполните следующую команду:

$ make ftest NAME=sharepoint_online

Для более быстрых тестов добавьте флаг DATA_SIZE=small:

make ftest NAME=sharepoint_online DATA_SIZE=small

Обратитесь к Известным проблемам для получения списка известных проблем всех соединителей.

См. Устранение неполадок.

См. Безопасность.