Configurar um back-end de carga de trabalho do Microsoft Fabric usando a especificação OpenAPI (Swagger)

Um back-end de carga de trabalho do Microsoft Fabric é um serviço que implementa o contrato da API do Fabric, que permite que cargas de trabalho personalizadas se integrem perfeitamente à plataforma Microsoft Fabric. Esse back-end lida com as operações do ciclo de vida dos itens da carga de trabalho, incluindo criação, recuperação, atualizações e exclusão.

Este artigo orienta você na geração rápida de um back-end de carga de trabalho do Fabric diretamente de uma definição de OpenAPI (Swagger). Essa abordagem API-first permite que você prototipe e valide rapidamente a lógica de back-end de forma independente, mesmo antes de integrá-la ao ambiente de desenvolvimento completo do Microsoft Fabric. Os princípios aqui demonstrados são amplamente aplicáveis, independentemente das ferramentas ou idiomas específicos escolhidos.

Ao final deste artigo, você será capaz de:

Gere um back-end de carga de trabalho do Fabric com base no arquivo Swagger incluído em um exemplo.
Compreender a estrutura básica e os componentes de um back-end de carga de trabalho do Fabric.
Execute e teste o back-end gerado localmente usando Python e FastAPI.

Neste artigo, você implementa as seguintes operações principais do ciclo de vida do item. Essas operações correspondem aos pontos de extremidade definidos no arquivo Fabric API Swagger.

Criar item: inicialize novos itens de carga de trabalho.
Obter carga útil do item: recupere a configuração do item.
Item de atualização: modifique itens existentes.
Eliminar item: Remover itens da área de trabalho.

Este artigo demonstra especificamente o processo usando Python e FastAPI com a ferramenta OpenAPI Generator. No entanto, OpenAPI Generator em si suporta inúmeras linguagens de programação e frameworks. Você é livre para escolher qualquer ferramenta ou método de geração de código compatível com OpenAPI que se adapte à experiência da sua equipe e às necessidades do projeto para criar seu esqueleto de back-end.

Pré-requisitos

Antes de iniciar os procedimentos neste artigo, verifique se você tem os seguintes itens.

Conhecimentos necessários

Compreensão do ciclo de vida do item do Microsoft Fabric. Leia Gerenciamento do ciclo de vida do item.

Esta compreensão é crucial para este artigo. O back-end gerado implementa as operações do ciclo de vida (criar, ler, atualizar, excluir) para itens de malha, conforme definido na documentação do ciclo de vida do item.
Conhecimento básico de Python e APIs RESTful.
Familiaridade com conceitos de carga de trabalho do Microsoft Fabric.

Software necessário

Python 3.8+. Baixar Python.
Node.js, que é necessário se você quiser instalar a CLI do OpenAPI Generator via npm. Faça o download Node.js.
Use o Git para clonar o repositório de exemplo. Transferir Git.
Um editor de código, como Visual Studio Code, PyCharm ou seu ambiente de desenvolvimento integrado (IDE) preferido.

Java para OpenAPI Generator

O CLI do OpenAPI Generator requer Java como ambiente de execução. Você não precisa escrever código Java. Você precisa dele apenas para executar a ferramenta geradora.

A versão mínima necessária do Java é Java 8. Recomendamos que você use uma versão de suporte de longo prazo (LTS) suportada, como Java 17 ou Java 21.

Para instalar o Java:

Instale a compilação Microsoft do OpenJDK (recomendado). Siga as instruções para o seu sistema operacional em Instalar o Microsoft Build do OpenJDK.

Verifique a instalação. Abra um terminal ou prompt de comando e execute:

java -version

Você deve ver uma saída semelhante a este exemplo:

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)

Se você já tiver o Java instalado de outro fornecedor (por exemplo, Oracle, Eclipse Temurin ou Amazon Corretto) com a versão 8 ou posterior, poderá usar a instalação existente.

Etapa 1: configurar seu ambiente de desenvolvimento

Primeiro, configure seu ambiente de desenvolvimento com as ferramentas e pacotes necessários:

Clonar o repositório de exemplo do desenvolvedor do Microsoft Fabric:

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

Crie um PythonBackend diretório:
```
mkdir PythonBackend
cd PythonBackend
```

Crie um ambiente virtual 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

Instale a CLI do OpenAPI Generator:
```
npm install @openapitools/openapi-generator-cli -g
```
Para métodos de instalação alternativos, consulte a documentação de instalação do OpenAPI Generator.

