SQL 终结点 APISQL Endpoint APIs

重要

此功能以个人预览版提供。This feature is in Private Preview. 若要试用,请与 Azure Databricks 联系人取得联系。To try it, reach out to your Azure Databricks contact.

重要

要访问 Databricks REST API,必须进行身份验证To access Databricks REST APIs, you must authenticate.

要求Requirements

  • 若要创建 SQL 终结点,必须在 Azure Databricks 工作区中具有群集创建权限To create SQL endpoints you must have cluster create permission in Azure Databricks Workspace.
  • 若要管理 SQL 终结点,必须在 Azure Databricks SQL Analytics 中具有该终结点的可管理权限。To manage a SQL endpoint you must have Can Manage permission in Azure Databricks SQL Analytics for the endpoint.

若要配置单个 SQL 终结点,请使用 SQL 终结点 APITo configure individual SQL endpoints, use the SQL Endpoints API. 若要配置所有 SQL 终结点,请使用 全局 SQL 终结点 APITo configure all SQL endpoints, use the Global SQL Endpoints API.

SQL 终结点 APISQL Endpoints API

使用此 API 创建、编辑、列出和获取 SQL 终结点。Use this API to create, edit, list, and get SQL endpoints.

本节内容:In this section:

创建Create

端点Endpoint HTTP 方法HTTP Method
2.0/sql/endpoints/ POST

创建 SQL 终结点。Create a SQL endpoint.

字段名称Field Name 类型Type 说明Description
namename STRING SQL 终结点的名称。Name of the SQL endpoint. 必须是唯一的。Must be unique. 此字段为必需字段。This field is required.
cluster_sizecluster_size String 分配给终结点的群集大小:"2X-Small""X-Small""Small""Medium""Large""X-Large""2X-Large""3X-Large""4X-Large"The size of the clusters allocated to the endpoint: "2X-Small", "X-Small", "Small", "Medium", "Large", "X-Large", "2X-Large", "3X-Large", "4X-Large". 有关从群集到实例大小的映射,请参阅群集大小For the mapping from cluster to instance size, see Cluster size. 此字段为必需字段。This field is required.
min_num_clustersmin_num_clusters INT32 SQL 终结点运行时可用的最小群集数。Minimum number of clusters available when a SQL endpoint is running. 默认值为 1。The default is 1.
max_num_clustersmax_num_clusters INT32 SQL 终结点运行时可用的最大群集数。Maximum number of clusters available when a SQL endpoint is running. 此字段为必需字段。This field is required. 如果未启用多群集负载均衡,则限制为 1If multi-cluster load balancing is not enabled, this is limited to 1.
auto_stop_minsauto_stop_mins INT32 在空闲的 SQL 终结点终止所有群集并停止之前等待的时间(以分钟为单位)。Time in minutes until an idle SQL endpoint terminates all clusters and stops. 此字段是可选的。This field is optional. 默认值为 0,表示禁用自动停止。The default is 0, which means auto stop is disabled.
标记tags EndpointTagsEndpointTags 描述终结点的键值对。Key-value pairs that describe the endpoint. Azure Databricks 使用这些标记来标记所有终结点资源。Azure Databricks tags all endpoint resources with these tags. 此字段是可选的。This field is optional.
enable_photonenable_photon BOOLEAN 决定是否在可加快查询执行的本机向量化引擎上执行查询。Whether queries are executed on a native vectorized engine that speeds up query execution. 此字段是可选的。This field is optional.

示例请求Example request

{
  "name": "My SQL Endpoint",
  "cluster_size": "Medium",
  "min_num_clusters": 1,
  "max_num_clusters": 10,
  "tags": {
    "custom_tags": [
      {
        "key": "mykey",
        "value": "myvalue"
      }
    ]
  },
  "enable_photon": "true"
}

示例响应Example response

{
  "id": "0123456789abcdef"
}

删除Delete

端点Endpoint HTTP 方法HTTP Method
2.0/sql/endpoints/{id} DELETE

删除 SQL 终结点。Delete a SQL endpoint.

