技能 API 與 SDK 參考

Important

這項功能位於 測試版 (Beta) 中。 帳號管理員可從帳號主控台 預覽 頁面管理此功能存取權。 請參閱 管理帳戶層級預覽。

利用這些範例來自動化技能管理。 API 將每個技能表示為 Skill 一個名為 skills/{catalog}.{schema}.{skill}的資源。 若要與經紀人共同撰寫並發表技能,請參閱 「創建與分享技能」。 關於特權與治理,請參見 治理技能。 技能沒有 Terraform 或 Declarative Automation Bundles 的資源。

先決條件

  • 建立 一個有規範的技能架構。

  • 擁有 你操作所需的權限。

  • 安裝並驗證你打算使用的客戶端。 REST API 沒有版本限制;每個工具和 SDK 都有最低版本:

    • Databricks CLI:v1.20.0 及以上版本
    • Python SDK: databricks-sdk 0.142.0 及以上版本
    • Go SDK: databricks-sdk-go v0.184.0 及以上版本
    • Go Modular SDK: github.com/databricks/sdk-go/aigateway v0.1.0 及以上版本
    • Java SDK: databricks-sdk-java 0.157.0 及以上版本
    • JavaScript SDK: @databricks/sdk-aigateway 0.23.0 及以上版本

    SDK snippets 假設一個已認證的工作區用戶端; w模組化 SDK snippets 假設 Unity Gateway 用戶端已認證,無論是 c 在 Go 和 JavaScript 中 client 。

API 作業

Skills REST API 提供這些操作。 每個項目也都要求 USE CATALOG 父母 USE SCHEMA 負責。 請點擊每個連結查看欄位、權限與回應。

Operation 應用案例 所需的權限
創造 創建一個技能並配置其套件儲存。 CREATE VOLUME 在結構描述上
Upload 透過檔案 API 上傳 SKILL.md 及任何支援檔案。 WRITE VOLUME 以及 READ VOLUME 關於技巧
完成 讀取並驗證 SKILL.md,然後設定技能組合名稱和描述。 READ VOLUME 關於 Skill
清單​​ 找到你能在架構中使用技能。 READ VOLUME, READ METADATA或 MANAGE 在技能上
獲取 閱讀技能的元資料和目前 etag狀態。 READ VOLUME, READ METADATA或 MANAGE 在技能上
Update 更改技能的註解。 MANAGE 關於 Skill
Delete 移除一個技能及其組合包。 MANAGE 關於 Skill

技能擁有者會將這些技能全部保留在技能上。 請參閱技能授予。

創造一項技能

創建技能需要三個步驟:建立技能、上傳其組合包,然後完成。 在你確定技能之前,它的組合名稱和描述都是空白的。

步驟一:創建技能

在一個架構中創造技能。 comment 這是你唯一能設定的欄位。 Azure Databricks 衍生 name、 bundle_name, 。description

將main.default.my_skill 和 data-team 取代為您自己的值。

REST API

傳送 POST/api/2.1/unity-catalog/skills,並傳遞 parent 和 skill_id 作為查詢參數:

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

CLI

傳遞父架構和技能名稱,並附註 --json:

databricks ai-gateway create-skill schemas/main.default my_skill \
  --json '{"comment": "Team-shared math helper skill"}'

Python SDK

使用 Databricks SDK for Python 創建並管理一項技能:

from databricks.sdk import WorkspaceClient
from databricks.sdk.service import catalog as c

w = WorkspaceClient()

skill = w.ai_gateway.create_skill(
    parent="schemas/main.default",
    skill_id="my_skill",
    skill=c.Skill(comment="Team-shared math helper skill"),
)

Go 軟體開發套件 (SDK)

使用 Databricks SDK for Go 創建並管理一項技能:

skill, err := w.AiGateway.CreateSkill(ctx, catalog.CreateSkillRequest{
	Parent:  "schemas/main.default",
	SkillId: "my_skill",
	Skill:   catalog.Skill{Comment: "Team-shared math helper skill"},
})

Go Modular SDK

用 Go Modular SDK 創建並管理一項技能。 可選欄位是指標,因此範例中使用一行輔助工具 func ptr[T any](v T) *T { return &v }。

skill, err := c.CreateSkill(ctx, aigateway.CreateSkillRequest{
	Parent:  ptr("schemas/main.default"),
	SkillId: ptr("my_skill"),
	Skill:   &aigateway.Skill{Comment: ptr("Team-shared math helper skill")},
})

Java 開發套件

使用 Databricks SDK for Java 創建並管理一項技能:

Skill skill =
    w.aiGateway()
        .createSkill(
            new CreateSkillRequest()
                .setParent("schemas/main.default")
                .setSkillId("my_skill")
                .setSkill(new Skill().setComment("Team-shared math helper skill")));

