Spec-Zone.ru › Elasticsearch 8
›Elasticsearch Guide [8.17] ›Интегрирование контента с помощью соединителей Elasticsearch ›Справочник по соединителям

Справочник по соединителю Elastic GraphQL

Подключатель Elastic GraphQL написан на Python с использованием фреймворка подключения Elastic. Просмотрите исходный код этого подключателя.

Доступность и предварительные требования

Этот подключатель был представлен в Elastic 8.14.0 и доступен как самоуправляемый самоуправляемый подключатель.

Для использования этого подключателя выполните все предварительные требования к самоуправляемым подключателям. Важно, что вы должны развернуть службу подключателей на собственной инфраструктуре. У вас есть два варианта развертывания:

  • Запуск службы подключателей из исходного кода. Используйте этот вариант, если вы чувствуете себя комфортно с Python и хотите быстро итерировать локально.
  • Запуск службы подключателей в Docker. Используйте этот вариант, если вы хотите развернуть подключатели на сервере или использовать платформу оркестрации контейнеров.

Этот подключатель находится в техническом предварительном просмотре и может быть изменён. Дизайн и код менее зрелые, чем официальные функции GA, и предоставляются как есть без гарантий. Функции технического предварительного просмотра не подпадают под SLA поддержки официальных функций GA.

Использование

Чтобы настроить этот подключатель в интерфейсе, выберите плитку GraphQL при создании нового подключателя в Поиск → Подключатели.

Если вы уже знакомы с принципом работы подключателей, вы также можете использовать API подключателей.

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

Развертывание с Docker

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

Шаг 1: Загрузка файла образца конфигурации

Загрузите файл образца конфигурации. Вы можете загрузить его вручную или выполнить следующую команду:

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

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

Шаг 2: Обновление файла конфигурации для вашего самоуправляемого подключателя

Обновите файл конфигурации следующими настройками, чтобы соответствовать вашей среде:

  • elasticsearch.host
  • elasticsearch.api_key
  • connectors

Если вы запускаете службу подключателя по отношению к контейнеризированной версии Elasticsearch и Kibana, ваш файл конфигурации будет выглядеть так:

# 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: graphql
    api_key: <CONNECTOR_API_KEY_FROM_KIBANA> # Optional. If not provided, the connector will use the elasticsearch.api_key instead

Использование elasticsearch.api_key является рекомендуемым методом аутентификации. Однако вы также можете использовать elasticsearch.username и elasticsearch.password для аутентификации с вашим экземпляром Elasticsearch.

Примечание: Вы можете изменить другие значения по умолчанию, просто раскомментировав определённые настройки в файле конфигурации и изменив их значения.

Шаг 3: Запуск Docker-изображения

Запустите Docker-изображение со службой подключателей с помощью следующей команды:

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-изображения в официальном репозитории.

У нас также есть быстрый самоуправляемый вариант с использованием Docker Compose, поэтому вы можете сразу запустить все необходимые службы: Elasticsearch, Kibana и службу подключателей. Дополнительную информацию см. в README в репозитории elastic/connectors.

Конфигурация

Настройка подключателя GraphQL

Обратите внимание на следующие поля конфигурации:

http_endpoint (обязательно)
Базовый URL GraphQL-точки входа. Пример: https://api.xyz.com/graphql
http_method (обязательно)
GET или POST.
authentication_method(обязательно)
Выберите из No Auth, Basic Auth и Bearer Token.
username
Требуется при использовании аутентификации по основанию.
password
Требуется при использовании аутентификации по основанию.
token
Требуется при использовании аутентификации с токеном доступа.
graphql_query (обязательно)

Запрос для извлечения данных из источника. Может содержать переменные, предоставленные в поле graphql_variables. Подключатель подставит переменные в запросе значениями из graphql_variables и выполнит GraphQL-запрос к источнику.

Пример:

query getUser($id: ID!) {
    user(id: $id) {
        name
        email
    }
}
graphql_variables

JSON-объект пар ключ-значение, содержащий переменные, используемые в GraphQL-запросе. Подключатель подставит переменные в запросе значениями, предоставленными здесь, и выполнит GraphQL-запрос к источнику.

Пример:

