Управление и выполнение записных книжек в Fabric с помощью API

  • Статья

REST API Microsoft Fabric предоставляет конечную точку службы для операций создания, чтения, обновления и удаления (CRUD) элемента Fabric. В этой статье описаны доступные ИНТЕРФЕЙСы REST API записной книжки и их использование.

Внимание

Эта функция доступна в предварительной версии.

Примечание.

Проверка подлинности субъекта-службы доступна для API CRUD записной книжки . Сейчас он не поддерживается для запуска API записной книжки.

С помощью API записных книжек инженеры и специалисты по обработке и анализу данных могут автоматизировать собственные конвейеры и удобно и эффективно устанавливать CI/CD. Эти API также позволяют пользователям легко управлять элементами записных книжек Fabric и интегрировать записные книжки с другими инструментами и системами.

Эти действия по управлению элементами доступны для записных книжек:

Действие Description
Создать элемент Создает записную книжку в рабочей области.
Обновление элемента Обновляет метаданные записной книжки.
Обновление определения элемента Обновляет содержимое записной книжки.
Удаление элемента Удаляет записную книжку.
Get item (Получение элемента) Возвращает метаданные записной книжки.
Получение определения элемента Возвращает содержимое записной книжки.
Элемент списка Вывод списка всех элементов в рабочей области.

Дополнительные сведения см. в разделе "Элементы — REST API".

Для записных книжек доступны следующие действия планировщика заданий:

Действие Description
Выполнение задания элемента по запросу Запустите записную книжку с параметризацией.
Отмена экземпляра задания элемента Отмена выполнения задания записной книжки.
Получение экземпляра задания элемента Получение состояния выполнения записной книжки.

Дополнительные сведения см. в разделе "Планировщик заданий".

Примеры использования REST API записной книжки

Используйте следующие инструкции, чтобы проверить примеры использования для определенных общедоступных API записных книжек и проверить результаты.

Примечание.

В этих сценариях рассматриваются только примеры использования записных книжек. Примеры распространенных API элементов структуры не рассматриваются здесь.

Необходимые компоненты

REST API Fabric определяет единую конечную точку для операций. Замените заполнители и {ARTIFACT_ID} соответствующими значениями при выполнении примеров {WORKSPACE_ID} в этой статье.

Создание записной книжки с определением

Создайте элемент записной книжки с существующим IPYNB-файлом:

Запросить

POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/items

{
    "displayName":"Notebook1",
    "type":"Notebook",
    "definition" : {
        "format": "ipynb",
        "parts": [
            {
                "path": "artifact.content.ipynb",
                "payload": "eyJuYmZvcm1hdCI6NCwibmJmb3JtYXRfbWlub3IiOjUsImNlbGxzIjpbeyJjZWxsX3R5cGUiOiJjb2RlIiwic291cmNlIjpbIiMgV2VsY29tZSB0byB5b3VyIG5ldyBub3RlYm9va1xuIyBUeXBlIGhlcmUgaW4gdGhlIGNlbGwgZWRpdG9yIHRvIGFkZCBjb2RlIVxuIl0sImV4ZWN1dGlvbl9jb3VudCI6bnVsbCwib3V0cHV0cyI6W10sIm1ldGFkYXRhIjp7fX1dLCJtZXRhZGF0YSI6eyJsYW5ndWFnZV9pbmZvIjp7Im5hbWUiOiJweXRob24ifX19",
                "payloadType": "InlineBase64"
            }
        ]
    }
}

Полезные данные в запросе — это строка base64, преобразованная из следующей примера записной книжки.

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

Примечание.

Вы можете изменить записную книжку по умолчанию lakehouse или подключенную среду, изменив содержимое metadata.trident.lakehouse записной книжки или metadata.trident.environment.

Получение записной книжки с определением

Чтобы получить содержимое записной книжки, используйте следующий API. Fabric поддерживает настройку формата в виде IPynb в строке запроса, чтобы получить записную книжку IPynb.

Запросить

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

Response

Код состояния: 200.

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

Запуск записной книжки по запросу

Запланируйте запуск записной книжки с помощью следующего API. Задание Spark начинает выполняться после успешного запроса.

Fabric поддерживает передачу parameters текста запроса для параметризации запуска записной книжки. Значения используются ячейкой параметра записной книжки.

Вы также можете использовать configuration для персонализации сеанса Запуска записной книжки Spark. configurationиспользует тот же контракт с магической командой конфигурации сеанса Spark.

Запросить

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

Код состояния: 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

С locationпомощью функции get Item Job Instance можно просмотреть состояние задания или отменить выполнение текущей записной книжки с помощью экземпляра задания отмены.

Связанный контент