JS 模組化 SDK

使用 JavaScript SDK 建立並管理一項技能:

const created = await client.createSkill({
  parent: 'schemas/main.default',
  skillId: 'my_skill',
  skill: { comment: 'Team-shared math helper skill' },
});

步驟二:上傳組合包

透過 Files API 將 ,以及 SKILL.md任何支援檔案上傳到技能的儲存路徑 /Skills/<catalog>/<schema>/<skill>/。 SKILL.md 必須從設定 name 和 description的 YAML 前置碼開始。 將此範例存為 SKILL.md:

---
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.

REST API

把 a PUT 傳送到 Files API。 設定為你的工作區 URL,例如 https://my-workspace.cloud.databricks.com,並DATABRICKS_TOKEN設定DATABRICKS_HOST為一個令牌。 這個範例是在標準輸入時將 token 傳遞到 , curl 因此它不會出現在程序清單中:

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}\""

CLI

建立技能資料夾,然後將檔案複製到裡面:

databricks fs mkdir dbfs:/Skills/main/default/my_skill
databricks fs cp SKILL.md dbfs:/Skills/main/default/my_skill/SKILL.md --overwrite

Python SDK

with open("SKILL.md", "rb") as f:
    w.files.upload("/Skills/main/default/my_skill/SKILL.md", f, overwrite=True)

Go 軟體開發套件 (SDK)

f, err := os.Open("SKILL.md")
if err != nil {
	return err
}
defer f.Close()

err = w.Files.Upload(ctx, files.UploadRequest{
	FilePath:  "/Skills/main/default/my_skill/SKILL.md",
	Contents:  f,
	Overwrite: true,
})

Go Modular SDK

Go Modular SDK 不包含 Files API。 改用 Files SDK for Go 上傳:

fc, err := files.NewClient(ctx)
if err != nil {
	return err
}

f, err := os.Open("SKILL.md")
if err != nil {
	return err
}
defer f.Close()

_, err = fc.Upload(ctx, "/Skills/main/default/my_skill/SKILL.md", f, files.WithOverwrite(true))

Java 開發套件

try (InputStream contents = Files.newInputStream(Paths.get("SKILL.md"))) {
  w.files()
      .upload(
          new UploadRequest()
              .setFilePath("/Skills/main/default/my_skill/SKILL.md")
              .setOverwrite(true)
              .setContents(contents));
}

JS 模組化 SDK

JavaScript Modular SDK 不包含 Files API,因此此範例直接呼叫 REST 端點。 它會讀取工作區的 URL,例如 https://my-workspace.cloud.databricks.com,以及來自 DATABRICKS_HOST 和 DATABRICKS_TOKEN 環境變數的權杖:

import { readFile } from 'node:fs/promises';

const response = await fetch(
  `${process.env.DATABRICKS_HOST}/api/2.0/fs/files/Skills/main/default/my_skill/SKILL.md?overwrite=true`,
  {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/octet-stream',
      Authorization: `Bearer ${process.env.DATABRICKS_TOKEN}`,
    },
    body: await readFile('SKILL.md'),
  },
);
if (!response.ok) {
  throw new Error(`Upload failed: ${response.status} ${response.statusText}`);
}

步驟三:完成技能

最終閱讀並驗證 SKILL.md,然後設定技能 bundle_name 的 和 description 從前置內容。 如果你之後更改組合包,請再完成一次。

REST API

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

CLI

databricks ai-gateway finalize-skill skills/main.default.my_skill

Python SDK

finalized = w.ai_gateway.finalize_skill(name="skills/main.default.my_skill")
print(finalized.bundle_name, finalized.description)

Go 軟體開發套件 (SDK)

finalized, err := w.AiGateway.FinalizeSkill(ctx, catalog.FinalizeSkillRequest{
	Name: "skills/main.default.my_skill",
})

Go Modular SDK

finalized, err := c.FinalizeSkill(ctx, aigateway.FinalizeSkillRequest{
	Name: ptr("skills/main.default.my_skill"),
})

Java 開發套件

Skill finalized =
    w.aiGateway().finalizeSkill(new FinalizeSkillRequest().setName("skills/main.default.my_skill"));

JS 模組化 SDK

const finalized = await client.finalizeSkill({ name: 'skills/main.default.my_skill' });

找到一項技能

在結構中列出你能存取的技能,然後依資源名稱取得技能的元資料。

REST API

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

databricks ai-gateway list-skills schemas/main.default

databricks ai-gateway get-skill skills/main.default.my_skill

Python SDK

for skill in w.ai_gateway.list_skills(parent="schemas/main.default"):
    print(skill.name)

skill = w.ai_gateway.get_skill(name="skills/main.default.my_skill")

CLI 和 Python 迭代器會幫你處理分頁。

授予存取權