Etapa 2: Verifique se seu ambiente virtual Python está ativo

Depois de criar seu ambiente virtual, é crucial garantir que você esteja usando o interpretador Python correto. Essa abordagem mantém as dependências do projeto isoladas e gerenciadas corretamente.

Verificar a ativação do ambiente virtual

Confirme se o seu ambiente virtual está ativado. Você deve ver (.venv) no início do prompt do terminal.

Se o ambiente virtual não estiver ativado, execute:

# Windows
.venv\Scripts\activate

# macOS/Linux
source .venv/bin/activate

Verifique se o interpretador Python do seu ambiente virtual está ativo

Confirme se seu terminal está usando o interpretador Python do seu ambiente virtual, não a instalação global do Python do seu sistema.

Execute o seguinte comando:

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

A saída esperada deve apontar para o seu ambiente virtual:

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

Importante

Se a saída apontar para um local diferente (como a instalação do Python em todo o sistema), o ambiente virtual não será ativado corretamente. Revisite a tarefa de ativação e verifique se o prompt do terminal aparece com (.venv).

Configure seu IDE (opcional)

A maioria dos IDEs modernos deteta automaticamente ambientes virtuais Python. No entanto, talvez seja necessário selecionar manualmente o intérprete nas configurações do IDE.

Exemplo: Configuração do Visual Studio Code

Abra a pasta do projeto no Visual Studio Code.
Abra a paleta de comandos:
- Windows ou Linux: Ctrl+Shift+P
- macOS: Cmd+Shift+P
Procure e selecione Python: Select Interpreter.
Escolha o intérprete localizado no seu ambiente virtual:
- Windows: .venv\Scripts\python.exe
- macOS ou Linux: .venv/bin/python
Verifique sua seleção na barra de status na parte inferior do Visual Studio Code. Ele deve exibir algo como:
```
Python 3.x.x ('.venv': venv)
```
Abra um novo terminal integrado (Terminal>New Terminal). O seu ambiente virtual deve ser ativado automaticamente, conforme indicado na linha de comando (.venv).

Solucionar problemas do seu ambiente virtual

Certifique-se sempre de que seu ambiente virtual esteja ativado antes de instalar dependências ou executar seu aplicativo. O (.venv) prefixo no seu terminal confirma o estado de ativação. Se você encontrar erros de importação ou pacotes ausentes, verifique se está usando o interpretador Python correto executando os comandos de verificação mencionados anteriormente.

Sugestão

Se o IDE não detetar automaticamente o ambiente virtual ou se o caminho do intérprete não corresponder ao ambiente virtual, tente estas soluções:

Certifique-se de abrir o IDE a partir do diretório correto do projeto.
Reinicie o IDE e tente selecionar o intérprete novamente.
Confirme se o seu ambiente virtual está ativado no seu terminal.

Etapa 3: Gerar o projeto FastAPI a partir da especificação OpenAPI

Use a CLI do OpenAPI Generator para criar um projeto Python FastAPI a partir da especificação Swagger da API de malha.

Executar o comando de geração

Execute o seguinte comando a partir do diretório PythonBackend :

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

Este comando instrui a CLI do OpenAPI Generator a executar as seguintes ações:

Parâmetro	Valor	Descrição	Obrigatório	Propósito	Referência
`-i`	`[InputSpecPath]` ¹	Especificação de entrada: Especifica o caminho para o arquivo de definição OpenAPI (Swagger) de origem	Obrigatório	Aponta para o contrato da API Fabric que define todos os pontos de extremidade, modelos e operações.	Especificação OpenAPI
`-g`	`python-fastapi` ²	Nome do gerador: Indica à ferramenta para usar o gerador `python-fastapi` para criar código do lado do servidor em Python.	Obrigatório	Determina a estrutura de saída e a linguagem para o código back-end gerado	Gerador de FastAPI em Python Explore todos os geradores de servidor disponíveis
`-o`	`.`	Diretório de saída: Instrui o gerador a colocar os arquivos de saída no diretório atual	Obrigatório	Especifica onde a estrutura do projeto gerado é criada	Não aplicável
`--additional-properties`	`packageName=fabric_api`	Opções específicas do gerador: Define o nome do pacote Python para o código gerado como `fabric_api`	Opcional	Personaliza a estrutura de código gerada e as convenções de nomenclatura	Opções do gerador