编辑Edit

端点Endpoint HTTP 方法HTTP Method
2.0/sql/endpoints/{id}/edit POST

修改 SQL 终结点。Modify a SQL endpoint. 所有字段都是可选的。All fields are optional. 缺失字段默认为当前值。Missing fields default to the current values.

字段名称Field Name 类型Type 说明Description
idid STRING SQL 终结点的 ID。ID of the SQL endpoint.
namename STRING SQL 终结点的名称。Name of the SQL endpoint.
cluster_sizecluster_size String 分配给终结点的群集大小:"2X-Small""X-Small""Small""Medium""Large""X-Large""2X-Large""3X-Large""4X-Large"The size of the clusters allocated to the endpoint: "2X-Small", "X-Small", "Small", "Medium", "Large", "X-Large", "2X-Large", "3X-Large", "4X-Large". 有关从群集到实例大小的映射,请参阅群集大小For the mapping from cluster to instance size, see Cluster size.
min_num_clustersmin_num_clusters INT32 SQL 终结点运行时可用的最小群集数。Minimum number of clusters available when a SQL endpoint is running.
max_num_clustersmax_num_clusters INT32 SQL 终结点运行时可用的最大群集数。Maximum number of clusters available when a SQL endpoint is running. 此字段为必需字段。This field is required. 如果未启用多群集负载均衡,则限制为 1If multi-cluster load balancing is not enabled, limited to 1.
auto_stop_minsauto_stop_mins INT32 在空闲的 SQL 终结点终止所有群集并停止之前等待的时间(以分钟为单位)。Time in minutes until an idle SQL endpoint terminates all clusters and stops.
标记tags EndpointTagsEndpointTags 描述终结点的键值对。Key-value pairs that describe the endpoint.
enable_photonenable_photon BOOLEAN 决定是否在可加快查询执行的本机向量化引擎上执行查询。Whether queries are executed on a native vectorized engine that speeds up query execution.

示例请求Example request

{
  "name": "My Edited SQL endpoint",
  "cluster_size": "Large",
  "auto_stop_mins": 60
}

获取Get

端点Endpoint HTTP 方法HTTP Method
2.0/sql/endpoints/{id} GET

检索 SQL 终结点的信息。Retrieve the info for a SQL endpoint.

字段名称Field Name 类型Type 说明Description
idid STRING SQL 终结点 ID。SQL endpoint ID.
namename STRING SQL 终结点的名称。Name of the SQL endpoint.
cluster_sizecluster_size String 分配给终结点的群集大小:"2X-Small""X-Small""Small""Medium""Large""X-Large""2X-Large""3X-Large""4X-Large"The size of the clusters allocated to the endpoint: "2X-Small", "X-Small", "Small", "Medium", "Large", "X-Large", "2X-Large", "3X-Large", "4X-Large". 有关从群集到实例大小的映射,请参阅群集大小For the mapping from cluster to instance size, see Cluster size.
auto_stop_minsauto_stop_mins INT32 在空闲的 SQL 终结点终止所有群集并停止之前等待的时间。Time until an idle SQL endpoint terminates all clusters and stops.
num_clustersnum_clusters INT32 分配给终结点的群集数。Number of clusters allocated to the endpoint.
min_num_clustersmin_num_clusters INT32 SQL 终结点运行时可用的最小群集数。Minimum number of clusters available when a SQL endpoint is running.
max_num_clustersmax_num_clusters INT32 SQL 终结点运行时可用的最大群集数。Maximum number of clusters available when a SQL endpoint is running.
num_active_sessionsnum_active_sessions INT32 SQL 终结点上运行的 JDBC 和 ODBC 活动会话的数目。Number of active JDBC and ODBC sessions running on the SQL endpoint.
statestate EndpointStateEndpointState SQL 终结点的状态。State of the SQL endpoint.
creator_namecreator_name STRING 创建终结点的用户的电子邮件地址。Email address of the user that created the endpoint.
creator_idcreator_id STRING 创建终结点的用户的 Azure Databricks ID。Azure Databricks ID of the user that created the endpoint.
jdbc_urljdbc_url STRING 用于将 SQL 命令提交到使用 JDBC 的 SQL 终结点的 URL。The URL used to submit SQL commands to the SQL endpoint using JDBC.
odbc_paramsodbc_params ODBCParamsODBCParams 使用 ODBC 向 SQL 终结点提交 SQL 命令所需的主机、路径、协议和端口信息。The host, path, protocol, and port information required to submit SQL commands to the SQL endpoint using ODBC.
标记tags EndpointTagsEndpointTags 描述终结点的键值对。Key-value pairs that describe the endpoint.
healthhealth EndpointHealthEndpointHealth 终结点的运行状况。The health of the endpoint.
enable_photonenable_photon BOOLEAN 决定是否在可加快查询执行的本机向量化引擎上执行查询。Whether queries are executed on a native vectorized engine that speeds up query execution.

示例响应Example response

{
  "id": "7f2629a529869126",
  "name": "MyEndpoint",
  "size": "SMALL",
  "min_num_clusters": 1,
  "max_num_clusters": 1,
  "auto_stop_mins": 0,
  "auto_resume": true,
  "num_clusters": 0,
  "num_active_sessions": 0,
  "state": "STOPPED",
  "creator_name": "user@example.com",
  "jdbc_url": "jdbc:spark://hostname.staging.cloud.databricks.com:443/default;transportMode=http;ssl=1;AuthMech=3;httpPath=/sql/1.0/endpoints/7f2629a529869126;",
  "odbc_params": {
    "hostname": "hostname.cloud.databricks.com",
    "path": "/sql/1.0/endpoints/7f2629a529869126",
    "protocol": "https",
    "port": 443
  },
  "tags": {
    "custom_tags": [
      {
        "key": "mykey",
        "value": "myvalue"
      }
    ]
  },
  "enable_photon": true,
  "cluster_size": "Small"
}

列表List

端点Endpoint HTTP 方法HTTP Method
2.0/sql/endpoints/ GET

列出工作区中的所有 SQL 终结点。List all SQL endpoints in the workspace.

示例响应Example response

{
  "endpoints": [
    { "id": "123456790abcdef", "name": "My SQL endpoint", "cluster_size": "Medium", },
    { "id": "098765321fedcba", "name": "Another SQL endpoint", "cluster_size": "Large", }
  ]
}

开始Start

端点Endpoint HTTP 方法HTTP Method
2.0/sql/endpoints/{id}/start POST

启动 SQL 终结点。Start a SQL endpoint.

停止Stop

端点Endpoint HTTP 方法HTTP Method
2.0/sql/endpoints/{id}/stop POST

停止 SQL 终结点。Stop a SQL endpoint.

全局 SQL 终结点 APIGlobal SQL Endpoints API

使用此 API 为所有 SQL 终结点配置安全策略和数据访问。Use this API to configure the security policy and data access for all SQL endpoints.

本节内容:In this section:

获取Get

端点Endpoint HTTP 方法HTTP Method
/2.0/sql/config/endpoints GET

获取所有 SQL 终结点的配置。Get the configuration for all SQL endpoints.

字段名称Field Name 类型Type 说明Description
security_policysecurity_policy EndpointSecurityPolicyEndpointSecurityPolicy 用于控制对数据集的访问的策略。The policy for controlling access to datasets.
data_access_configdata_access_config EndpointConfPair 的数组Array of EndpointConfPair 一个由包含外部 Hive 元存储属性的键值对构成的数组。An array of key-value pairs containing properties for an external Hive metastore.

示例响应Example response

{
  "security_policy": "DATA_ACCESS_CONTROL",
  "data_access_config": [
    {
      "key": "spark.sql.hive.metastore.jars",
      "value": "/databricks/hive_metastore_jars/*"
    }
  ],
}

编辑Edit

编辑所有 SQL 终结点的配置。Edit the configuration for all SQL endpoints.

重要

  • 所有字段都是必填字段。All fields are required.
  • 调用此方法可重启所有正在运行的 SQL 终结点。Invoking this method restarts all running SQL endpoints.
