Настройка серверной части рабочей нагрузки Microsoft Fabric с помощью спецификации OpenAPI (Swagger)

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

В этой статье вы найдете руководство по быстрому созданию бэкенда для рабочего процесса Fabric непосредственно из спецификации OpenAPI (Swagger). Подход с приоритетом API позволяет оперативно создавать прототипы и валидировать бизнес-логику независимым образом, даже до интеграции в полную среду разработки Microsoft Fabric. Принципы, показанные здесь, широко применимы, независимо от того, какие специальные инструменты или языки вы выбираете.

К концу этой статьи вы сможете:

• Создайте резервную часть рабочей нагрузки Fabric на основе файла Swagger, включенного в пример.
• Понять базовую структуру и компоненты серверной части рабочей нагрузки Fabric.
• Запустите и проверьте созданную серверную часть локально с помощью Python и FastAPI.

В этой статье вы реализуете следующие основные операции из жизненного цикла элементов. Эти операции соответствуют конечным точкам, определенным в файле Swagger API Fabric.

• Создание элемента: инициализация новых элементов рабочей нагрузки.
• Получить полезную нагрузку элемента: извлечь конфигурацию элемента.
• Обновление элемента: изменение существующих элементов.
• Удаление элемента: удаление элементов из рабочей области.

В этой статье описывается процесс с помощью Python и FastAPI с помощью средства генератора OpenAPI. Однако генератор OpenAPI поддерживает множество языков программирования и платформ. Вы можете выбрать любое средство или метод создания кода, совместимое с OpenAPI, которое соответствует опыту вашей команды и потребностям проекта, чтобы создать каркас заднего конца.

Предпосылки

Перед началом процедур в этой статье убедитесь, что у вас есть следующие элементы.

Необходимые знания

• Понимание жизненного цикла элементов Microsoft Fabric. Прочитайте управление жизненным циклом предметов.

  Это понимание имеет решающее значение для этой статьи. Созданный внутренний интерфейс реализует операции жизненного цикла (создание, чтение, обновление, удаление) для элементов Fabric, как определено в документации по жизненному циклу элементов.

• Базовые знания api Python и RESTful.

• Знакомство с понятиями рабочей нагрузки Microsoft Fabric.

Необходимое программное обеспечение

• Python 3.8+. Скачайте Python.
• Node.js, что необходимо для установки OpenAPI Generator CLI через npm. Скачайте Node.js.
• Git, чтобы клонировать образец репозитория. скачатьGit.
• Редактор кода, например Visual Studio Code, PyCharm или предпочитаемая интегрированная среда разработки (IDE).

Генератор Java для OpenAPI

Интерфейс командной строки генератора OpenAPI требует Java в качестве среды выполнения. Вам не нужно писать код Java. Вам потребуется только запустить средство генератора.

Минимально необходимая версия Java — это Java 8. Рекомендуется использовать поддерживаемую долгосрочную версию поддержки (LTS), например Java 17 или Java 21.

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

1. Установите сборку Microsoft OpenJDK (рекомендуется). Следуйте инструкциям по операционной системе в установке Microsoft Build of OpenJDK.

2. Проверьте установку. Откройте терминал или командную строку и выполните следующую команду:

   java -version
   

   Вы должны увидеть выходные данные, аналогичные этому примеру:

   openjdk version "17.0.12" 2024-07-16 LTS
   OpenJDK Runtime Environment Microsoft-10377968 (build 17.0.12+7-LTS)
   OpenJDK 64-Bit Server VM Microsoft-10377968 (build 17.0.12+7-LTS, mixed mode, sharing)
   

Если у вас уже есть Java от другого поставщика (например, Oracle, Eclipse Temurin или Amazon Corretto) с версией 8 или более поздней, можно использовать существующую установку.

Шаг 1. Настройка среды разработки

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

1. Клонируйте пример репозитория разработчика Microsoft Fabric:

   git clone https://github.com/microsoft/Microsoft-Fabric-workload-development-sample
   cd Microsoft-Fabric-workload-development-sample
   