¹ Para [InputSpecPath], o caminho é ../Backend/src/Contracts/FabricAPI/Workload/swagger.json.

² Para o parâmetro generator (-g), este artigo usa o valor python-fastapi como exemplo. OpenAPI Generator suporta vários geradores de código do lado do servidor para várias linguagens e estruturas. Você pode substituir python-fastapi pelo gerador desejado. Para obter uma lista abrangente, consulte a documentação do OpenAPI Server Generators.

Instalar as dependências necessárias

Para instalar dependências, use este comando:

pip install -r requirements.txt

No sistema operativo Windows, pode encontrar um erro com o pacote uvloop. Se tal acontecer:

Abra o ficheiro requirements.txt .
Encontre a uvloop entrada, que pode ser semelhante a uvloop==0.17.0. Adicione a plataforma condicional ao final:
```
uvloop==<existing version>; sys_platform != 'win32'
```
Por exemplo, se o arquivo tiver uvloop==0.17.0, altere-o para uvloop==0.17.0; sys_platform != 'win32'.
Execute novamente pip install -r requirements.txt.

Essa alteração garante que uvloop seja instalado apenas em plataformas que não sejam Windows.

Etapa 4: Entender a estrutura do código gerado

OpenAPI Generator cria um projeto FastAPI estruturado com os seguintes diretórios chave:

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

O apis diretório contém as definições de roteador para cada ponto de extremidade da API.
O models diretório contém modelos Pydantic para objetos de solicitação e resposta.
O impl diretório é onde você implementa a lógica do controlador.
O main.py arquivo configura o aplicativo FastAPI.

Etapa 5: Implementar o controlador ItemLifecycle

Crie uma implementação de controlador que lide com solicitações da Fabric API. O controlador herda da classe base gerada.

Criar item_lifecycle_controller.py no impl diretório:

# 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

Etapa 6: Configurar e executar o aplicativo FastAPI

Antes de executar seu aplicativo FastAPI, verifique se a configuração da porta está alinhada com o ambiente de desenvolvimento do Microsoft Fabric. Esta etapa é crucial para a integração adequada com o gateway de desenvolvimento do Fabric.

Compreender a configuração da porta

Quando você está desenvolvendo uma carga de trabalho do Microsoft Fabric, o gateway de desenvolvimento roteia solicitações de API para seu back-end. Esta configuração requer:

Seu back-end para ser executado em uma porta específica (padrão: 5000).
A porta para corresponder ao valor WorkloadEndpointURL na configuração da carga de trabalho.
Todas as chamadas de API da Fabric devem ser encaminhadas através do gateway de desenvolvimento para este endpoint.

Configurar o endpoint de carga de trabalho (para integração com o Fabric)

Ao integrar com o ambiente de desenvolvimento completo do Microsoft Fabric, você precisa configurar a URL do ponto de extremidade da carga de trabalho. Essa configuração informa ao gateway de desenvolvimento para onde encaminhar solicitações de API.

Localize ou crie seu arquivo de configuração de carga de trabalho (workload-dev-mode.json):
- O local padrão é C:\workload-dev-mode.json.
- Você pode criar esse arquivo mais tarde, quando estiver configurando o ambiente de desenvolvimento completo do Fabric.

Certifique-se de que o valor WorkloadEndpointURL corresponda à porta de back-end:

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

Para obter detalhes completos sobre a configuração da carga de trabalho, consulte a documentação para começar a usar o back-end de extensibilidade.

Execute o aplicativo FastAPI

Inicie seu aplicativo FastAPI na porta 5000 (ou a porta escolhida que corresponda à configuração).

Para o Windows PowerShell:

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

Para um prompt de comando do Windows:

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

Para macOS ou Linux:

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

Importante

A configuração PYTHONPATH é crucial para que o Python encontre os módulos corretamente. Esta variável de ambiente afeta apenas a sessão de terminal atual.

Como alternativa, pode executar o comando a partir do diretório src.

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

Observação

A porta 5000 é frequentemente usada como padrão em exemplos de desenvolvimento de carga de trabalho do Microsoft Fabric. Se você precisar usar uma porta diferente:

Altere o --port valor no comando uvicorn (por exemplo, --port 5001).
Para corresponder a esta nova porta, atualize o valor de WorkloadEndpointURL no seu arquivo workload-dev-mode.json (por exemplo, "http://localhost:5001").