端点Endpoint HTTP 方法HTTP Method
/2.0/sql/config/endpoints PUT
字段名称Field Name 类型Type 说明Description
security_policysecurity_policy EndpointSecurityPolicyEndpointSecurityPolicy 用于控制对数据集的访问的策略。The policy for controlling access to datasets.
data_access_configdata_access_config EndpointConfPair 的数组Array of EndpointConfPair 一个由包含外部 Hive 元存储属性的键值对构成的数组。An array of key-value pairs containing properties for an external Hive metastore.

示例请求Example request

{
  "data_access_config": [
    {
      "key": "spark.sql.hive.metastore.jars",
      "value": "/databricks/hive_metastore_jars/*"
    }
  ],
}

数据结构Data structures

本节内容:In this section:

EndpointConfPairEndpointConfPair

字段名称Field Name 类型Type 描述Description
keykey STRING 配置键名称。Configuration key name.
value STRING 配置键值。Configuration key value.

EndpointHealthEndpointHealth

字段名称Field Name 类型Type 说明Description
statusstatus EndpointStatusEndpointStatus 终结点状态。Endpoint status.
messagemessage STRING 有关运行状况的描述性消息。A descriptive message about the health status. 包含有关导致当前运行状况的错误的信息。Includes information about errors contributing to current health status.

EndpointSecurityPolicyEndpointSecurityPolicy

选项Option 说明Description
DATA_ACCESS_CONTROL 使用数据访问控制来控制对数据集的访问。Use data access control to control access to datasets.

EndpointState EndpointState

SQL 终结点的状态。State of a SQL endpoint. 可允许的状态转换如下:The allowable state transitions are:

  • STARTING -> STARTING, RUNNING, STOPPING, DELETINGSTARTING -> STARTING, RUNNING, STOPPING, DELETING
  • RUNNING -> STOPPING, DELETINGRUNNING -> STOPPING, DELETING
  • STOPPING -> STOPPED, STARTINGSTOPPING -> STOPPED, STARTING
  • STOPPED -> STARTING, DELETINGSTOPPED -> STARTING, DELETING
  • DELETING -> DELETED
状态State 说明Description
STARTING 正在启动终结点。The endpoint is in the process of starting.
RUNNING 启动过程已完成,终结点已可供使用。The starting process is done and the endpoint is ready to use.
STOPPING 正在停止终结点。The endpoint is in the process of being stopped.
STOPPED 终结点已停止。The endpoint is stopped. 首先调用 start 或者提交 JDBC 或 ODBC 请求。Start by calling start or by submitting a JDBC or ODBC request.
DELETING 正在销毁终结点。The endpoint is in the process of being destroyed.
DELETED 终结点已被删除并且无法恢复。The endpoint has been deleted and cannot be recovered.

EndpointStatusEndpointStatus

状态State 说明Description
HEALTHY 终结点正常运行,无已知问题。Endpoint is functioning normally and there are no known issues.
DEGRADED 终结点可能正常运行,但存在一些已知问题。Endpoint might be functional, but there are some known issues. 性能可能会受到影响。Performance might be affected.
FAILED 终结点受到严重影响,无法为查询提供服务。Endpoint is severely affected and will not be able to serve queries.

EndpointTagsEndpointTags

字段名称Field Name 类型Type 说明Description
custom_tagscustom_tags EndpointTagPair 的数组Array of EndpointTagPair 一个包含键值对数组的对象。An object containing an array of key-value pairs.

EndpointTagPairEndpointTagPair

字段名称Field Name 类型Type 描述Description
keykey STRING 标记键名称。Tag key name.
value STRING 标记键值。Tag key value.

ODBCParams ODBCParams

字段名称Field Name 类型Type 说明Description
hosthost STRING ODBC 服务器主机名。ODBC server hostname.
pathpath STRING ODBC 服务器路径。ODBC server path.
protocolprotocol STRING ODBC 服务器协议。ODBC server protocol.
portport INT32 ODBC 服务器端口ODBC server port