Gerenciar e executar blocos de anotações no Fabric com APIs

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

Com as APIs de notebook, engenheiros de dados e cientistas de dados podem automatizar seus próprios pipelines e estabelecer CI/CD de forma conveniente e eficiente. Essas APIs também facilitam para os usuários o gerenciamento e a manipulação de itens de bloco de anotações do Fabric e integram blocos de anotações com outras ferramentas e sistemas. Os notebooks podem ser orquestrados através de pipelines do Fabric e de agendadores externos através destas APIs, permitindo uma integração fluida com fluxos de trabalho automatizados.

Estas ações de gerenciamento de itens estão disponíveis para notebooks:

Ação Descrição
Criar item Cria um bloco de anotações dentro de um espaço de trabalho.
Atualizar item Atualiza os metadados de um bloco de anotações.
Atualizar definição de item Atualiza o conteúdo de um bloco de anotações.
Eliminar item Elimina um caderno.
Buscar item Obtém os metadados de um bloco de anotações.
Obter definição de item Obtém o conteúdo de um bloco de anotações.
Item de lista Liste todos os itens em um espaço de trabalho.

Para obter mais informações, consulte Itens - API REST.

As seguintes ações do Job scheduler estão disponíveis para cadernos:

Ação Descrição
Executar trabalho de item sob demanda Execute um notebook sob demanda com suporte para parametrização, configuração de sessão (como Spark/definições de computação), seleção de ambiente e de tempo de execução, e seleção do Fabric Lakehouse alvo.
Cancelar instância de tarefa de item Cancelar uma execução de tarefa de notebook.
Obter instância de tarefa do item Obtenha o estado de execução do notebook e recupere o valor de saída devolvido pela execução.

Para obter mais informações, consulte Agendador de tarefas.

Nota

A autenticação do principal de serviço é suportada tanto para a API REST dos Itens (operações de CRUD do notebook) como para a API do Agendador de Tarefas (execução, monitorização e cancelamento). Isto permite automação segura e não assistida e cenários CI/CD. Adicione o principal de serviço ao espaço de trabalho com um papel apropriado (Administrador, Membro ou Contribuidor) para gerir e executar cadernos.

Valores de saída das execuções de notebooks

As execuções de notebook executadas através da API do Job Scheduler podem devolver um valor de saída que pode usar para orquestração condicional. O valor de saída aparece no campo exitValue da carga útil de resposta da instância de tarefa Get Item Job Instance.

Um notebook pode definir o seu valor de saída chamando mssparkutils.notebook.exit("your-value") antes do processo terminar. O valor de saída é uma cadeia e pode codificar qualquer sinal de resultado — por exemplo, "success", "no_rows_processed", ou um resultado serializado em JSON.

Orquestradores externos, pipelines do Fabric e outras ferramentas de automação podem chamar Get Item Job Instance após a conclusão da execução para ler o valor de saída e tomar decisões com base nos resultados. Por exemplo:

  1. Enviar um Item Job de Execução a Pedido com parâmetros e definições de execução.
  2. Interrogar Get Item Job Instance até status tornar-se Completed (ou Failed).
  3. Leia exitValue a resposta para determinar o próximo passo no seu fluxo de trabalho.

Este padrão permite orquestração condicional e sinalização para fluxos posteriores com base nos resultados de execução do notebook.

Exemplo de ponta a ponta

O exemplo seguinte mostra como submeter uma execução de caderno e recuperar o seu estado e valor de saída. Para o esquema completo do corpo da requisição, incluindo parâmetros, configuração de sessão e campos de seleção do Lakehouse, consulte a documentação da API Job Scheduler - Run on demand Item Job.

Passo 1: Submeter uma execução

Use o endpoint Run on demand Item Job para iniciar uma execução de um notebook:

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

A resposta devolve 202 Accepted com um Location cabeçalho contendo o URL da instância de trabalho que usa para monitorizar a execução.

Passo 2: Recuperar o estado da execução e o valor de saída

Use o URL do Location cabeçalho para verificar o estado e leia o valor de saída após a execução concluir:

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

Exemplo de resposta (abreviado):

{
  "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 ramifice a sua lógica de automação em conformidade.

  • Last updated on