Настройка сопоставителя GraphQL

Статья
12/09/2023

ОБЛАСТЬ ПРИМЕНЕНИЯ: все уровни Управление API

Настройте сопоставитель для получения или задания данных для поля GraphQL в типе объекта, указанном в схеме GraphQL. Схема должна быть импортирована в Управление API как API GraphQL.

В настоящее время Управление API поддерживает сопоставители, которые могут получить доступ к следующим источникам данных:

Источник данных на основе HTTP (REST или SOAP API)
База данных Cosmos DB
База данных SQL Azure

Полезная информация

Сопоставитель — это ресурс, содержащий определение политики, которое вызывается только при выполнении соответствующего типа объекта и поля в схеме.
Каждый сопоставитель разрешает данные для одного поля. Чтобы разрешить данные для нескольких полей, настройте отдельный сопоставитель для каждого.
Политики сопоставителя область вычисляются после любых inbound политик backend в конвейере выполнения политики. Они не наследуют политики от других область. Дополнительные сведения см. в разделе "Политики" в Управление API.
Политики API-область можно настроить для API GraphQL независимо от политик, область d. Например, добавьте политику validate-graphql-request в inbound область для проверки запроса перед вызовом сопоставителя. Настройте политики API-область на вкладке политик API для API.

Необходимые компоненты

Существующий экземпляр Управления API. Создайте его, если у вас его нет.
Импорт сквозного или искусственного API GraphQL.

Создание сопоставителя

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

Перейдите к экземпляру Управления API на портале Azure.
В меню слева выберите API и имя API GraphQL.
На вкладке "Схема" просмотрите схему поля в типе объекта, в котором требуется настроить сопоставитель.
1. Выберите поле, а затем в левом поле наведите указатель на указатель.
2. Выберите + Добавить сопоставитель.
На странице создания сопоставителя:
1. Обновите свойство Name, если вы хотите, при необходимости введите описание и подтвердите или обновите выбор типа и поля.
2. Выберите источник данных сопоставителя. В этом примере выберите HTTP API.
В редакторе политики сопоставителя обновите http-data-source политику с дочерними элементами для вашего сценария.
1. Обновите необходимый http-request элемент с помощью политик для преобразования операции GraphQL в HTTP-запрос.
2. При необходимости добавьте http-response элемент и добавьте дочерние политики для преобразования HTTP-ответа сопоставителя. http-response Если элемент не указан, ответ возвращается в виде необработанной строки.
3. Нажмите кнопку создания.
Сопоставитель подключен к полю и отображается на вкладке "Сопоставители ".

Управление сопоставителями

Вывод списка и управления сопоставителями для API GraphQL на вкладке "Сопоставители API".

На вкладке "Сопоставители" :

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

Изменение и проверка сопоставителя

При изменении одного сопоставителя откроется страница "Изменить сопоставитель". Вы можете:

Обновите политику сопоставителя и при необходимости источник данных. Изменение источника данных перезаписывает текущую политику сопоставителя.
Измените тип и поле, предназначенные для сопоставителя.
Проверьте и отладите конфигурацию сопоставителя. При изменении политики сопоставителя выберите "Запустить тест", чтобы проверка выходные данные из источника данных, которые можно проверить на соответствие схеме. Если возникают ошибки, ответ содержит сведения об устранении неполадок.

Контекст GraphQL

Контекст запроса и ответа сопоставителя (если указано) отличается от контекста для исходного запроса API шлюза:
- context.GraphQL свойства задаются аргументами (Arguments) и родительским объектом (Parent) для текущего выполнения сопоставителя.
- Контекст запроса содержит аргументы, передаваемые в запрос GraphQL в качестве текста.
- Контекст ответа — это ответ от независимого вызова, сделанного сопоставителями, а не контекста для полного ответа запроса шлюза. Переменная context , передаваемая через конвейер запроса и ответа, дополняется контекстом GraphQL при использовании с сопоставителя GraphQL.

Контексте. GraphQL.parent

В качестве значения context.GraphQL.parent задается родительский объект для текущего выполнения сопоставителя. Рассмотрим следующую частичную схему:

type Comment {
    id: ID!
    owner: string!
    content: string!
}

type Blog {
    id: ID!
    title: string!
    content: string!
    comments: [Comment]!
    comment(id: ID!): Comment
}

type Query {
    getBlog(): [Blog]!
    getBlog(id: ID!): Blog
}

Также рассмотрим запрос GraphQL для всех сведений для определенного блога:

query {
    getBlog(id: 1) {
        title
        content
        comments {
            id
            owner
            content
        }
    }
}

Если вы задаете сопоставитель для comments поля в типе Blog , необходимо понять, какой идентификатор блога следует использовать. Идентификатор блога можно получить, context.GraphQL.Parent["id"] как показано в следующем сопоставителье:

<http-data-source>
    <http-request>
        <set-method>GET</set-method>
        <set-url>@($"https://data.contoso.com/api/blog/{context.GraphQL.Parent["id"]}")
        </set-url>
    </http-request>
</http-data-source>

Контексте. GraphQL.Arguments

Аргументы для параметризованного запроса GraphQL добавляются в context.GraphQL.Arguments. Например, рассмотрим следующие два запроса:

query($id: Int) {
    getComment(id: $id) {
        content
    }
}

query {
    getComment(id: 2) {
        content
    }
}

С их помощью можно вызвать сопоставитель getComment. GraphQL отправляет следующие полезные данные JSON:

{
    "query": "query($id: Int) { getComment(id: $id) { content } }",
    "variables": { "id": 2 }
}

{
    "query": "query { getComment(id: 2) { content } }"
}

Сопоставитель можно определить следующим образом:

<http-data-source>
    <http-request>
        <set-method>GET</set-method>
        <set-url>@($"https://data.contoso.com/api/comment/{context.GraphQL.Arguments["id"]}")</set-url>
    </http-request>
</http-data-source>

Следующие шаги

Дополнительные примеры сопоставителя см. в следующих примерах: