Compartilhar via

Gerenciar e executar notebooks no Fabric com APIs

  • Artigo

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.

Importante

Esse recurso está em versão prévia.

Observação

A autenticação da entidade de serviço está disponível para a API CRUD do Notebook. Não há suporte para executar a API do notebook por enquanto.

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.

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 workspace.

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 do item sob demanda Executar notebook com parametrização.
Cancelar instância de trabalho do item Cancelar execução do trabalho do notebook.
Obter instância de trabalho do item Obter status da execução do notebook.

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

Observação

A autenticação da entidade de serviço está disponível para a API de CRUD do Notebook e a API do Job Scheduler, o que significa que você pode usar a entidade de serviço para realizar operações de CRUD, iniciar/cancelar execuções de notebooks e obter o status da execução. Você precisa adicionar a entidade de serviço ao workspace com a função apropriada.

Exemplos de uso da API REST do notebook

Use as instruções a seguir para testar exemplos de uso de APIs públicas específicas de notebook e verificar os resultados.

Observação

Esses cenários abrangem apenas exemplos de uso exclusivos de notebook. Exemplos comuns de API de item do Fabric não são abordados aqui.

Pré-requisitos

A API Rest do Fabric define um ponto de extremidade unificado para operações. Substitua os espaços reservados {WORKSPACE_ID} e {ARTIFACT_ID} por valores apropriados ao seguir os exemplos neste artigo.

Criar um notebook com uma definição

Crie um item de notebook com um arquivo .ipynb existente e outro tipo de arquivos de origem.

Solicitar

POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/items
 
{
    "displayName":"Notebook1",
    "type":"Notebook",
    "definition" : {
        "format": "ipynb", // Use "fabricGitSource" for source file format.
        "parts": [
            {
                "path": "notebook-content.ipynb", // fabric source file format, .py, .scala, .sql files are supported.
                "payload": "eyJuYmZvcm1hdCI6NCwibmJmb3JtYXRfbWlub3IiOjUsImNlbGxzIjpbeyJjZWxsX3R5cGUiOiJjb2RlIiwic291cmNlIjpbIiMgV2VsY29tZSB0byB5b3VyIG5ldyBub3RlYm9va1xuIyBUeXBlIGhlcmUgaW4gdGhlIGNlbGwgZWRpdG9yIHRvIGFkZCBjb2RlIVxuIl0sImV4ZWN1dGlvbl9jb3VudCI6bnVsbCwib3V0cHV0cyI6W10sIm1ldGFkYXRhIjp7fX1dLCJtZXRhZGF0YSI6eyJsYW5ndWFnZV9pbmZvIjp7Im5hbWUiOiJweXRob24ifX19",
                "payloadType": "InlineBase64"
            }
        ]
    }
}

A carga na solicitação é uma cadeia de caracteres base64 convertida do notebook de exemplo a seguir.

{
    "nbformat": 4,
    "nbformat_minor": 5,
    "cells": [
        {
            "cell_type": "code",
            "source": [
                "# Welcome to your new notebook\n# Type here in the cell editor to add code!\n"
            ],
            "execution_count": null,
            "outputs": [],
            "metadata": {}
        }
    ],
    "metadata": {
        "language_info": {
            "name": "python"
        },
        "dependencies": {
            "environment": {
                "environmentId": "6524967a-18dc-44ae-86d1-0ec903e7ca05",
                "workspaceId": "c31eddd2-26e6-4aa3-9abb-c223d3017004"
            },
            "lakehouse": {
                "default_lakehouse": "5b7cb89a-81fa-4d8f-87c9-3c5b30083bee",
                "default_lakehouse_name": "lakehouse_name",
                "default_lakehouse_workspace_id": "c31eddd2-26e6-4aa3-9abb-c223d3017004"
            }
        }
    }
}

Observação

Você pode alterar o lakehouse padrão ou o ambiente anexado do notebook alterando metadata.trident.lakehouse ou metadata.trident.environment do conteúdo dele.

Obter um notebook com uma definição

Use a API a seguir para obter o conteúdo do notebook. O Fabric dá suporte à configuração do formato como .ipynb na cadeia de caracteres de consulta para obter um notebook .ipynb.

Solicitar

POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/items/{{ARTIFACT_ID}}/GetDefinition?format=ipynb

Response

Código de status: 200

{
    "definition": {
        "parts": [
            {
                "path": "notebook-content.ipynb",
                "payload": "eyJuYmZvcm1hdCI6NCwibmJmb3JtYXRfbWlub3IiOjUsImNlbGxzIjpbeyJjZWxsX3R5cGUiOiJjb2RlIiwic291cmNlIjpbIiMgV2VsY29tZSB0byB5b3VyIG5ldyBub3RlYm9va1xuIyBUeXBlIGhlcmUgaW4gdGhlIGNlbGwgZWRpdG9yIHRvIGFkZCBjb2RlIVxuIl0sImV4ZWN1dGlvbl9jb3VudCI6bnVsbCwib3V0cHV0cyI6W10sIm1ldGFkYXRhIjp7fX1dLCJtZXRhZGF0YSI6eyJsYW5ndWFnZV9pbmZvIjp7Im5hbWUiOiJweXRob24ifX19",
                "payloadType": "InlineBase64"
            }
        ]
    }
}

Executar um notebook sob demanda

Agende a execução do notebook com a API a seguir. O trabalho do Spark começa a ser executado após uma solicitação bem-sucedida.

O Fabric dá suporte à passagem de parameters no corpo da solicitação para parametrizar a execução do notebook. Os valores são consumidos pela célula de parâmetro do notebook.

Você também pode usar configuration para personalizar a sessão do Spark da execução do notebook. configuration compartilha o mesmo contrato com o comando magic de configuração de sessão do Spark.

Solicitar

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

{
    "executionData": {
        "parameters": {
            "parameterName": {
                "value": "new value",
                "type": "string"
            }
        },
        "configuration": {
            "conf": {
                "spark.conf1": "value"
            },
            "environment": {
                "id": "<environment_id>",
                "name": "<environment_name>"
            },
            "defaultLakehouse": {
                "name": "<lakehouse-name>",
                "id": "<lakehouse-id>",
                "workspaceId": "<(optional) workspace-id-that-contains-the-lakehouse>"
            },
            "useStarterPool": false,
            "useWorkspacePool": "<workspace-pool-name>"
        }
    }
}

Response

Código de status: 202

Location: https://api.fabric.microsoft.com/v1/workspaces/4b218778-e7a5-4d73-8187-f10824047715/items/431e8d7b-4a95-4c02-8ccd-6faef5ba1bd7/jobs/instances/f2d65699-dd22-4889-980c-15226deb0e1b
Retry-After: 60

Com location, você pode usar Obter instância de trabalho do item para exibir o status do trabalho ou usar Cancelar instância de trabalho do item para cancelar a execução atual do notebook.

Conteúdo relacionado