2. PythonBackend Создайте каталог:

   mkdir PythonBackend
   cd PythonBackend
   

3. Создайте виртуальную среду Python:

   # Create a Python virtual environment for the project
   python -m venv .venv
   
   # Activate the virtual environment
   # Windows
   .venv\Scripts\activate
   
   # macOS/Linux
   source .venv/bin/activate
   

4. Установите cli генератора OpenAPI:

   npm install @openapitools/openapi-generator-cli -g
   

   Альтернативные методы установки см. в документации по установке Генератора OpenAPI.

Шаг 2. Убедитесь, что виртуальная среда Python активна

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

Проверка активации виртуальной среды

Убедитесь, что виртуальная среда активирована. Вы увидите (.venv) в начале запроса терминала.

Если виртуальная среда не активирована, выполните следующую команду:

# Windows
.venv\Scripts\activate

# macOS/Linux
source .venv/bin/activate

Убедитесь, что интерпретатор Python виртуальной среды активен

Убедитесь, что терминал использует интерпретатор Python из виртуальной среды, а не глобальную установку Python вашей системы.

Выполните следующую команду:

# Display the path to the active Python interpreter
python -c "import sys; print(sys.executable)"

Ожидаемые выходные данные должны указывать на виртуальную среду:

- Windows: C:\path\to\project\PythonBackend\.venv\Scripts\python.exe
- macOS/Linux: /path/to/project/PythonBackend/.venv/bin/python

Настройка интегрированной среды разработки (необязательно)

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

Устранение неполадок виртуальной среды

Всегда убедитесь, что виртуальная среда активируется перед установкой зависимостей или запуском приложения. Префикс (.venv) в терминале подтверждает состояние активации. Если возникают ошибки импорта или отсутствующие пакеты, убедитесь, что вы используете правильный интерпретатор Python, выполнив ранее упомянутые команды проверки.

Шаг 3. Создание проекта FastAPI из спецификации OpenAPI

Используйте интерфейс командной строки генератора OpenAPI для создания проекта Python FastAPI из спецификации Swagger API Fabric.

Выполните команду генерации

Выполните следующую команду из PythonBackend каталога:

openapi-generator-cli generate -i ../Backend/src/Contracts/FabricAPI/Workload/swagger.json -g python-fastapi -o . --additional-properties=packageName=fabric_api

Эта команда указывает интерфейсу командной строки генератора OpenAPI выполнить следующие действия:

¹ Для [InputSpecPath], путь имеет значение ../Backend/src/Contracts/FabricAPI/Workload/swagger.json.

² Для параметра генератора (-g) в этой статье используется значение python-fastapi в качестве примера. Генератор OpenAPI поддерживает множество генераторов кода на стороне сервера для различных языков и платформ. Вы можете заменить python-fastapi нужным генератором. Полный список см. в документации по генераторам серверов OpenAPI.

Установка необходимых зависимостей

Чтобы установить зависимости, используйте следующую команду:

pip install -r requirements.txt

В Windows может возникнуть ошибка с пакетом uvloop . Если это произойдет, выполните следующие действия.

1. requirements.txt Откройте файл.

2. Найдите запись uvloop, которая может выглядеть примерно так uvloop==0.17.0. Добавьте в конец условия платформы:

   uvloop==<existing version>; sys_platform != 'win32'
   

   Например, если в вашем файле есть uvloop==0.17.0, измените его на uvloop==0.17.0; sys_platform != 'win32'.

3. Еще раз запустите pip install -r requirements.txt.

Это изменение гарантирует установку uvloop только на платформах, не на Windows.

Шаг 4. Общие сведения о созданной структуре кода

Генератор OpenAPI создает структурированный проект FastAPI со следующими ключевыми каталогами:

