Referensi API dan SDK Skills

Important

Fitur ini ada di Beta. Admin akun dapat mengelola akses ke fitur ini dari halaman Pratinjau di konsol akun. Lihat Mengelola pratinjau tingkat akun.

Gunakan contoh-contoh ini untuk mengotomatisasi manajemen keterampilan. API mewakili setiap keterampilan sebagai sumber Skill daya bernama skills/{catalog}.{schema}.{skill}. Untuk menulis dan menerbitkan keterampilan bersama agen, lihat Buat dan bagikan keterampilan. Untuk hak istimewa dan tata kelola, lihat Keterampilan Kelola. Skill tidak memiliki sumber daya Terraform atau Declarative Automation Bundles.

Prasyarat

Buat skema yang diatur untuk keterampilan.
Memiliki izin yang diperlukan untuk operasi Anda.
Instal dan autentikasi klien yang akan Anda gunakan. API REST tidak memerlukan versi; setiap alat dan SDK memiliki versi minimum:
- Databricks CLI: v1.20.0 dan ke atas
- Python SDK:databricks-sdk 0.142.0 ke atas
- Go SDK:databricks-sdk-go v0.184.0 ke atas
- Go Modular SDK: github.com/databricks/sdk-go/aigateway v0.1.0 ke atas
- Java SDK:databricks-sdk-java 0.157.0 ke atas
- JavaScript SDK:@databricks/sdk-aigateway 0.23.0 ke atas
Cuplikan SDK mengasumsikan klien workspace yang terautentikasi, w; Potongan SDK modular mengasumsikan klien Unity Gateway yang terautentikasi, c baik di Go maupun client JavaScript.

Pengoperasian API

API Skills REST menyediakan operasi-operasi ini. Masing-masing juga membutuhkan USE CATALOG dan USE SCHEMA menjadi tanggung jawab orang tua. Ikuti setiap tautan untuk mendapatkan kolom, izin, dan responsnya.

Pengoperasian	Skenario penggunaan	Memerlukan izin
Menciptakan	Buat keterampilan dan sediakan penyimpanan bundelnya.	`CREATE VOLUME` pada skema
Unggah	Unggah `SKILL.md` dan file pendukung melalui Files API.	`WRITE VOLUME` dan `READ VOLUME` pada keterampilan
Menyelesaikan	Baca dan validasi `SKILL.md`, lalu atur nama bundle dan deskripsi skill.	`READ VOLUME` tentang keterampilan
Daftar	Cari keterampilan yang bisa diakses dalam sebuah skema.	`READ VOLUME`, `READ METADATA`, atau `MANAGE` pada keterampilan
Dapatkan	Baca metadata keterampilan dan data terkini `etag`.	`READ VOLUME`, `READ METADATA`, atau `MANAGE` pada keterampilan
Update	Ubah komentar keterampilan.	`MANAGE` tentang keterampilan
Menghapus	Hapus skill dan bundelnya.	`MANAGE` tentang keterampilan

Pemilik keterampilan memegang semua ini pada keterampilan tersebut. Lihat Memberikan akses ke keterampilan.

Buat kemampuan

Membuat keterampilan membutuhkan tiga langkah: buat keterampilan, unggah bundelnya, lalu selesaikan. Sampai Anda menyelesaikan keterampilan, nama dan deskripsi bundelnya kosong.

Langkah 1: Buat keterampilan

Buat keterampilan dalam sebuah skema. comment adalah satu-satunya bidang yang bisa Anda atur. Azure Databricks menurunkan name, bundle_name, dan description.

Ganti main.default.my_skill dan data-team dengan nilai Anda sendiri.

REST API

Kirim ke POST/api/2.1/unity-catalog/skills, melewatkan parent dan skill_id sebagai parameter query:

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

Kirimkan skema induk dan nama keterampilan, lalu berikan komentar dengan --json:

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

Python SDK

Buat dan kelola keterampilan dengan Databricks SDK untuk 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 (Kit Pengembangan Perangkat Lunak)

Buat dan kelola keterampilan dengan Databricks SDK untuk 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

Buat dan kelola keterampilan dengan Go Modular SDK. Kolom opsional adalah pointer, jadi contoh menggunakan pembantu satu baris, 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 SDK

Buat dan kelola keterampilan dengan Databricks SDK untuk 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 Modular SDK

Buat dan kelola keterampilan dengan JavaScript SDK:

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

Langkah 2: Unggah bundel

Unggah SKILL.md, dan file pendukungnya, ke jalur penyimpanan skill, /Skills/<catalog>/<schema>/<skill>/, melalui Files API. SKILL.md harus dimulai dengan frontmatter YAML yang menetapkan name dan description. Simpan contoh ini sebagai 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

