SQL Endpoint 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 エンドポイント APIを使用します。To configure individual SQL endpoints, use the SQL Endpoints API. すべての SQL エンドポイントを構成するには、 グローバル SQL エンドポイント APIを使用します。To configure all SQL endpoints, use the Global SQL Endpoints API.

SQL Endpoints 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 TypeType 説明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. マルチクラスターの負荷分散が有効になっていない場合、これはに限定され 1 ます。If 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.
tagstags 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 TypeType 説明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. マルチクラスターの負荷分散が有効になっていない場合は、に制限され 1 ます。If 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.
tagstags 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 TypeType 説明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 JDBC を使用して sql のエンドポイントに 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.
tagstags 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"
}

ListList

エンドポイント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.

StopStop

エンドポイント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 TypeType DescriptionDescription
security_policysecurity_policy EndpointSecurityPolicyEndpointSecurityPolicy データセットへのアクセスを制御するためのポリシー。The policy for controlling access to datasets.
data_access_configdata_access_config Endpointconfpairの配列Array of EndpointConfPair 外部 Hive metastoreのプロパティを含むキーと値のペアの配列。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 TypeType DescriptionDescription
security_policysecurity_policy EndpointSecurityPolicyEndpointSecurityPolicy データセットへのアクセスを制御するためのポリシー。The policy for controlling access to datasets.
data_access_configdata_access_config Endpointconfpairの配列Array of EndpointConfPair 外部 Hive metastoreのプロパティを含むキーと値のペアの配列。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 TypeType 説明Description
keykey STRING 構成キー名。Configuration key name.
value STRING 構成キーの値。Configuration key value.

EndpointHealthEndpointHealth

フィールド名Field Name TypeType 説明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
StateState DescriptionDescription
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

StateState DescriptionDescription
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 TypeType DescriptionDescription
custom_tagscustom_tags Endpointtagpairの配列Array of EndpointTagPair キーと値のペアの配列を格納しているオブジェクト。An object containing an array of key-value pairs.

EndpointTagPairEndpointTagPair

フィールド名Field Name TypeType 説明Description
keykey STRING タグキー名。Tag key name.
value STRING タグキー値。Tag key value.

Odbcparams ODBCParams

フィールド名Field Name TypeType DescriptionDescription
ホストhost STRING ODBC サーバーのホスト名。ODBC server hostname.
pathpath STRING ODBC サーバーパス。ODBC server path.
protocolprotocol STRING ODBC サーバープロトコル。ODBC server protocol.
portport INT32 ODBC サーバーポートODBC server port