PythonBackend/
├── src/
│   └── fabric_api/
│       ├── apis/              # Generated API route definitions
│       │   ├── item_lifecycle_api.py
│       │   ├── jobs_api.py
│       │   └── endpoint_resolution_api.py
│       ├── impl/              # Where you'll implement controllers
│       │   └── __init__.py
│       ├── models/            # Data models for requests/responses
│       │   ├── create_item_request.py
│       │   └── ...
│       └── main.py            # FastAPI application entry point
├── tests/                     # Generated test files
└── requirements.txt           # Dependencies

• Каталог apis содержит определения маршрутизатора для каждой конечной точки API.
• Каталог models содержит модели Pydantic для объектов запроса и ответа.
• Каталог impl находится в том месте, где реализуется логика контроллера.
• Файл main.py настраивает приложение FastAPI.

Шаг 5. Реализация контроллера ItemLifecycle

Создайте реализацию контроллера, которая обрабатывает запросы API Fabric. Контроллер наследует от созданного базового класса.

Создайте item_lifecycle_controller.py в каталоге impl :

# file path: src/fabric_api/impl/item_lifecycle_controller.py

from fabric_api.apis.item_lifecycle_api_base import BaseItemLifecycleApi
from fabric_api.models.get_item_payload_response import GetItemPayloadResponse
from pydantic import Field, StrictStr
from typing_extensions import Annotated
from fastapi import HTTPException

class ItemLifecycleController(BaseItemLifecycleApi):
    """
    Implementation of Item Lifecycle API methods.
    """
    
    async def item_lifecycle_create_item(
        self,
        workspaceId,
        itemType,
        itemId,
        activity_id,
        request_id,
        authorization,
        x_ms_client_tenant_id,
        create_item_request,
    ) -> None:
        """
        Implementation for creating a new item.
        """
        print(f"\n=== CREATE ITEM CALLED ===")
        print(f"Workspace ID: {workspaceId}")
        print(f"Item Type: {itemType}")
        print(f"Item ID: {itemId}")
        print(f"Display Name: {create_item_request.display_name}")
        print(f"Description: {create_item_request.description}")
        if create_item_request.creation_payload:
            print(f"Creation Payload: {create_item_request.creation_payload}")
        print("===========================\n")
        return
    
    async def item_lifecycle_delete_item(
        self,
        workspaceId,
        itemType,
        itemId,
        activity_id,
        request_id,
        authorization,
        x_ms_client_tenant_id,
    ) -> None:
        """
        Implementation for deleting an existing item.
        """
        print(f"Delete item called for itemId: {itemId}")
        return
    
    async def item_lifecycle_get_item_payload(
        self,
        workspaceId,
        itemType,
        itemId,
        activity_id,
        request_id,
        authorization,
        x_ms_client_tenant_id,
    ) -> GetItemPayloadResponse:
        """
        Implementation for retrieving the payload for an item.
        """
        print(f"Get item payload called for itemId: {itemId}")
        # Return a simple payload
        return GetItemPayloadResponse(item_payload={"sample": "data"})
    
    async def item_lifecycle_update_item(
        self,
        workspaceId,
        itemType,
        itemId,
        activity_id,
        request_id,
        authorization,
        x_ms_client_tenant_id,
        update_item_request,
    ) -> None:
        """
        Implementation for updating an existing item.
        """
        print(f"Update item called for itemId: {itemId}")
        return

Шаг 6. Настройка и запуск приложения FastAPI

Перед запуском приложения FastAPI убедитесь, что конфигурация порта соответствует среде разработки Microsoft Fabric. Этот шаг имеет решающее значение для правильной интеграции с шлюзом разработки Fabric.

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

При разработке рабочей нагрузки Microsoft Fabric шлюз разработки направляет запросы API в серверную часть. Для этой конфигурации требуется следующее:

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

Настройка конечной точки рабочей нагрузки (для интеграции Fabric)

При интеграции с полной средой разработки Microsoft Fabric необходимо настроить URL-адрес конечной точки рабочей нагрузки. Эта конфигурация сообщает шлюзу разработки, где пересылать запросы API.

