다음을 통해 공유

API를 사용하여 Fabric에서 Notebook 관리 및 실행

  • 아티클

Microsoft Fabric REST API는 Fabric 항목의 CRUD(만들기, 읽기, 업데이트 및 삭제) 작업을 위한 서비스 엔드포인트를 제공합니다. 이 문서에서는 사용 가능한 Notebook REST API 및 해당 사용에 대해 설명합니다.

Important

이 기능은 미리 보기로 제공됩니다.

참고 항목

서비스 주체 인증 은 Notebook CRUD API에 사용할 수 있습니다. 지금은 Notebook API 실행에 대해 지원되지 않습니다.

Notebook API를 사용하면 데이터 엔지니어와 데이터 과학자가 자체 파이프라인을 자동화하고 CI/CD를 편리하고 효율적으로 설정할 수 있습니다. 또한 이러한 API를 사용하면 사용자가 Fabric Notebook 항목을 쉽게 관리 및 조작하고 Notebook을 다른 도구 및 시스템과 통합할 수 있습니다.

이러한 항목 관리 작업은 Notebook에 사용할 수 있습니다.

작업 설명
항목 만들기 워크 영역 안에 Notebook을 만듭니다.
항목 업데이트 Notebook의 메타데이터를 업데이트합니다.
항목 정의 업데이트 Notebook의 콘텐츠를 업데이트합니다.
항목 삭제 Notebook 삭제
항목 가져오기 Notebook의 메타데이터를 가져옵니다.
항목 정의 가져오기 Notebook의 콘텐츠를 가져옵니다.
목록 항목 작업 영역의 모든 항목을 나열합니다.

자세한 내용은 항목 - REST API를 참조하세요.

Notebook에 사용할 수 있는 작업 스케줄러 작업은 다음과 같습니다.

작업 설명
주문형 항목 작업 실행 매개 변수화를 사용하여 Notebook을 실행합니다.
항목 작업 인스턴스 취소 Notebook 작업 실행을 취소합니다.
항목 작업 인스턴스 가져오기 Notebook 실행 상태를 가져옵니다.

자세한 내용은 작업 스케줄러을 참조하세요.

Notebook REST API 사용 예제

다음 지침을 사용하여 특정 Notebook 공용 API에 대한 사용 예제를 테스트하고 결과를 확인합니다.

참고 항목

이러한 시나리오는 Notebook 고유 사용 예제만 다룹니다. Fabric 항목 일반적인 API 예제는 여기에서 다루지 않습니다.

필수 조건

Fabric Rest API는 작업에 대한 통합 엔드포인트를 정의합니다. 이 문서의 예제를 따를 때 자리 표시자를 {WORKSPACE_ID}과 {ARTIFACT_ID}를 적절한 값으로 바꿉니다.

정의가 있는 Notebook 만들기

기존 .ipynb 파일 및 다른 형식의 소스 파일을 사용하여 Notebook 항목을 만듭니다.

요청

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

요청의 페이로드는 다음 샘플 Notebook에서 변환된 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"
            }
        }
    }
}

참고 항목

Notebook 콘텐츠 metadata.trident.lakehouse 또는 metadata.trident.environment를 변경하여 Notebook 기본 Lakehouse 또는 첨부된 환경을 변경할 수 있습니다.

정의가 있는 Notebook 가져오기

다음 API를 사용하여 Notebook 콘텐츠를 가져옵니다. Fabric은 .ipynb Notebook을 가져오기 위해 쿼리 문자열에서 형식을 .ipynb로 설정할 수 있도록 지원합니다.

Request

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

필요에 따라 Notebook 실행

다음 API를 사용하여 Notebook 실행을 예약합니다. Spark 작업은 요청이 성공한 후 실행을 시작합니다.

Fabric은 노트북 실행을 매개 변수화하기 위해 요청 본문에 parameters를 전달할 수 있도록 지원합니다. 이 값은 Notebook 매개 변수 셀에서 사용합니다.

configuration를 사용해 노트북 실행의 Spark 세션을 개인화할 수도 있습니다. configuration는 Spark 세션 구성 매직 명령으로 동일한 계약을 공유합니다.

Request

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

응답

상태 코드: 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를 사용하면 항목 작업 인스턴스 가져오기를 사용해 작업 상태를 보거나 항목 작업 인스턴스 취소를 사용해 현재 노트북 실행을 취소할 수 있습니다.

관련 콘텐츠