REST API 1.2 REST API 1.2

Azure Databricks REST API を使用すると、Web UI を使用するのではなく、プログラムによって Azure Databricks にアクセスできます。The Azure Databricks REST API allows you to programmatically access Azure Databricks instead of going through the web UI.

このトピックでは、REST API 1.2 について説明します。This topic covers REST API 1.2. ほとんどのユース ケースでは、REST API 2.0 を使用することをお勧めします。For most use cases, we recommend using the REST API 2.0. これは 1.2 API のほとんどの機能に加えて、追加機能をサポートしています。It supports most of the functionality of the 1.2 API, as well as additional functionality.

REST API のユース ケースREST API use cases

  • 既存の実稼働システムまたはワークフロー システムからトリガーされた Apache Spark ジョブを開始します。Start Apache Spark jobs triggered from your existing production systems or from workflow systems.
  • プログラムを使用して、特定のサイズのクラスターを 1 日の決まった時間に起動し、夜間にシャットダウンします。Programmatically bring up a cluster of a certain size at a fixed time of day and then shut it down at night.

API のカテゴリAPI categories

  • 実行コンテキスト: Spark コマンドを呼び出すことができる一意の変数名前空間を作成します。Execution context: create unique variable namespaces where Spark commands can be called.
  • コマンド実行: 特定の実行コンテキスト内でコマンドを実行します。Command execution: run commands within a specific execution context.

詳細Details

  • この REST API は HTTPS 経由で実行されます。This REST API runs over HTTPS.
  • 情報を取得するには、HTTP GET を使用します。For retrieving information, use HTTP GET.
  • 状態を変更するには、HTTP POST を使用します。For modifying state, use HTTP POST.
  • ファイルをアップロードするには、multipart/form-data を使用します。For file upload, use multipart/form-data. それ以外の場合は application/json を使用します。Otherwise use application/json.
  • 応答のコンテンツ タイプは JSON です。The response content type is JSON.
  • 基本認証は、すべての API 呼び出しに対してユーザーを認証するために使用されます。Basic authentication is used to authenticate the user for every API call.
  • ユーザー資格情報は base64 でエンコードされ、すべての API 呼び出しの HTTP ヘッダーにあります。User credentials are base64 encoded and are in the HTTP header for every API call. たとえば、「 Authorization: Basic YWRtaW46YWRtaW4= 」のように入力します。For example, Authorization: Basic YWRtaW46YWRtaW4=.

作業開始Get started

次の例では、<databricks-instance> を Azure Databricks デプロイの <region>.azuredatabricks.net ドメイン名に置き換えます。In the following examples, replace <databricks-instance> with the <region>.azuredatabricks.net domain name of your Azure Databricks deployment.

接続をテストするTest your connection

> telnet <databricks-instance> 443

Trying 52.11.163.202...
Connected to <databricks-instance>.
Escape character is '^]'.

> nc -v -z <databricks-instance> 443
found 1 connections:
     1: flags=82<CONNECTED,PREFERRED>
    outif utun0
    src x.x.x.x port 59063
    dst y.y.y.y port 443
    rank info not available
    TCP aux info available

Connection to <databricks-instance> port 443 [TCP/HTTPS] succeeded!

上記のいずれかのツールを使用して接続をテストできます。You can use either tool above to test the connection. ポート 443 は既定の HTTPS ポートであり、このポートで REST API を実行できます。Port 443 is default HTTPS port and you can run the REST API on this port. ポート 443 に接続できない場合は、ご利用のアカウントの URL を添えて help@databricks.com にお問い合わせください。If you cannot connect to port 443, contact help@databricks.com with your account URL.

サンプルの API 呼び出しSample API calls

ここでは、いくつかのサンプル cURL コマンドについて説明しますが、任意のプログラミング言語で HTTP ライブラリを使用することもできます。We cover some sample cURL commands below, but you can also use an HTTP library in your programming language of choice.

GET 要求GET request

注意

URL に & 文字が含まれている場合、UNIX でコマンドの区切り記号として解釈されないように、その URL を引用符で囲む必要があります。If your URL has the & character in it you must quote that URL so UNIX doesn’t interpret it as a command separator:

curl -n 'https://<databricks-instance>/api/1.2/commands/status?clusterId=batVenom&contextId=35585555555555&commandId=45382422555555555'

application/json を使用した POST 要求POST request with application/json

curl -X POST -n https://<databricks-instance>/api/1.2/contexts/create -d "language=scala&clusterId=batVenom"

カテゴリ別 API エンドポイントAPI endpoints by category