1. Найдите или создайте файл конфигурации рабочей нагрузки (workload-dev-mode.json):

   • По умолчанию он расположен в папке C:\workload-dev-mode.json.
   • Этот файл можно создать позже при настройке полной среды разработки Fabric.

2. Убедитесь, что значение WorkloadEndpointURL соответствует вашему серверному порту.

   {
       "WorkloadEndpointURL": "http://localhost:5000",
       // ... other configuration settings
   }
   

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

Запуск приложения FastAPI

Запустите приложение FastAPI через порт 5000 (или выбранный порт, соответствующий конфигурации).

Для Windows PowerShell:

$env:PYTHONPATH="src"
uvicorn fabric_api.main:app --host 0.0.0.0 --port 5000

Для командной строки Windows:

set PYTHONPATH=src
uvicorn fabric_api.main:app --host 0.0.0.0 --port 5000

Для macOS или Linux:

PYTHONPATH=src uvicorn fabric_api.main:app --host 0.0.0.0 --port 5000

Кроме того, можно выполнить команду из src каталога:

cd src
python -m uvicorn fabric_api.main:app --host 0.0.0.0 --port 5000

Убедитесь, что ваш бэкэнд доступен

После запуска приложения убедитесь, что он работает правильно:

1. Проверьте выходные данные консоли. Он должен быть похож на этот пример:

   INFO:     Uvicorn running on http://0.0.0.0:5000 (Press CTRL+C to quit)
   INFO:     Started reloader process [xxxx]
   INFO:     Started server process [xxxx]
   INFO:     Waiting for application startup.
   INFO:     Application startup complete.
   

2. Проверьте документацию по API:

   1. Откройте свой браузер и перейдите по адресу http://localhost:5000/docs.
   2. Убедитесь, что пользовательский интерфейс Swagger отображает все доступные конечные точки.

Шаг 7. Тестирование API

Вы можете протестировать API с помощью команд Curl или встроенного пользовательского интерфейса Swagger, который предоставляет FastAPI.

Изгиб

Выполните следующую команду в терминале:

curl -X POST "http://localhost:5000/workspaces/test-workspace/items/TestItemType/test-item-123" \
  -H "Content-Type: application/json" \
  -H "activity-id: test-activity-id" \
  -H "request-id: test-request-123" \
  -H "authorization: SubjectAndAppToken1.0 subjectToken=\"dummy-token\", appToken=\"dummy-app-token\"" \
  -H "x-ms-client-tenant-id: test-tenant-456" \
  -d '{
    "display_name": "Test Item",
    "description": "This is a test item created via curl",
    "creation_payload": {
      "key1": "value1",
      "key2": "value2",
      "nested": {
        "data": "example"
      }
    }
  }'

Пользовательский интерфейс Swagger

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

1. Откройте свой браузер и перейдите по адресу http://localhost:5000/docs.

2. В разделе ItemLifecycle найдите конечную точку POST.

   POST /workspaces/{workspaceId}/items/{itemType}/{itemId}
   

3. Нажмите кнопку Попробовать.

4. Заполните необходимые параметры:

   • workspaceId: test-workspace
   • itemType: TestItemType
   • itemId: test-item-123
   • activity-id: test-activity-id
   • request-id: test-request-123
   • authorization: SubjectAndAppToken1.0 subjectToken="dummy-token", appToken="dummy-app-token"
   • x-ms-client-tenant-id: test-tenant-456

   Для текста запроса используйте следующий код:

   
   {
       "display_name": "Test Item",
       "description": "This is a test item created via Swagger UI",
       "creation_payload": {
           "key1": "value1",
           "key2": "value2",
           "nested": {
           "data": "example"
           }
       }
   }
   
   

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

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

   === CREATE ITEM CALLED ===
   Workspace ID: test-workspace
   Item Type: TestItemType
   Item ID: test-item-123
   Display Name: Test Item
   Description: This is a test item created via Swagger UI
   Creation Payload: {'key1': 'value1', 'key2': 'value2', 'nested': {'data': 'example'}}
   ===========================
   

   Сведения об ответе также отображаются непосредственно в пользовательском интерфейсе Swagger.

   Подсказка

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

