メインコンテンツまでスキップ
に最終更新

スキル API および SDK リファレンス

備考

ベータ版

この機能はベータ版です。アカウント管理者は、アカウント コンソールの [プレビュー] ページからこの機能へのアクセスを管理できます。アカウントレベルのプレビューの管理を参照してください。

これらの例を使用して、スキル管理を自動化してください。APIは各スキルを、skills/{catalog}.{schema}.{skill}という名前のSkillリソースとして表します。エージェントを使用したスキルの作成と公開については、スキルの作成と共有を参照してください。権限とガバナンスについては、スキルのガバナンスを参照してください。スキルには、Terraformリソースも宣言型オートメーションバンドルのリソースもありません。

前提条件​

  • スキル用のガバナンス対象スキーマを設定します。

  • 操作に必要な権限を持っていることを確認してください。

  • 使用するクライアントをインストールして認証します。REST APIにバージョン要件はありません。各ツールとSDKには最小バージョンがあります：

    SDKスニペットでは、認証済みのワークスペースクライアントwを前提とします；Modular SDKスニペットでは、GoのcおよびJavaScriptのclientで認証済みのUnity Gatewayクライアントを前提とします。

APIオペレーション​

「Skills REST API」は、次の操作を提供します。それぞれについて、親に対してUSE CATALOGおよびUSE SCHEMAも必要です。各Linkで、そのフィールド、権限、および応答を確認してください。

オペレーション

ユースケース

必要な権限

作成

スキルを作成し、そのバンドルストレージをプロビジョニングします。

CREATE VOLUME スキーマで

アップロード

Files APIを使用して、SKILL.mdと関連ファイルをuploadしてください。

WRITE VOLUME およびスキルのREAD VOLUME

完了する

SKILL.mdを読み込んで検証し、スキルのバンドル名と説明を設定します。

READ VOLUME スキルについて

リスト

スキーマ内でアクセスできるスキルを検索します。

READ VOLUME, スキルに対するREAD METADATA、またはMANAGE

取得

スキルのメタデータと現在のetagを読み取ります。

READ VOLUME, スキルに対するREAD METADATA、またはMANAGE

更新

スキルのコメントを変更します。

MANAGE スキルについて

削除

スキルとそのバンドルを削除します。

MANAGE スキルについて

オペレーション

ユースケース

必要な権限

作成

スキルを作成し、そのバンドルストレージをプロビジョニングします。

CREATE VOLUME スキーマで

アップロード

Files APIを使用して、SKILL.mdと関連ファイルをuploadしてください。

WRITE VOLUME およびスキルのREAD VOLUME

完了する

SKILL.mdを読み込んで検証し、スキルのバンドル名と説明を設定します。

READ VOLUME スキルについて

リスト

スキーマ内でアクセスできるスキルを検索します。

READ VOLUME, スキルに対するREAD METADATA、またはMANAGE

取得

スキルのメタデータと現在のetagを読み取ります。

READ VOLUME, スキルに対するREAD METADATA、またはMANAGE

更新

スキルのコメントを変更します。

MANAGE スキルについて

削除

スキルとそのバンドルを削除します。

MANAGE スキルについて

スキルの所有者は、そのスキルに対するこれらすべての権限を持ちます。「スキルへのアクセス権の付与」を参照してください。

スキルを作成​

スキルの作成には3つのステップがあります。スキルを作成し、そのバンドルをuploadしてから、スキルを完了します。スキルを完了するまでは、バンドル名と説明は空です。

ステップ 1：スキルを作成する​

スキーマ内にスキルを作成します。設定できるフィールドはcommentのみです。Databricksはname、bundle_name、descriptionを導出します。

main.default.my_skillとdata-teamを独自の値に置き換えます。

/api/2.1/unity-catalog/skillsにPOSTを送信し、parentとskill_idをクエリーパラメーターとして渡す場合：

Bash
databricks api post \
  "/api/2.1/unity-catalog/skills?parent=schemas/main.default&skill_id=my_skill" \
  --json '{"comment": "Team-shared math helper skill"}'

ステップ 2：バンドルをuploadする​

Files APIを使用して、SKILL.mdおよび関連ファイルをスキルのストレージパス/Skills/<catalog>/<schema>/<skill>/にuploadします。SKILL.mdは、nameとdescriptionを設定するYAML frontmatterで始まる必要があります。この例をSKILL.mdとして保存：

Markdown
---
name: my-skill
description: A team-shared skill that helps with basic math.
---

# My Skill

Step-by-step guidance the agent follows when this skill is loaded.

PUTをFiles APIに送信します。DATABRICKS_HOSTにワークスペースURL（例：https://my-workspace.cloud.databricks.com）を設定し、DATABRICKS_TOKENにトークンを設定します。この例では、プロセス一覧に表示されないように、標準入力からcurlにトークンを渡します：

Bash
curl --request PUT --config - --data-binary @SKILL.md \
  --header "Content-Type: application/octet-stream" \
  "${DATABRICKS_HOST}/api/2.0/fs/files/Skills/main/default/my_skill/SKILL.md?overwrite=true" \
  <<< "header = \"Authorization: Bearer ${DATABRICKS_TOKEN}\""

ステップ3：スキルを完了する​

確定処理では、SKILL.mdを読み込んで検証し、その後、frontmatterからスキルのbundle_nameとdescriptionを設定します。後でバンドルを変更した場合は、もう一度確定処理を実行してください。

Bash
databricks api post "/api/2.1/unity-catalog/skills/main.default.my_skill/finalize" --json '{}'

スキルを検索​

スキーマ内でアクセスできるスキルを一覧表示し、リソース名を指定してスキルのメタデータを取得します。

Bash
databricks api get "/api/2.1/unity-catalog/skills?parent=schemas/main.default"

databricks api get "/api/2.1/unity-catalog/skills/main.default.my_skill"

リストのレスポンスにnext_page_tokenが含まれている場合は、次のリクエストでpage_tokenとして渡します。next_page_tokenが存在しないか空になるまで続行します。

CLI と Python イテレーターがページネーションを処理します。

アクセス権を付与​

これらの例では、スキルにREAD VOLUMEを付与します。これにより、プリンシパルはスキルを読み取り、そのバンドルをdownloadできます。その他のスキル権限については、スキルへのアクセスを付与するを参照してください。

Bash
databricks api patch \
  "/api/2.1/unity-catalog/permissions/skill/main.default.my_skill" \
  --json '{
    "changes": [
      { "principal": "data-team", "add": ["READ_VOLUME"] }
    ]
  }'

スキルを更新​

これらの例では、変更できる唯一のフィールドであるスキルのコメントを更新します。スキルの名前は変更できません。スキルの内容を変更するには、新しいバンドルをuploadし、スキルを再度確定してください。

条件付き更新の場合は、まずスキルを取得し、そのetagを更新とともに渡します。更新が成功するのは、その読み取り以降にスキルが変更されていない場合のみです。RESTクエリー文字列に追加するときは、etagをURLエンコードします。

Bash
databricks api patch \
  "/api/2.1/unity-catalog/skills/main.default.my_skill?update_mask=comment" \
  --json '{"comment": "Updated: team-shared math helper"}'

スキルを削除​

スキルを削除すると、そのスキルとバンドルが削除されます。エージェントはこれを読み込めなくなります。

最後に読み取ってから変更されていないことを条件に削除するため、スキルの現在のetagを渡すこともできます。RESTクエリー文字列内のetagをURLエンコードします。

Bash
databricks api delete "/api/2.1/unity-catalog/skills/main.default.my_skill"

その他のリソース​

このページの見出し