Gerenciar e executar notebooks no Fabric com APIs

A API REST do Microsoft Fabric fornece um ponto de extremidade de serviço para operações de criação, leitura, atualização e exclusão (CRUD) de um item do Fabric. Este artigo descreve as APIs REST de notebook disponíveis e o uso delas.

Com as APIs de notebook, engenheiros de dados e cientistas de dados podem automatizar os próprios pipelines e estabelecer CI/CD de forma conveniente e eficiente. Essas APIs também facilitam o gerenciamento e a manipulação de itens de notebook do Fabric e integram os notebooks a outras ferramentas e sistemas. Os notebooks podem ser orquestrados a partir de pipelines do Fabric e agendadores externos por meio dessas APIs, permitindo uma integração perfeita com fluxos de trabalho automatizados.

Estas ações de Gerenciamento de item estão disponíveis para notebooks:

Ação Descrição
Criar item Cria um notebook em um workspace.
Atualizar item Atualiza os metadados de um notebook.
Atualiza a definição do item Atualiza o conteúdo de um notebook.
Excluir item Exclui um notebook.
Obter item Obtém os metadados de um notebook.
Obtém a definição do item Obtém o conteúdo de um notebook.
Item de lista Lista todos os itens em um espaço de trabalho.

Para obter mais informações, confira Itens – API REST.

As seguintes ações do Agendador de trabalho estão disponíveis para notebooks:

Ação Descrição
Executar trabalho de item sob demanda Execute um notebook sob demanda com suporte para configuração de parâmetros, configuração de sessão (como ajustes do Spark/compute), seleção de ambiente e tempo de execução, e escolha do destino do Fabric Lakehouse.
Cancelar instância de tarefa do item Cancelar uma execução de trabalho no notebook.
Obter Instância da Tarefa do Item Obtenha o status de execução do notebook e recupere o valor de saída retornado pela execução.

Para obter mais informações, confira Agendador de trabalho.

Observação

A autenticação do princípio de serviço tem suporte para a API REST de Itens (operações CRUD do notebook) e a API de Agendamento de Trabalho (execução, monitoramento e cancelamento). Isso permite automação segura sem supervisão e cenários de CI/CD. Adicione o principal do serviço ao workspace com uma função apropriada (Administrador, Membro ou Colaborador) para a gestão e execução de notebooks.

Valores de saída de execuções de um notebook

As execuções de notebooks realizadas por meio da API do Job Scheduler podem retornar um valor de saída que você pode usar para orquestração condicional. O valor de saída aparece no campo exitValue da carga de resposta Get Item Job Instance.

Um notebook pode definir seu valor de saída chamando mssparkutils.notebook.exit("your-value") antes que a execução seja concluída. O valor de saída é uma cadeia de caracteres e pode codificar qualquer sinal de resultado, por exemplo, "success""no_rows_processed"ou um resultado serializado por JSON.

Orquestradores externos, pipelines do Fabric e outras ferramentas de automação podem chamar Get Item Job Instance depois que a execução for concluída para ler o valor de saída e ramificar os resultados. Por exemplo:

  1. Envie uma Tarefa de Item Executada sob Demanda com parâmetros e configurações de execução.
  2. Verifique a Instância do Trabalho de Obtenção de Item até que status seja Completed (ou Failed).
  3. Leia exitValue a partir da resposta para determinar a próxima etapa em seu fluxo de trabalho.

Esse padrão permite a orquestração condicional e a sinalização a jusante com base nos resultados da execução do notebook.

Exemplo de ponta a ponta

O exemplo a seguir mostra como enviar uma execução de notebook e recuperar seu status e valor de saída. Para obter o esquema completo da solicitação, incluindo parâmetros, configuração de sessão e campos de seleção do Lakehouse, consulte a referência da API Agendador de Trabalhos – Execução sob Demanda.

Etapa 1: Enviar uma execução

Use o endpoint Executar Item Job sob demanda para iniciar uma execução de notebook:

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{notebookId}/jobs/instances?jobType=RunNotebook

A resposta retorna 202 Accepted com um Location cabeçalho que contém a URL da instância de trabalho que você usa para monitorar a execução.

Etapa 2: recuperar o status da execução e o valor de saída

Use a URL do cabeçalho Location para verificar o status e ler o valor de saída após a conclusão da execução.

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{notebookId}/jobs/instances/{jobInstanceId}

Resposta de exemplo (abreviada):

{
  "id": "<jobInstanceId>",
  "itemId": "<notebookId>",
  "jobType": "RunNotebook",
  "invokeType": "OnDemand",
  "status": "Completed",
  "startTimeUtc": "2026-03-01T10:00:00Z",
  "endTimeUtc": "2026-03-01T10:05:00Z",
  "failureReason": null,
  "exitValue": "success"
}

Leia exitValue para determinar o resultado e ramificar sua lógica de automação adequadamente.

  • Last updated on