Partilhar via

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

  • Artigo

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 de malha. Este artigo descreve as APIs REST do bloco de anotações disponíveis e seu uso.

Importante

Este recurso está em pré-visualização.

Nota

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

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.

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 Exclui um bloco de anotações.
Obter 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 Agendador de tarefas estão disponíveis para blocos de anotações:

Ação Descrição
Executar trabalho de item sob demanda Execute notebook com parametrização.
Cancelar instância de trabalho de item Cancelar a execução do trabalho do bloco de anotações.
Obter instância de trabalho de item Obter o status de execução do bloco de anotações.

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

Exemplos de uso da API REST do bloco de anotações

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

Nota

Esses cenários abrangem apenas exemplos de uso exclusivos do bloco de anotações. Exemplos comuns de API de item de malha não são abordados aqui.

Pré-requisitos

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

Criar um bloco de notas com uma definição

Crie um item de bloco de anotações com um arquivo .ipynb existente e outro tipo de arquivos de origem.

Pedir

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 útil na solicitação é uma cadeia de caracteres base64 convertida do bloco de anotações 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"
            }
        }
    }
}

Nota

Você pode alterar o ambiente padrão ou anexado do bloco de anotações alterando o conteúdo metadata.trident.lakehouse do bloco de anotações ou metadata.trident.environment.

Obter um bloco de notas com uma definição

Use a API a seguir para obter o conteúdo do bloco de anotações. O Fabric oferece suporte à definição do formato como .ipynb na cadeia de caracteres de consulta para obter um bloco de anotações .ipynb.

Pedir

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 bloco de notas a pedido

Agende a execução do seu bloco de notas com a seguinte API. O trabalho do Spark começa a ser executado após uma solicitação bem-sucedida.

A malha suporta a passagem parameters no corpo da solicitação para parametrizar a execução do bloco de anotações. Os valores são consumidos pela célula de parâmetros do bloco de anotações.

Você também pode usar configuration para personalizar a sessão do Spark da execução do bloco de anotações. configurationcompartilha o mesmo contrato com o comando magic de configuração da sessão do Spark.

Pedir

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 locationo , você pode usar Obter Instância de Trabalho de Item para exibir o status do trabalho ou usar Cancelar Instância de Trabalho de Item para cancelar a execução atual do bloco de anotações.

Conteúdos relacionados