Certifique-se de que outro aplicativo em seu sistema ainda não esteja usando a porta escolhida.

Verifique se o backend está acessível

Depois de iniciar o aplicativo, verifique se ele está sendo executado corretamente:

Verifique a saída do console. Deve ser semelhante a este exemplo:

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.

Teste a documentação da API:
1. Abra o seu browser e vá para http://localhost:5000/docs.
2. Confirme se a interface do Swagger exibe todos os endpoints disponíveis.

Etapa 7: Testar a API

Você pode testar a API utilizando comandos Curl ou a interface de utilizador interna do Swagger UI fornecida pelo FastAPI.

Curl

Execute o seguinte comando no seu terminal:

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"
      }
    }
  }'

Interface do usuário do Swagger

O FastAPI gera automaticamente documentação de API interativa, para que você possa testar seus endpoints diretamente do seu navegador:

Abra o seu browser e vá para http://localhost:5000/docs.

ItemLifecycle Na seção, localize o endpoint POST

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

Selecione o botão Experimentar .
Preencha os parâmetros necessários:
- 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
Para o corpo da solicitação, use o seguinte código:
```
{
    "display_name": "Test Item",
    "description": "This is a test item created via Swagger UI",
    "creation_payload": {
        "key1": "value1",
        "key2": "value2",
        "nested": {
        "data": "example"
        }
    }
}
```
Selecione o botão Executar para enviar a solicitação.

O console do servidor exibe uma saída semelhante às seguintes mensagens:
```
=== 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'}}
===========================
```
Os detalhes da resposta também aparecem diretamente na interface do usuário do Swagger.

Sugestão

Usar o Swagger UI geralmente é mais fácil e rápido durante o desenvolvimento, porque fornece uma interface fácil de usar para testar endpoints de API sem precisar criar comandos Curl manualmente.

Etapa 8: Explore a documentação da API

O FastAPI gera automaticamente documentação interativa da API:

Abra o seu browser e vá para http://localhost:5000/docs.
Na Swagger UI exibida, é possível explorar e testar todos os endpoints.
Para ver os pontos de extremidade criar, obter, atualizar e excluir, selecione a ItemLifecycle seção .

A imagem a seguir mostra um exemplo do Swagger UI com os endpoints da Fabric API.

Etapa 9: Implementar funcionalidades mais avançadas

As etapas anteriores forneceram um exemplo básico de como implementar a ItemLifecycle API usando Python com FastAPI. Lembre-se, este artigo é um exemplo fundamental que demonstra apenas os conceitos centrais. Para um back-end robusto e com qualidade de produção, você normalmente implementa mais funcionalidades, como:

Crie classes de serviço para lidar com lógica de negócios, operações de banco de dados e outros elementos de uma camada de serviço:

# 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

Use a injeção de dependência no controlador:

# 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)

Adicionar tratamento de erros:

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")

Aqui estão mais considerações para um back-end robusto:

Implementação dos controladores restantes: Por exemplo, implemente a API de Tarefas e a API de Resolução de Endpoints.
Autenticação e autorização: ajude a proteger seus endpoints validando tokens e permissões. Para obter mais informações, consulte Visão geral de autenticação e autorização de back-end.
Armazenamento persistente: integre com bancos de dados ou outras soluções de armazenamento para persistência de dados.
Registro e monitoramento: implemente o registro e o monitoramento abrangentes para acompanhar a integridade e o desempenho do aplicativo.
Testes: escreva testes de unidade e integração para ajudar a garantir a confiabilidade e a correção.

Conclusão

Agora você configura com êxito um back-end da API de carga de trabalho do Microsoft Fabric usando Python com FastAPI. Esta implementação:

Usa a ferramenta OpenAPI Generator para criar um projeto FastAPI.
Implementa os controladores necessários para lidar com solicitações da Fabric API.

Este artigo é um exemplo básico que demonstra como implementar uma API para ItemLifecycle usando Python. Mais aprimoramentos e considerações, como os descritos na Etapa 9: Implementar funcionalidades mais avançadas, são necessários para criar um back-end de alta qualidade, robusto e seguro que seja adequado para um ambiente de produção.

Uma integração completa com o Microsoft Fabric requer a implementação de tratamento de autenticação adequado, armazenamento persistente, tratamento abrangente de erros e lógica de negócios personalizada específica para sua carga de trabalho.

Comentários

Esta página foi útil?

Last updated on 2026-04-29