Для GraphQL-запроса query getUser($id: ID!) { user(id: $id) { name } }

  • Где значение graphql_variables равно {"id": "123"}
  • Подключатель выполнит query getUser { user(id: "123") { name } }, чтобы получить данные из источника
graphql_object_to_id_map (обязательно)

JSON-отображение между объектами GraphQL-ответа и полями ID индекса. Подключатель извлечёт данные для каждого объекта (JSON-ключа) и использует предоставленное поле ID (JSON-значение), чтобы индексировать объект в Elasticsearch. Подключатель проиндексирует все поля для каждого объекта, указанные в отображении. Используйте нотацию (.) для указания полного пути от корня GraphQL-ответа до желаемого объекта.

Пример:

GraphQL-запрос query getUser { organization { users{ user_id name email} } } получает всех доступных пользователей из источника. Для индексации каждого пользователя как отдельного документа настройте это поле следующим образом.

{
    "organization.users": "user_id"
}

В этом примере user_id уникален для каждого документа пользователя. Поэтому мы устанавливаем user_id в качестве значения для organization.users.

Путь, указанный в этом поле, должен содержать только JSON-объекты, а не списки.

headers

JSON-объект, содержащий пользовательские заголовки, которые будут отправляться с каждым GraphQL-запросом:

{
    "content-type": "Application/json"
}
pagination_model (обязательно)

Это поле определяет модель пагинации, которая будет использоваться подключателем. Подключатель поддерживает No pagination и Cursor-based pagination модели пагинации.

Для пагинации на основе указателя добавьте pageInfo {endCursor hasNextPage} и переменную аргумента after в ваш запрос в нужном узле (Pagination key). Используйте аргумент запроса after с переменной для перебора страниц. Значение по умолчанию для этого поля — No pagination. Пример:

Для Cursor-based pagination запрос должен выглядеть так:

query getUsers($cursor: String!) {
    sampleData {
        users(after: $cursor) {
            pageInfo {
                endCursor
                hasNextPage
            }
            nodes {
                first_name
                last_name
                address
            }
        }
    }
}

Значение pagination_key равно sampleData.users, поэтому оно должно содержать:

  • pageInfo {endCursor hasNextPage}
  • аргумент after с переменной при использовании пагинации на основе указателя
pagination_key (обязательно)

Указывает, какой GraphQL-объект используется для пагинации. Используйте . для указания полного пути объекта от корня ответа.

Пример:

  • organization.users
connection_timeout
Указывает максимальное время в секундах ожидания ответа от GraphQL-источника. Значение по умолчанию — 30 секунд.

Документы и синхронизации

Подключатель синхронизирует объекты и сущности на основе GraphQL-запроса и списка GraphQL-объектов.

Типы синхронизации

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

Этот подключатель в настоящее время не поддерживает инкрементные синхронизации.

Правила синхронизации

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

Расширенные правила синхронизации

Расширенные правила синхронизации недоступны для этого подключателя в текущей версии.

Операции клиента подключателя

Конечные интеграционные тесты

Фреймворк коннекторов позволяет операторам запускать функциональные тесты на реальном источнике данных, используя Docker Compose. Вам не нужен запущенный экземпляр Elasticsearch или источник GraphQL для запуска этого теста.

Обратитесь к тестированию коннекторов для получения более подробной информации.

Для выполнения конечных интеграционных тестов для коннектора GraphQL выполните следующую команду:

$ make ftest NAME=graphql

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

make ftest NAME=graphql DATA_SIZE=small

По умолчанию, DATA_SIZE=MEDIUM.

Известные проблемы

  • Каждый документ будет обновлен при каждом синхронизации.
  • Если имя одного и того же поля существует с различными типами в разных объектах, коннектор может выдать исключение анализаера маппинга.

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

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

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

Безопасность

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

© 2023-2025 Elasticsearch
As of September 2024, Elasticsearch is available under a choice of three licenses: the Server Side Public License (SSPL), the Elastic License, or the AGPLv3 (OSI approved).
Elasticsearch and the Elasticsearch logo are trademarks of Elasticsearch B.V., registered in the U.S. and in other countries.
https://www.elastic.co/guide/en/elasticsearch/reference/8.17/es-connectors-graphql.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API