這些範例 READ VOLUME 授予技能,讓校長能閱讀技能並下載其組合包。 關於其他技能特權,請參見 「授予技能存取權」。

REST API

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

CLI

Grant READ VOLUME 與 Databricks CLI:

databricks grants update skill main.default.my_skill \
  --json '{"changes": [{"principal": "data-team", "add": ["READ_VOLUME"]}]}'

Python SDK

Grant READ VOLUME 使用 適用於 Python 的 Databricks SDK:

from databricks.sdk.service import catalog as c

w.grants.update(
    securable_type="skill",
    full_name="main.default.my_skill",
    changes=[c.PermissionsChange(principal="data-team", add=[c.Privilege.READ_VOLUME])],
)

Go 軟體開發套件 (SDK)

使用 READ VOLUME 授予 :

_, err := w.Grants.Update(ctx, catalog.UpdatePermissions{
	SecurableType: "skill",
	FullName:      "main.default.my_skill",
	Changes: []catalog.PermissionsChange{{
		Principal: "data-team",
		Add:       []catalog.Privilege{catalog.PrivilegeReadVolume},
	}},
})

Java 開發套件

使用 適用於 Java 的 Databricks SDK 授予 READ VOLUME:

w.grants()
    .update(
        new UpdatePermissions()
            .setSecurableType("skill")
            .setFullName("main.default.my_skill")
            .setChanges(
                Arrays.asList(
                    new PermissionsChange()
                        .setPrincipal("data-team")
                        .setAdd(Arrays.asList(Privilege.READ_VOLUME)))));

更新技能

這些範例是更新技能評論,這是你唯一能更改的欄位。 這個技能的名稱不能更改。 要更改技能內容,請 上傳 新組合包並重新 完成 該技能。

有條件更新的話,先 取得技能 並隨更新傳達 etag 。 更新只有在技能自那次讀取後沒有改變時才算成功。 在將 URL etag 編碼到 REST 查詢字串時。

REST API

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

CLI

databricks ai-gateway update-skill skills/main.default.my_skill comment \
  --json '{"comment": "Updated: team-shared math helper"}'

Python SDK

from databricks.sdk.service import catalog as c
from databricks.sdk.common.types.fieldmask import FieldMask

updated = w.ai_gateway.update_skill(
    name="skills/main.default.my_skill",
    update_mask=FieldMask(["comment"]),
    skill=c.Skill(comment="Updated: team-shared math helper"),
)

Go 軟體開發套件 (SDK)

updated, err := w.AiGateway.UpdateSkill(ctx, catalog.UpdateSkillRequest{
	Name:       "skills/main.default.my_skill",
	UpdateMask: *fieldmask.New([]string{"comment"}),
	Skill:      catalog.Skill{Comment: "Updated: team-shared math helper"},
})

Go Modular SDK

mask, err := types.NewFieldMask[aigateway.Skill]("comment")
updated, err := c.UpdateSkill(ctx, aigateway.UpdateSkillRequest{
	Skill: &aigateway.Skill{
		Name:    ptr("skills/main.default.my_skill"),
		Comment: ptr("Updated: team-shared math helper"),
	},
	UpdateMask: mask,
})

Java 開發套件

Skill updated =
    w.aiGateway()
        .updateSkill(
            new UpdateSkillRequest()
                .setName("skills/main.default.my_skill")
                .setUpdateMask(FieldMask.newBuilder().addPaths("comment").build())
                .setSkill(new Skill().setComment("Updated: team-shared math helper")));

JS 模組化 SDK

import { skillFieldMask } from '@databricks/sdk-aigateway/v1';

const updated = await client.updateSkill({
  skill: {
    name: 'skills/main.default.my_skill',
    comment: 'Updated: team-shared math helper',
  },
  updateMask: skillFieldMask('comment'),
});

刪除技能

刪除技能會移除該技能及其組合包。 客服人員無法再載入它。

你也可以傳遞技能的當前值 etag ,讓刪除條件是自上次讀取以來技能沒有改變。 在 REST 中將查詢字串 URL 編碼 etag 。

REST API

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

CLI

databricks ai-gateway delete-skill skills/main.default.my_skill

Python SDK

w.ai_gateway.delete_skill(name="skills/main.default.my_skill")

Go 軟體開發套件 (SDK)

err := w.AiGateway.DeleteSkill(ctx, catalog.DeleteSkillRequest{
	Name: "skills/main.default.my_skill",
})

Go Modular SDK

err := c.DeleteSkill(ctx, aigateway.DeleteSkillRequest{
	Name: ptr("skills/main.default.my_skill"),
})

Java 開發套件

w.aiGateway().deleteSkill(new DeleteSkillRequest().setName("skills/main.default.my_skill"));

JS 模組化 SDK

await client.deleteSkill({ name: 'skills/main.default.my_skill' });

其他資源