Шаг 8. Изучение документации по API

FastAPI автоматически создает интерактивную документацию ПО API:

1. Откройте свой браузер и перейдите по адресу http://localhost:5000/docs.

2. В появившемся пользовательском интерфейсе Swagger можно изучить и проверить все конечные точки.

3. Чтобы просмотреть создание, получение, обновление и удаление конечных точек, выберите ItemLifecycle раздел.

На следующем рисунке показан пример пользовательского интерфейса Swagger с конечными точками API Fabric.

Шаг 9. Реализация более сложных функций

Предыдущие шаги содержат базовый пример реализации ItemLifecycle API с помощью Python с FastAPI. Помните, что эта статья является базовым примером, демонстрирующим только основные понятия. Для создания надежной серверной части промышленного качества обычно реализуются дополнительные функциональные возможности, например:

• Создайте классы служб для обработки бизнес-логики, операций с базами данных и других элементов уровня служб:

  # src/fabric_api/services/storage_service.py
  class StorageService:
      async def create_item(self, workspace_id, item_type, item_id, item_data):
          """
          Store the item in a database or other persistent storage
          """
          # Implementation here
          pass
  
      async def get_item(self, workspace_id, item_type, item_id):
          """
          Retrieve an item from storage
          """
          # Implementation here
          pass
  

• Используйте инъекцию зависимостей в вашем контроллере:

  # src/fabric_api/impl/item_lifecycle_controller.py
  from fabric_api.services.storage_service import StorageService
  
  class ItemLifecycleController(BaseItemLifecycleApi):
      def __init__(self):
          self.storage_service = StorageService()
  
      async def item_lifecycle_create_item(self, workspaceId, ...):
          # Use the service
          await self.storage_service.create_item(workspaceId, itemType, itemId, create_item_request)
  

• Добавление обработки ошибок:

  async def item_lifecycle_create_item(self, ...):
      try:
          # Your implementation
          await self.storage_service.create_item(...)
          return None
      except ValueError as e:
          # Client error
          raise HTTPException(status_code=400, detail=str(e))
      except Exception as e:
          # Server error
          raise HTTPException(status_code=500, detail="Internal server error")
  

Ниже приведены дополнительные рекомендации по обеспечению надежной внутренней части:

• Реализация оставшихся контроллеров: например, реализуйте API задач и API разрешения конечных точек.
• Проверка подлинности и авторизация: защита конечных точек путем проверки маркеров и разрешений. Дополнительные сведения см. в обзоре серверной проверки подлинности и авторизации.
• Постоянное хранилище: интеграция с базами данных или другими решениями для хранения данных.
• Ведение журнала и мониторинг. Реализация комплексного ведения журнала и мониторинга для отслеживания работоспособности и производительности приложений.
• Тестирование. Написание модульных и интеграции тестов для обеспечения надежности и правильности.

Заключение

Теперь вы успешно настроили серверную часть API рабочей нагрузки Microsoft Fabric с помощью Python с FastAPI. Эта реализация:

• Использует средство генератора OpenAPI для создания проекта FastAPI.
• Реализует необходимые контроллеры для обработки запросов API Fabric.

В этой статье представлен базовый пример того, как реализовать API для ItemLifecycle, используя Python. Дополнительные усовершенствования и рекомендации, такие как описанные в шаге 9. Реализация более сложных функций необходима для создания высококачественной, надежной и безопасной внутренней части, подходящей для рабочей среды.

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

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

• Документация по Microsoft Fabric
• Документация по пакету средств разработки рабочей нагрузки
• Документация по FastAPI
• Документация по генератору OpenAPI
• Документация по Python asyncio