工作区 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_EXISTIf path does not exist, this call returns an error RESOURCE_DOES_NOT_EXIST. 如果 path 为非空目录且 recursive 设置为 false,则此调用会返回错误 DIRECTORY_NOT_EMPTYIf 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. 默认情况下,它为 falseIt 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_EXISTIf 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_EXCEEDEDIf 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 部署的工作区 URLIn 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. 默认情况下,该属性为 SOURCEBy 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_EXISTIf 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. 它可以是 NOTEBOOKDIRECTORYLIBRARYIt could be NOTEBOOK, DIRECTORY or LIBRARY.
object_idobject_id INT64 NOTEBOOKDIRECTORY 的唯一标识符。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_EXISTSIf 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. 请求的示例,其中 content1+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 部署的工作区 URLIn 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. 默认情况下,该属性为 SOURCEBy 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. 默认情况下,它为 falseIt 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_EXISTIf 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_EXISTSIf 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. 它由 listget-status 返回。It is returned by list and get-status.

字段名称Field Name 类型Type 说明Description
object_typeobject_type ObjectTypeObjectType 对象的类型。The type of the object. 它可以是 NOTEBOOKDIRECTORYLIBRARYIt could be NOTEBOOK, DIRECTORY or LIBRARY.
object_idobject_id INT64 NOTEBOOKDIRECTORY 的唯一标识符。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