Kirim ke PUTAPI Files. Atur DATABRICKS_HOST ke URL workspace Anda, seperti https://my-workspace.cloud.databricks.com, dan DATABRICKS_TOKEN ke token. Contoh ini meneruskan token ke curl input standar sehingga tidak muncul di daftar proses:

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

Buat folder keterampilan, lalu salin file ke dalamnya:

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 (Kit Pengembangan Perangkat Lunak)

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 tidak menyertakan API Files. Unggah dengan Files SDK for Go sebagai gantinya:

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 SDK

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 Modular SDK

JavaScript Modular SDK tidak menyertakan Files API, jadi contoh ini memanggil endpoint REST secara langsung. Ia membaca URL workspace, seperti https://my-workspace.cloud.databricks.com, dan token dari DATABRICKS_HOSTDATABRICKS_TOKEN variabel dan environment:

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}`);
}

Langkah 3: Selesaikan keterampilan

Finaling membaca dan memvalidasi SKILL.md, lalu mengatur keterampilan bundle_name dan description dari frontmatter-nya. Jika Anda mengubah bundel nanti, finalisasi lagi.

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 (Kit Pengembangan Perangkat Lunak)

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 SDK

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

JS Modular SDK

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

Temukan keterampilan

Daftarkan keterampilan yang bisa Anda akses dalam sebuah skema, lalu dapatkan metadata keterampilan berdasarkan nama sumber dayanya.

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"

Ketika respons daftar mencakup next_page_token, teruskan seperti page_token pada permintaan berikutnya. Lanjutkan sampai next_page_token kosong atau tidak ada.

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")

Iterator CLI dan Python menangani penoplomanan untuk Anda.

Memberikan akses

Contoh-contoh ini memberikan keterampilan READ VOLUME , yang memungkinkan kepala sekolah membaca keterampilan dan mengunduh bundelnya. Untuk hak istimewa keterampilan lainnya, lihat Memberikan akses ke keterampilan.

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

Hibah READ VOLUME dengan Databricks CLI:

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

Python SDK

Berikan READ VOLUME dengan Databricks SDK untuk Python:

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 (Kit Pengembangan Perangkat Lunak)

Berikan READ VOLUME dengan Databricks SDK for Go:

_, 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 SDK

Berikan READ VOLUME dengan Databricks SDK untuk Java:

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)))));

Perbarui keterampilan

Contoh-contoh ini memperbarui komentar keterampilan, satu-satunya bidang yang bisa Anda ubah. Nama skillnya tidak bisa diubah. Untuk mengubah isi keterampilan, unggah bundel baru dan selesaikan keterampilan itu lagi.

Untuk pembaruan bersyarat, pertama-tama dapatkan skill dan luluskan bersama etag pembaruan. Pembaruan hanya berhasil jika skill tidak berubah sejak bacaan itu. URL-encode saat etag menambahkannya ke string kueri 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 (Kit Pengembangan Perangkat Lunak)

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 SDK

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 Modular 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'),
});

Menghapus keterampilan

Menghapus skill akan menghapusnya dan bundle-nya. Agen tidak bisa lagi memuatnya.

Anda juga bisa meneruskan data keterampilan saat ini etag agar penghapusan bersyarat bahwa tidak ada perubahan sejak pembacaan terakhir. Encode URL string etag kueri REST.

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 (Kit Pengembangan Perangkat Lunak)

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 SDK

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

JS Modular SDK

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

Sumber daya tambahan

Saran dan Komentar

Apakah halaman ini membantu?

Terakhir diperbarui pada 2026-10-15

Referensi API dan SDK Skills

Prasyarat

Pengoperasian API

Buat kemampuan

Langkah 1: Buat keterampilan

REST API

CLI

Python SDK

Go SDK (Kit Pengembangan Perangkat Lunak)

Go Modular SDK

Java SDK

JS Modular SDK

Langkah 2: Unggah bundel

REST API

CLI

Python SDK

Go SDK (Kit Pengembangan Perangkat Lunak)

Go Modular SDK

Java SDK

JS Modular SDK

Langkah 3: Selesaikan keterampilan

REST API

CLI

Python SDK

Go SDK (Kit Pengembangan Perangkat Lunak)

Go Modular SDK

Java SDK

JS Modular SDK

Temukan keterampilan

REST API

CLI

Python SDK

Memberikan akses

REST API

CLI

Python SDK

Go SDK (Kit Pengembangan Perangkat Lunak)

Java SDK

Perbarui keterampilan

REST API

CLI

Python SDK

Go SDK (Kit Pengembangan Perangkat Lunak)

Go Modular SDK

Java SDK

JS Modular SDK

Menghapus keterampilan

REST API

CLI

Python SDK

Go SDK (Kit Pengembangan Perangkat Lunak)

Go Modular SDK

Java SDK

JS Modular SDK

Sumber daya tambahan

Saran dan Komentar

Sumber Daya Tambahan: