工作区 APIWorkspace API
使用工作区 API 可列出、导入、导出和删除笔记本和文件夹。The Workspace API allows you to list, import, export, and delete notebooks and folders. 对工作区 API 的请求的最大允许大小为 10MB。The maximum allowed size of a request to the Workspace API is 10MB. 有关此 API 的操作方法指南,请参阅工作区示例。See Workspace examples for a how to guide on this API.
重要
要访问 Databricks REST API,必须进行身份验证。To access Databricks REST APIs, you must authenticate.
删除 Delete
端点Endpoint | HTTP 方法HTTP Method |
---|---|
2.0/workspace/delete |
POST |
删除对象或目录(可以选择以递归方式删除目录中的所有对象)。Delete an object or a directory (and optionally recursively deletes all objects in the directory).
如果 path
不存在,则此调用会返回错误 RESOURCE_DOES_NOT_EXIST
。If path
does not exist, this call returns an error RESOURCE_DOES_NOT_EXIST
.
如果 path
为非空目录且 recursive
设置为 false
,则此调用会返回错误 DIRECTORY_NOT_EMPTY
。If path
is a non-empty directory and recursive
is set to false
, this call returns an error DIRECTORY_NOT_EMPTY
.
对象删除无法撤消,且以递归方式删除目录不是原子操作。Object deletion cannot be undone and deleting a directory recursively is not atomic.
请求的示例:Example of request:
{
"path": "/Users/user@example.com/project",
"recursive": true
}
请求结构 Request structure
字段名称Field Name | 类型Type | 描述Description |
---|---|---|
pathpath | STRING |
笔记本或目录的绝对路径。The absolute path of the notebook or directory. 此字段为必需字段。This field is required. |
recursiverecursive | BOOL |
一个标志,用于指定是否以递归方式删除对象。The flag that specifies whether to delete the object recursively. 默认情况下,它为 false 。It is false by default. 请注意,此删除目录操作不是原子操作。Please note this deleting directory is not atomic. 如果此操作中途失败,则该目录下的某些对象可能会被删除,并且无法撤消。If it fails in the middle, some of objects under this directory may be deleted and cannot be undone. |
导出 Export
端点Endpoint | HTTP 方法HTTP Method |
---|---|
2.0/workspace/export |
GET |
导出笔记本或整个目录的内容。Export a notebook or contents of an entire directory.
如果 path
不存在,则此调用会返回错误 RESOURCE_DOES_NOT_EXIST
。If path
does not exist, this call returns an error RESOURCE_DOES_NOT_EXIST
.
只能以 DBC
格式导出目录。You can export a directory only in DBC
format.
如果导出的数据超过大小限制,则此调用会返回错误 MAX_NOTEBOOK_SIZE_EXCEEDED
。If the exported data exceeds the size limit, this call returns an error MAX_NOTEBOOK_SIZE_EXCEEDED
.
此 API 不支持导出库。This API does not support exporting a library.
请求的示例:Example of request:
{
"path": "/Users/user@example.com/project/ScalaExampleNotebook",
"format": "SOURCE"
}
响应的示例,其中 content
已进行 base64 编码:Example of response, where content
is base64-encoded:
{
"content": "Ly8gRGF0YWJyaWNrcyBub3RlYm9vayBzb3VyY2UKMSsx",
}
也可通过启用 direct_download
来下载导出的文件:Alternatively, you can download the exported file by enabling direct_download
:
curl -n -o example.scala \
'https://<databricks-instance>/api/2.0/workspace/export?path=/Users/user@example.com/ScalaExampleNotebook&direct_download=true'
在以下示例中,请将 <databricks-instance>
替换为 Azure Databricks 部署的工作区 URL。In the following examples, replace <databricks-instance>
with the workspace URL of your Azure Databricks deployment.
请求结构 Request structure
字段名称Field Name | 类型Type | 描述Description |
---|---|---|
pathpath | STRING |
笔记本或目录的绝对路径。The absolute path of the notebook or directory. 仅 DBC 支持导出目录。Exporting a directory is supported only for DBC . 此字段为必需字段。This field is required. |
formatformat | ExportFormatExportFormat | 此项指定已导出文件的格式。This specifies the format of the exported file. 默认情况下,该属性为 SOURCE 。By default, this is SOURCE . 但是,它可以是以下值之一:However it may be one of:SOURCE , HTML , JUPYTER , DBC .SOURCE , HTML , JUPYTER , DBC . 值区分大小写。The value is case sensitive. |
direct_downloaddirect_download | BOOL |
一个标志,用于启用直接下载。Flag to enable direct download. 如果它为 true ,则响应将是导出的文件本身。If it is true , the response will be the exported file itself. 否则,响应会包含 base64 编码字符串形式的内容。Otherwise, the response contains content as base64 encoded string. 请参阅导出笔记本或文件夹,详细了解如何使用它。See Export a notebook or folder for more information about how to use it. |
响应结构 Response structure
字段名称Field Name | 类型Type | 描述Description |
---|---|---|
内容content | BYTES |
Base64 编码的内容。The base64-encoded content. 如果超过限制 (10MB),则会引发错误代码为 MAX_NOTEBOOK_SIZE_EXCEEDED 的异常。If the limit (10MB) is exceeded, exception with error code MAX_NOTEBOOK_SIZE_EXCEEDED is thrown. |
获取状态 Get status
端点Endpoint | HTTP 方法HTTP Method |
---|---|
2.0/workspace/get-status |
GET |
获取对象或目录的状态。Gets the status of an object or a directory.
如果 path
不存在,则此调用会返回错误 RESOURCE_DOES_NOT_EXIST
。If path
does not exist, this call returns an error RESOURCE_DOES_NOT_EXIST
.
请求的示例:Example of request:
{
"path": "/Users/user@example.com/project/ScaleExampleNotebook"
}
响应的示例:Example of response:
{
"path": "/Users/user@example.com/project/ScalaExampleNotebook",
"language": "SCALA",
"object_type": "NOTEBOOK",
"object_id": 789
}
请求结构 Request structure
字段名称Field Name | 类型Type | 描述Description |
---|---|---|
pathpath | STRING |
笔记本或目录的绝对路径。The absolute path of the notebook or directory. 此字段为必需字段。This field is required. |
响应结构 Response structure
字段名称Field Name | 类型Type | 说明Description |
---|---|---|
object_typeobject_type | ObjectTypeObjectType | 对象的类型。The type of the object. 它可以是 NOTEBOOK 、DIRECTORY 或 LIBRARY 。It could be NOTEBOOK , DIRECTORY or LIBRARY . |
object_idobject_id | INT64 |
NOTEBOOK 或 DIRECTORY 的唯一标识符。Unique identifier for a NOTEBOOK or DIRECTORY . |
pathpath | STRING |
对象的绝对路径。The absolute path of the object. |
语言language | 语言Language | 对象的语言。The language of the object. 仅当对象类型为 NOTEBOOK 时才设置此值。This value is set only if the object type is NOTEBOOK . |
导入 Import
端点Endpoint | HTTP 方法HTTP Method |
---|---|
2.0/workspace/import |
POST |
导入笔记本或整个目录的内容。Import a notebook or the contents of an entire directory.
如果 path
已存在并且 overwrite
设置为 false
,则此调用会返回错误 RESOURCE_ALREADY_EXISTS
。If path
already exists and overwrite
is set to false
, this call returns an error RESOURCE_ALREADY_EXISTS
.
只能使用 DBC
格式来导入目录。You can use only DBC
format to import a directory.
请求的示例,其中 content
是 1+1
的 base64 编码字符串:Example of request, where content
is the base64-encoded string of 1+1
:
{
"content": "MSsx\n",
"path": "/Users/user@example.com/project/ScalaExampleNotebook",
"language": "SCALA",
"overwrite": true,
"format": "SOURCE"
}
也可直接导入本地文件。Alternatively, you can import a local file directly.
在以下示例中,请将 <databricks-instance>
替换为 Azure Databricks 部署的工作区 URL。In the following examples, replace <databricks-instance>
with the workspace URL of your Azure Databricks deployment.
curl -n -F path=/Users/user@example.com/project/ScalaExampleNotebook -F language=SCALA \
-F content=@example.scala \
https://<databricks-instance>/api/2.0/workspace/import
请求结构 Request structure
字段名称Field Name | 类型Type | 描述Description |
---|---|---|
pathpath | STRING |
笔记本或目录的绝对路径。The absolute path of the notebook or directory. 仅 DBC 格式支持导入目录。Importing directory is only support for DBC format. 此字段为必需字段。This field is required. |
formatformat | ExportFormatExportFormat | 此项指定要导入的文件的格式。This specifies the format of the file to be imported. 默认情况下,该属性为 SOURCE 。By default, this is SOURCE . 但是,它可以是以下值之一:However it may be one of:SOURCE , HTML , JUPYTER , DBC .SOURCE , HTML , JUPYTER , DBC . 值区分大小写。The value is case sensitive. |
语言language | 语言Language | 语言。The language. 如果格式设置为 SOURCE ,则此字段为必填字段;否则,它会被系统忽略。If format is set to SOURCE , this field is required; otherwise, it will be ignored. |
内容content | BYTES |
Base64 编码的内容。The base64-encoded content. 此项的限制为 10 MB。This has a limit of 10 MB. 如果超过限制 (10MB),则会引发错误代码为 MAX_NOTEBOOK_SIZE_EXCEEDED 的异常。If the limit (10MB) is exceeded, exception with error code MAX_NOTEBOOK_SIZE_EXCEEDED is thrown. 此参数可能不存在,将会改用已发布的文件。This parameter might be absent, and instead a posted file will be used. 请参阅导入笔记本或目录,详细了解如何使用它。See Import a notebook or directory for more information about how to use it. |
overwriteoverwrite | BOOL |
一个标志,用于指定是否覆盖现有对象。The flag that specifies whether to overwrite existing object. 默认情况下,它为 false 。It is false by default. 对于 DBC 格式,不支持覆盖,因为它可能包含目录。For DBC format, overwrite is not supported since it may contain a directory. |
列表 List
端点Endpoint | HTTP 方法HTTP Method |
---|---|
2.0/workspace/list |
GET |
列出目录的内容,如果不是目录,则列出对象。List the contents of a directory, or the object if it is not a directory.
如果输入路径不存在,则此调用会返回错误 RESOURCE_DOES_NOT_EXIST
。If the input path does not exist, this call returns an error RESOURCE_DOES_NOT_EXIST
.
请求的示例:Example of request:
{
"path": "/Users/user@example.com/"
}
响应的示例:Example of response:
{
"objects": [
{
"path": "/Users/user@example.com/project",
"object_type": "DIRECTORY",
"object_id": 123
},
{
"path": "/Users/user@example.com/PythonExampleNotebook",
"language": "PYTHON",
"object_type": "NOTEBOOK",
"object_id": 456
}
]
}
请求结构 Request structure
字段名称Field Name | 类型Type | 描述Description |
---|---|---|
pathpath | STRING |
笔记本或目录的绝对路径。The absolute path of the notebook or directory. 此字段为必需字段。This field is required. |
响应结构 Response structure
字段名称Field Name | 类型Type | 描述Description |
---|---|---|
对象objects | 一个 ObjectInfo 数组An array of ObjectInfo | 对象的列表。List of objects. |
Mkdirs Mkdirs
端点Endpoint | HTTP 方法HTTP Method |
---|---|
2.0/workspace/mkdirs |
POST |
创建给定目录和必要的父目录(如果不存在)。Create the given directory and necessary parent directories if they do not exists.
如果在输入路径的任何前缀处存在一个对象(而不是目录),则此调用会返回错误 RESOURCE_ALREADY_EXISTS
。If there exists an object (not a directory) at any prefix of the input path, this call returns an error RESOURCE_ALREADY_EXISTS
.
如果此操作失败,可能已成功创建了一些必需的父目录。If this operation fails it may have succeeded in creating some of the necessary parent directories.
请求的示例:Example of request:
{
"path": "/Users/user@example.com/project"
}
请求结构 Request structure
字段名称Field Name | 类型Type | 描述Description |
---|---|---|
pathpath | STRING |
目录的绝对路径。The absolute path of the directory. 如果父目录不存在,则也会创建它们。If the parent directories do not exist, it will also create them. 如果目录已存在,此命令不需执行任何操作即可成功执行。If the directory already exists, this command will do nothing and succeed. 此字段为必需字段。This field is required. |
数据结构 Data structures
本节内容:In this section:
ObjectInfo ObjectInfo
工作区中对象的信息。The information of the object in workspace. 它由 list
和 get-status
返回。It is returned by list
and get-status
.
字段名称Field Name | 类型Type | 说明Description |
---|---|---|
object_typeobject_type | ObjectTypeObjectType | 对象的类型。The type of the object. 它可以是 NOTEBOOK 、DIRECTORY 或 LIBRARY 。It could be NOTEBOOK , DIRECTORY or LIBRARY . |
object_idobject_id | INT64 |
NOTEBOOK 或 DIRECTORY 的唯一标识符。Unique identifier for a NOTEBOOK or DIRECTORY . |
pathpath | STRING |
对象的绝对路径。The absolute path of the object. |
语言language | 语言Language | 对象的语言。The language of the object. 仅当对象类型为 NOTEBOOK 时才设置此值。This value is set only if the object type is NOTEBOOK . |
ExportFormat ExportFormat
笔记本导入和导出的格式。The format for notebook import and export.
格式Format | 描述Description |
---|---|
源SOURCE | 笔记本将以源代码的形式导入/导出。The notebook will be imported/exported as source code. |
HTMLHTML | 笔记本将以 HTML 文件的形式导入/导出。The notebook will be imported/exported as an HTML file. |
JUPYTERJUPYTER | 笔记本将以 Jupyter/IPython Notebook 文件的形式导入/导出。The notebook will be imported/exported as a Jupyter/IPython Notebook file. |
DBCDBC | 笔记本将以 Databricks 存档格式导入/导出。The notebook will be imported/exported as Databricks archive format. |
语言 Language
笔记本的语言。The language of notebook.
语言Language | 说明Description |
---|---|
SCALASCALA | Scala 笔记本。Scala notebook. |
PYTHONPYTHON | Python 笔记本。Python notebook. |
SQLSQL | SQL 笔记本。SQL notebook. |
RR | R 笔记本。R notebook. |
ObjectType ObjectType
工作区中对象的类型。The type of the object in workspace.
类型Type | 描述Description |
---|---|
NOTEBOOKNOTEBOOK | 笔记本Notebook |
目录DIRECTORY | DirectoryDirectory |
LIBRARYLIBRARY | 库Library |