Поделиться через

API Fabric для редактора GraphQL

API Fabric для GraphQL предоставляет графическую среду разработки GraphQL в браузере, которая позволяет интерактивной игровой площадке создавать, тестировать и просматривать динамические результаты запросов и мутаций GraphQL.

Кто использует редактор GraphQL

Редактор GraphQL имеет важное значение для следующих элементов:

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

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

Начало работы с редактором GraphQL

Выполните следующие действия, чтобы начать работу с редактором GraphQL:

  1. Откройте элемент API GraphQL. Перейдите к рабочей области в Fabric и откройте API для элемента GraphQL.

  2. Доступ к редактору — выберите запрос в левом нижнем углу экрана портала.

    Снимок экрана, показывающий, где отображается параметр

  3. Напишите запрос . Введите запросы GraphQL непосредственно на вкладке "Запрос ". Используйте Intellisense с сочетаниями клавиш:

    • Windows: CTRL + ПРОБЕЛ
    • macOS: команда + пробел

    Снимок экрана редактора API, на котором показана вкладка

  4. Выполните запрос. Выберите"Выполнить" , чтобы выполнить запрос и получить данные из источника данных.

Создание кода

Редактор API автоматически создает стандартный код Python или Node.js, который отражает запрос GraphQL или мутацию, которую вы сейчас тестируете в редакторе. По мере создания прототипа и уточнения запросов созданный код обновляется соответствующим образом. Когда вы удовлетворены результатами, вы можете просмотреть и скопировать созданный код, чтобы выполнить локально для тестирования или повторно использовать его в процессе разработки приложений.

Внимание

Созданный код использует учетные данные интерактивного браузера и должен использоваться только для тестирования. В производственной среде всегда регистрируйте приложение в Microsoft Entra и используйте соответствующие client_id и области действия. Полный пример можно найти в примере кода в Connect Applications.

Чтобы приступить к работе, выполните приведенные действия.

  1. Напишите запрос . Введите следующий пример запроса (или собственный) в редакторе запросов:

    query {
  addresses(first: 5) {
     items {
        AddressID
        City
        StateProvince
        CountryRegion
     }  
  }
}

  2. Запустите запрос. Выберите"Запустить" , чтобы выполнить запрос, и убедитесь, что он работает правильно в редакторе, прежде чем продолжить.

  3. Создайте код . Нажмите кнопку "Создать код ", а затем выберите предпочитаемый язык программирования (Python или JavaScript/Node.JS):

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

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

Python

  1. Создайте файл с именем editor.py и вставьте созданный код из приведенного выше примера запроса.

  2. Создайте виртуальную среду, выполнив команду python -m venv .venv.

  3. Активация venv путем выполнения .venv\Scripts\activate или source .venv/bin/activate.

  4. Установите необходимую зависимость, выполнив команду pip install azure-identity.

  5. Выполните код с помощью python editor.py.

  6. Вам будет предложено войти через окно браузера для проверки подлинности запроса.

  7. Ответ API печатается в консоли.

    {
	"data": {
		"addresses": {
			"items": [
				{
					"AddressID": 9,
					"City": "Bothell",
					"StateProvince": "Washington",
					"CountryRegion": "United States"
				},
				{
					"AddressID": 11,
					"City": "Bothell",
					"StateProvince": "Washington",
					"CountryRegion": "United States"
				},
				{
					"AddressID": 25,
					"City": "Dallas",
					"StateProvince": "Texas",
					"CountryRegion": "United States"
				},
				{
					"AddressID": 28,
					"City": "Phoenix",
					"StateProvince": "Arizona",
					"CountryRegion": "United States"
				},
				{
					"AddressID": 32,
					"City": "Montreal",
					"StateProvince": "Quebec",
					"CountryRegion": "Canada"
				}
			]
		}
	}
}