実行コンテキスト Execution context

  • https://<databricks-instance>/api/1.2/contexts/create – 特定のプログラミング言語について、指定したクラスターに実行コンテキストを作成しますhttps://<databricks-instance>/api/1.2/contexts/create – create an execution context on a specified cluster for a given programming language

    • application/json を使用した POST 要求:POST request with application/json:
      • datadata

        {"language": "scala", "clusterId": "peaceJam"}
        
  • https://<databricks-instance>/api/1.2/contexts/status – 既存の実行コンテキストの状態を示しますhttps://<databricks-instance>/api/1.2/contexts/status – show the status of an existing execution context

    • GET 要求:GET request:
      • 引数の例: clusterId=peaceJam&contextId=179365396413324Example arguments: clusterId=peaceJam&contextId=179365396413324
      • status: ["Pending", "Running", "Error"]status: ["Pending", "Running", "Error"]
  • https://<databricks-instance>/api/1.2/contexts/destroy – 実行コンテキストを破棄しますhttps://<databricks-instance>/api/1.2/contexts/destroy – destroy an execution context

    • application/json を使用した POST 要求:POST request with application/json:
      • datadata

        {"contextId" : "1793653964133248955", "clusterId" : "peaceJam"}
        

コマンド実行Command execution

既知の制限: コマンド実行は %run をサポートしません。Known limitations: command execution does not support %run.

  • https://<databricks-instance>/api/1.2/commands/execute – コマンドまたはファイルを実行します。https://<databricks-instance>/api/1.2/commands/execute – run a command or file.

    • application/json を使用した POST 要求:POST request with application/json:

      • datadata

        {"language": "scala", "clusterId": "peaceJam", "contextId" : "5456852751451433082", "command": "sc.parallelize(1 to 10).collect"}
        
    • multipart/form-data を使用した POST 要求:POST request with multipart/form-data:

      • datadata

        {"language": "python", "clusterId": "peaceJam", "contextId" : "5456852751451433082"}
        
      • ファイルのアップロードfiles

        {"command": "./myfile.py"}
        
  • https://<databricks-instance>/api/1.2/commands/status – 1 つのコマンドの状態または結果を示しますhttps://<databricks-instance>/api/1.2/commands/status – show one command’s status or result

    • GET 要求GET Request
      • 引数の例: clusterId=peaceJam&contextId=5456852751451433082&commandId=5220029674192230006Example arguments: clusterId=peaceJam&contextId=5456852751451433082&commandId=5220029674192230006
      • status:["Queued", "Running", "Cancelling", "Finished", "Cancelled", "Error"]status:["Queued", "Running", "Cancelling", "Finished", "Cancelled", "Error"]
  • https://<databricks-instance>/api/1.2/commands/cancel – 1 つのコマンドをキャンセルしますhttps://<databricks-instance>/api/1.2/commands/cancel – cancel one command

    • application/json を使用した POST 要求:POST request with application/json:
      • datadata

        {"clusterId": "peaceJam", "contextId" : "5456852751451433082", "commandId" : "2245426871786618466"}
        

例:Spark JAR をアップロードして実行するExample: Upload and run a Spark JAR

JAR をアップロードするUpload a JAR

  1. JAR をアップロードしてクラスターに添付するには、REST API 2.0 を使用します。Use the REST API 2.0 to upload a JAR and attach it to a cluster.

JAR を実行するRun a JAR

  1. 実行コンテキストを作成します。Create an execution context.

    curl -X POST -n  https://<databricks-instance>/api/1.2/contexts/create -d "language=scala&clusterId=batVenom"
    
    {
      "id": "3558513128163162828"
    }
    
  2. JAR を使用するコマンドを実行します。Execute a command that uses your JAR.

    curl -X POST -n https://<databricks-instance>/api/1.2/commands/execute \
    -d 'language=scala&clusterId=batVenom&contextId=3558513128163162828&command=println(com.databricks.apps.logs.chapter1.LogAnalyzer.processLogFile(sc,null,"dbfs:/somefile.log"))'
    
    {
      "id": "4538242203822083978"
    }
    
  3. コマンドの状態を確認します。Check on the status of your command. 長い Spark ジョブを実行している場合、すぐには処理が戻らないことがあります。It may not return immediately if you are running a lengthy Spark job.

    curl -n 'https://<databricks-instance>/api/1.2/commands/status?clusterId=batVenom&contextId=3558513128163162828&commandId=4538242203822083978'
    
    {
       "id": "4538242203822083978",
       "results": {
         "data": "Content Size Avg: 1234, Min: 1234, Max: 1234",
         "resultType": "text"
       },
       "status": "Finished"
    }