API Fabric для представления схемы GraphQL и обозревателя схем

API Fabric для GraphQL автоматически создает схему, которая определяет структуру API на основе подключенных источников данных. Схема, написанная на языке определения схемы GraphQL (SDL), описывает все доступные типы, поля, запросы и изменения, которые клиенты могут использовать для взаимодействия с данными.

Представление схемы предоставляет только для чтения текстовое представление полной схемы GraphQL, а обозреватель схем в левой области позволяет перемещаться, проверять и изменять объекты, предоставляемые через API. Вместе эти средства помогают понять структуру API и контролировать доступ к данным клиентам.

Кто использует представление схемы

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

• Инженеры данных настраивают объекты Fabric Lakehouse и хранилища для предоставления через GraphQL
• Разработчики приложений обнаруживают доступные типы данных Fabric, поля и связи перед написанием запросов
• Участники рабочей области Fabric понимают структуру доступа к данным и управляют ими для своей рабочей области
• Разработчики бизнес-аналитики просматривают связи данных Fabric при создании пользовательских аналитических приложений

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

Доступ и изучение схемы

Вы можете получить доступ к представлению схемы из редактора запросов или непосредственно из элемента API GraphQL. Чтобы открыть представление схемы, выберите схему в левом нижнем углу. В представлении схемы отображается текстовая версия полного SDL GraphQL в режиме только для чтения, включая все созданные типы, поля, запросы и мутации.

На следующем рисунке показано представление схемы с областью обозревателя схем слева:

Навигация с обозревателем схем

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

Разверните узлы в обозревателе схем, чтобы просмотреть:

• Типы: типы GraphQL, созданные из таблиц и представлений источников данных
• Запросы: автоматически созданные операции чтения для получения данных
• Мутации: автоматически создаваемые операции записи для создания, обновления и удаления данных (только для хранилища)

Типы

Типы представляют структуру данных и отображаются под именем источника данных, из которого они были созданы. На следующем рисунке показан тип SalesOrderDetail, созданный из таблицы SalesOrderDetail в конечной точке аналитики SQL AdventureWorks:

Запросы

API автоматически создает запросы на получение данных из предоставляемых объектов. Разверните узел запросов, чтобы просмотреть все доступные операции чтения:

Изменения

Изменения — это операции записи для создания, обновления и удаления данных. Разверните узел мутаций, чтобы просмотреть все доступные операции записи:

Примечание.

Изменения создаются только для источников данных хранилища данных Fabric. Конечные точки SQL Analytics (Lakehouses и зеркальные базы данных) доступны только для чтения и поддерживают исключительно выполнение запросов. Если в обозревателе схем не отображаются изменения, убедитесь, что вы подключены к хранилищу данных Fabric.

Изменение объектов с помощью обозревателя схем

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

Параметры изменения доступа

Чтобы изменить объект, выберите многоточие (...) рядом с любым типом в обозревателе схем. В следующем примере показано меню изменений для типа SalesOrderDetail :

Доступные варианты изменения

Обновление схемы . Синхронизирует схему GraphQL с последней структурой из источника данных. Используйте это при добавлении новых таблиц, представлений или столбцов в источник данных и их предоставления через API. Эта операция обнаруживает и добавляет новые объекты при сохранении существующей конфигурации.

Переименование . Изменяет способ отображения объекта в API GraphQL. Это полезно для создания более интуитивно понятных соглашений об именовании API или скрытия сведений о реализации от клиентов. Например, можно просто tbl_SalesOrderDetailпереименоватьSalesOrderDetail. Переименование влияет только на схему API и не изменяет базовый объект источника данных.

Удаление из схемы — удаляет объект из API GraphQL, что делает его недоступным для клиентов. Используйте это для скрытия конфиденциальных данных, удаления устаревших объектов или упрощения поверхности API. Данные остаются в источнике данных; удаляется только экспозиция API.

Управление связями — открывает интерфейс управления отношениями, где можно определить, как объекты подключаются друг к другу. Связи обеспечивают вложенные запросы и обход графа, позволяя клиентам получать связанные данные в одном запросе. Дополнительные сведения см. в разделе "Управление связями" в API Fabric для GraphQL.

Свойства — отображает подробные метаданные об объекте, включая исходное имя, как оно отображается в источнике данных, имя типа GraphQL, владелец и расположение (имя рабочей области и источника данных). Используйте это для проверки сопоставления объектов между источником данных и API GraphQL.

Включение и отключение запросов и мутаций

Функция включения или отключения запросов и мутаций предоставляет администраторам и разработчикам детализированный контроль доступа к API и использования. Он позволяет выборочно активировать или деактивировать определенные запросы и изменения в схеме GraphQL. Это позволяет динамически управлять возможностями API, не изменяя код или развертывая изменения.

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

• Управление версиями API: отключение устаревших операций при переходе клиентов на новые версии
• Периоды обслуживания: временно отключите операции записи (изменения) во время обслуживания данных
• Безопасность и соответствие. Ограничение доступа к конфиденциальным операциям без их удаления из схемы
• Поэтапное развертывание: включение новых запросов или мутаций для тестирования, прежде чем сделать их широко доступными

Запросы и изменения в обозревателе схем имеют два других варианта:

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

• Включение. Позволяет повторно включить ранее отключенный запрос или мутацию. Запрос или мутация сразу после операции перезагрузки схемы, которая возникает при выборе параметра "Включить ".

Примечание.

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

Связанный контент

• API Fabric для редактора GraphQL
• Управление связями в API Fabric для GraphQL
• Начало работы с API Fabric для GraphQL