Node.JS

  1. Создайте файл с именем editor.js и вставьте созданный код из приведенного выше примера запроса.

  2. В той же папке editor.js создайте файл package.json со следующим содержимым:

    {
  "type": "module",
  "dependencies": {}
}

  3. Установка Node.js на компьютере разработки (включает npm)

  4. Выполните npm install @azure/identity или аналогичную команду в выбранном менеджере пакетов, чтобы установить самую последнюю версию библиотеки удостоверений.

  5. Запустите node editor.js , чтобы выполнить код.

  6. Вам будет предложено войти через окно браузера для проверки подлинности запроса.

  7. Ответ API печатается в консоли.

    {
	"data": {
		"addresses": {
			"items": [
				{
					"AddressID": 9,
					"City": "Bothell",
					"StateProvince": "Washington",
					"CountryRegion": "United States"
				},
				{
					"AddressID": 11,
					"City": "Bothell",
					"StateProvince": "Washington",
					"CountryRegion": "United States"
				},
				{
					"AddressID": 25,
					"City": "Dallas",
					"StateProvince": "Texas",
					"CountryRegion": "United States"
				},
				{
					"AddressID": 28,
					"City": "Phoenix",
					"StateProvince": "Arizona",
					"CountryRegion": "United States"
				},
				{
					"AddressID": 32,
					"City": "Montreal",
					"StateProvince": "Quebec",
					"CountryRegion": "Canada"
				}
			]
		}
	}
}

Разработка запросов и мутаций

В следующих примерах демонстрируется синтаксис запросов GraphQL и мутаций с помощью примера данных AdventureWorks. В этих примерах предполагается, что вы работаете с хранилищем данных Fabric, поддерживающим операции записи (мутации). Источники данных, доступ к которых осуществляется через конечные точки аналитики SQL (например, Lakehouses и зеркальные базы данных), доступны только для чтения и поддерживают только запросы, а не мутации.

Просмотрите этот краткий фрагмент схемы GraphQL из AdventureWorks. Он определяет Product тип с запросами для чтения одного продукта или перечисления всех продуктов, а также с мутаторами для создания, обновления или удаления продуктов, поддерживая все сценарии использования CRUDL (создание, чтение, обновление, удаление, перечисление).

{
  type Product {
    ProductID: Int!
    Name: String!
    ProductNumber: String!
    Color: String
    ListPrice: Float!
    SellStartDate: DateTime!
  }

  type Query {
    products(first: Int, filter: ProductFilterInput): ProductConnection
    products_by_pk(ProductID: Int!): Product
  }

  type Mutation {
    createProduct(Name: String!, ProductNumber: String!, ListPrice: Float!, SellStartDate: DateTime!): Product
    updateProduct(ProductID: Int!, Name: String, Color: String, ListPrice: Float): Product
    deleteProduct(ProductID: Int!): Boolean
  }
}

Чтение данных, предоставляемых с помощью GraphQL, с помощью любого запроса, определенного в схеме. Запрос products_by_pk извлекает один продукт по первичному ключу.

query MyQuery {
  products_by_pk(ProductID: 680) {
    ProductID
    Name
    ProductNumber
    Color
    ListPrice
  }
}

Ответ.

{
  "data": {
    "products_by_pk": {
      "ProductID": 680,
      "Name": "HL Road Frame - Black, 58",
      "ProductNumber": "FR-R92B-58",
      "Color": "Black",
      "ListPrice": 1431.50
    }
  }
}

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

mutation MyMutation {
  createProduct(
    Name: "Mountain Bike Helmet - Blue", 
    ProductNumber: "HE-M897-B", 
    ListPrice: 89.99,
    SellStartDate: "2025-01-01T00:00:00Z"
  ) {
    ProductID
    Name
    ProductNumber
    ListPrice
  }
}

Ответ.

{
  "data": {
    "createProduct": {
      "ProductID": 1001,
      "Name": "Mountain Bike Helmet - Blue",
      "ProductNumber": "HE-M897-B",
      "ListPrice": 89.99
    }
  }
}

Переменные запроса

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

mutation MyMutation ($name: String!, $productNumber: String!, $listPrice: Float!, $sellStartDate: DateTime!){
  createProduct(
    Name: $name, 
    ProductNumber: $productNumber, 
    ListPrice: $listPrice,
    SellStartDate: $sellStartDate
  ) {
    ProductID
    Name
    ProductNumber
    ListPrice
  }
}

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

{
  "name": "Mountain Bike Helmet - Blue",
  "productNumber": "HE-M897-B",
  "listPrice": 89.99,
  "sellStartDate": "2025-01-01T00:00:00Z"
}

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

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

  • Last updated on