Databricks Genie API と API ワークフローの統合

Databricks Genie を使用すると、エンタープライズ データとの自然言語による対話が可能になり、コードを記述することなくデータセットのクエリ、分析、操作を行うことができます。

このガイドでは、Databricks Genie API を操作して、質問入力に基づいて情報を取得する方法の実用的なチュートリアルを提供します。以下の主なアクションを実行します。

• 変数を初期化します—トークン、URL、ID などの必要なパラメーターを設定します。
• トークンの取得 — HTTP POST 要求を実行して、認証用のアクセス トークンを取得します。
• 会話の開始 - ユーザーの質問を Genie API に送信して会話を開始します。
• メッセージ補完のポーリング: Do While ループに入り、COMPLETED になるまで Genie メッセージのステータスを繰り返しチェックします。

• クエリ結果の取得 - メッセージが完了すると、Genie API から最終的なクエリ結果が取得され、取得したデータがワークフローの出力として提供されます。

前提条件

まず、Databricks ワークスペースに "Item Restrictions" という Genie スペースが必要です。

その目的は、さまざまな製品の配送制限を参照し、配送の詳細に関する回答を提供することです。

1. API ワークフローを作成します。
2. ワークフローの入力を定義します。データ マネージャーを開き、次の設定で新しい [入力] パラメーターを追加します。
   • 名前 - 質問
   • 型 - String
   • [必須] としてマークします。
3. ワークフロー変数を定義します。[データ マネージャー] > [変数] を開き、以下を追加します。
   • token (String)—Databricks Genie API にアクセスするために必要な認証トークンを格納します。
   • conversation_id (String)—Databricks Genie API との特定の会話セッションを追跡します。会話を開始すると、API によってこの ID が提供され、これを使用して後続の要求で進行中の会話を参照します。
   • message_id (String)—会話内の特定のメッセージを指します。次に、この ID を使用して、その特定のメッセージ処理の状態と、最終的には結果を取得します。
   • attachment_id (String)—Genie API のメッセージに関連付けられた特定の添付ファイル (この場合はクエリ結果を保持する) を指します。
   • url (String)— Databricks Genie API エンドポイントのベース URL を格納します。
   • space_id (String)—Databricks Genie 内の特定のスペースを指します。
4. アクセス トークンを取得する HTTP アクティビティを追加し、次のように設定します。
   • 表示名 - 「Get token HTTP Request」
   • メソッド - POST
   • 要求 URL —https://accounts.cloud.databricks.com/oidc/accounts/{account_id}/v1/token
   • ヘッダー—

     {
     "Authorization": "Basic <your_basic_token>",
     "Content-Type": "application/x-www-form-urlencoded"
     }

   • 要求本文—

     "grant_type=client_credentials&scope=all-apis"

   このアクティビティのコンテキスト出力名は HTTP_Request_1です。
5. 前のアクティビティから取得したトークンを token 変数に割り当てます。[代入] アクティビティを追加し、次のように設定します。
   • 変数 -token
   • 値を設定—$context.outputs.HTTP_Request_1.content.access_token

   コンテキスト出力名の HTTP_Request_1 は、ワークフローで使用されているものとは異なる場合があります。
6. 会話を開始する ための HTTP アクティビティを追加し、次のように設定します。
   • 表示名 - 「会話の開始 HTTP 要求」
   • メソッド - POST
   • 要求 URL —https://{your-databricks-instance}/api/2.0/genie/spaces/{space_id}/start-conversationを使用するか、式エディターを使用して次のように構築します。

     $context.variables.url + "/api/2.0/genie/spaces/"+ $context.variables.space_id +"/start-conversation"

   • ヘッダー—

     {"Authorization": "Bearer " + $context.variables.token}

   • 要求本文—

     {"content": $workflow.input.question}

   出力が保存されていることを確認します。このアクティビティの出力から conversation_id と message_id を取得できます。

   このアクティビティのコンテキスト出力名は HTTP_Request_2です。
7. ループを入力して、COMPLETEDまでGenieメッセージのステータスを確認します。[ 繰り返し (後判定 )] アクティビティを追加し、[ 条件 ] を $context.outputs.HTTP_Request_3?.content?.status !== "COMPLETED"に設定します。ここで HTTP_Request_3 は [メッセージを取得] の HTTP 要求アクティビティを指します。つまり、メッセージの状態が COMPLETED でない限り、ループは継続します。
8. [繰り返し (後判定)] ループ内
   1. 最後のメッセージを取得するための [HTTP ] アクティビティを追加し、次のように設定します。
      • 表示名 - 「メッセージの取得 HTTP 要求」
      • メソッド - GET
      • 要求 URL —https://{your-databricks-instance}/api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}を使用するか、式エディターを使用して次のように構築します。

        [ $context.variables.url+"/api/2.0/genie/spaces/"+$context.variables.space_id+"/conversations/", $context.outputs.HTTP_Request_2.content.conversation_id, "/messages/", $context.outputs.HTTP_Request_2.content.message_id ].join('')

        ここでの HTTP_Request_2 は、[会話を開始] の [HTTP 要求] アクティビティを指します。
      • ヘッダー—

        {"Authorization": "Bearer " + $context.variables.token}

      • 要求本文—

        {"content": $workflow.input.question}

      このアクティビティのコンテキスト出力名は HTTP_Request_3です。
   2. [メッセージの HTTP 要求を取得] アクティビティの直後に [条件分岐 (if )] アクティビティを追加し、[ 条件 ] を $context.outputs.HTTP_Request_3?.content?.status === "COMPLETED"に設定します。ここで HTTP_Request_3 は [メッセージの HTTP 要求を取得] アクティビティを指します。
   3. [Then] (true) 分岐に [代入] アクティビティを追加し、次のように設定します。
      • 変数 -conversation_id
      • 値を設定 —$context.outputs.HTTP_Request_3.content.conversation_id。 HTTP_Request_3 は [メッセージを取得] の [HTTP 要求を取得] アクティビティを指します。
   4. もう 1 つ [代入] アクティビティを追加します。
      • 変数 -message_id
      • 値を設定 —$context.outputs.HTTP_Request_3.content.message_id。 HTTP_Request_3 は [メッセージを取得] の [HTTP 要求を取得] アクティビティを指します。
   5. もう 1 つ [代入] アクティビティを追加します。
      • 変数 -attachment_id
      • 値を設定 —$context.outputs.HTTP_Request_3.content.attachments[0].attachment_id。 HTTP_Request_3 は [メッセージを取得] の [HTTP 要求を取得] アクティビティを指します。
   6. [Else] 分岐に [待機] アクティビティを追加し、[期間] を 1 秒に設定します。これにより、ワークフローは短時間待機してから再試行するよう指示されます。
9. ループを終了し、SQL クエリを実行する HTTP アクティビティを追加して、次のように設定します。
   • 表示名 - 「SQL HTTP 要求を実行」
   • メソッド - GET
   • 要求 URL —https://{your-databricks-instance}/api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/attachments/{attachment_id}/query-resultを使用するか、式エディターを使用して次のように構築します。

     $context.variables.url+"/api/2.0/genie/spaces/"+$context.variables.space_id+"/conversations/" + $context.variables.conversation_id + "/messages/"  + $context.variables.message_id + "/attachments/" +  $context.variables.attachment_id + "/query-result"

   • ヘッダー—

     {"Authorization": "Bearer " + $context.variables.token}

   このアクティビティのコンテキスト出力名は HTTP_Request_3です。
10. ワークフローの出力を定義します。データ マネージャーを開き、次の入力パラメーターを追加します。
    • 名前 - row_count
    • [タイプ] - 数値
    • [必須] としてマークします。

    ] と [

    • 名前 - data_array
    • タイプ - 配列
    • [必須] としてマークします。
11. [応答] アクティビティを追加し、次のように設定します。
    • 応答—

      {
        "row_count": -75647404.57028332,
        "data_array": [
          [],
          [],
          [
            "ut et aute officia",
            "ex ut",
            "nisi non ut Lorem velit",
            "aliquip Duis consectetur irure id"
          ]
        ]
      }

12. 連携を実行します。デプロイされたワークフローは、任意の自然言語クエリで呼び出すことができます。質問の例は、「キューバへのSKU ENB-SP-200の出荷に制限はありますか?」です。

重要なポイント:

1. 簡単なセットアップ – APIワークフローは、カスタムコードなしでGenieを接続するための迅速な方法を提供します。
2. 一貫性のあるスキーマ – Genie の応答は JSON ベースであり、UiPath に容易に解析できます。
3. スケーラブルな連携 – 応答は Apps、長期実行のワークフロー、またはオーケストレーションで使用できます。
4. ラピッドプロトタイピング – 実用的なオートメーションのセットアップは数分で完了し、ユースケースを迅速に検証できます。