Beceri API'si ve SDK referansı

Important

Bu özellik Beta sürümündedir. Hesap yöneticileri bu özelliğe erişimi hesap konsolu Önizlemeler sayfasından yönetebilir. Bkz. Hesap düzeyinde önizlemeleri yönetme.

Bu örnekleri beceri yönetimini otomatikleştirmek için kullanın. API, her yeteneği Skill bir kaynak olarak temsil skills/{catalog}.{schema}.{skill}eder. Bir ajanla bir beceri yazıp yayımlamak için, Yetenekler yarat ve paylaş bölümünü inceleyin. Ayrıcalıklar ve yönetim için bkz. Yönetim becerileri. Yeteneklerin Terraform veya Deklarative Automation Bundles kaynakları yoktur.

Önkoşullar

Beceriler için yönetilen bir şema oluşturun.
İşleminiz için gerekli izinlere sahip olun.
Kullanmayı planladığınız istemciyi kurup doğrulayın. REST API'nin sürüm gereksinimi yoktur; her aracın ve SDK'nın minimum bir sürümü vardır:
- Databricks CLI: v1.20.0 ve üzeri
- Python SDK: databricks-sdk 0.142.0 ve üzeri
- Go SDK: databricks-sdk-go v0.184.0 ve üzeri sürümler
- Go Modular SDK: github.com/databricks/sdk-go/aigateway v0.1.0 ve üzeri
- Java SDK:databricks-sdk-java 0.157.0 ve üzeri
- JavaScript SDK: @databricks/sdk-aigateway 0.23.0 ve üzeri
SDK snippet'leri, doğrulanmış bir çalışma alanı istemcisini varsayar, w; Modüler SDK snippetleri ise Go ve client JavaScript'te doğrulanmış bir Unity Gateway istemcisi c varsayır.

API işlemleri

Skills REST API'si bu işlemleri sağlar. Her biri ayrıca ebeveyn üzerinde ve gereklidir USE CATALOGUSE SCHEMA . Her linki alanları, izinleri ve yanıtları için takip edin.

Operation	Kullanım örneği	Gerekli izinler
Oluştur	Bir beceri yaratın ve paket depolamasını sağla.	`CREATE VOLUME` şema üzerinde
Yükle	Dosya API üzerinden yükleyin `SKILL.md` ve destekleyen dosyalar.	`WRITE VOLUME` ve `READ VOLUME` beceri üzerine
Tamamla	Oku ve doğrula `SKILL.md`, sonra becerinin paket adını ve açıklamasını belirle.	`READ VOLUME` Yetenek üzerine
Listesi	Bir şemada erişebileceğiniz beceriler bulun.	`READ VOLUME`, `READ METADATA`, ya `MANAGE` da beceri üzerine
Get	Bir becerinin meta verilerini ve güncel `etag`bilgilerini okuyun.	`READ VOLUME`, `READ METADATA`, ya `MANAGE` da beceri üzerine
Update	Becerinin yorumunu değiştir.	`MANAGE` Yetenek üzerine
Delete	Bir yetenek ve demetini çıkar.	`MANAGE` Yetenek üzerine

Yetenek sahibi, bunların hepsini yetenekte tutuyor. Bkz. Becerilere erişim hibesi.

Beceri oluşturma

Bir beceri yaratmak üç adımdan oluşur: beceriyi oluşturmak, paketini yüklemek ve ardından tamamlamak. Bir yetenek kesinleşene kadar paket adı ve açıklaması boş kalıyor.

Adım 1: Beceriyi yaratın

Beceriyi bir şemada yarat. comment ayarlayabileceğiniz tek alan. Azure Databricks name, bundle_name, ve description.

ve main.default.my_skill değerlerini kendi değerlerinizle değiştirindata-team.

REST API

/api/2.1/unity-catalog/skills adresine bir POST gönder, sorgu parametreleri olarak geçinparent: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

Ebeveyn şemasını ve yetenek adını iletin ve yoruma --jsonşunları ekleyin:

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

Python SDK'sı

Databricks SDK for Python ile bir beceri oluşturun ve yönetin:

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'sı

Go için Databricks SDK ile bir beceri oluşturun ve yönetin:

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 ile bir beceri oluşturun ve yönetin. Isteğe bağlı alanlar işaretçidir, bu yüzden örnekte tek satırlık bir yardımcı kullanılır, 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'sı

Java için Databricks SDK ile bir beceri oluşturun ve yönetin:

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

JS Modüler SDK

JavaScript SDK ile bir beceri oluşturun ve yönetin:

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

Adım 2: Paketi yükleyin

Fayllar API'si üzerinden , ve destekleyen dosyaları becerinin depolama yoluna /Skills/<catalog>/<schema>/<skill>/yükleyinSKILL.md. SKILL.md ve ayarlayan namedescriptionYAML ön maddeyle başlamalı. Bu örneği şu şekilde kaydedin 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

Dosyalar API'sine A PUT gönderin. Çalışma DATABRICKS_HOST alanı URL'nize ayarlayın, örneğin https://my-workspace.cloud.databricks.com, ve DATABRICKS_TOKEN bir token. Bu örnek, token standart girdide işlem curl listesinde görünmemesi için aktarıyor:

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

Becerinin klasörünü oluşturun, sonra dosyayı içine kopyalayın:

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'sı

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

Go SDK'sı

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'da Dosyalar API'si yok. Bunun yerine Go için Files SDK ile yükleyin:

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'sı

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 Modüler SDK

JavaScript Modular SDK'sı Files API'sini içermiyor, bu yüzden bu örnek doğrudan REST uç noktasını çağırıyor. Çalışma alanı URL'sini, örneğin https://my-workspace.cloud.databricks.com, ve ve DATABRICKS_TOKEN çevre değişkenlerinden bir tokenı DATABRICKS_HOST okur:

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

Adım 3: Beceriyi Tamamla

Sonlandırma, okuyor ve doğruluyor SKILL.md, sonra beceriyi bundle_name belirliyor ve description ön konudan geliyor. Paketi daha sonra değiştirirseniz, tekrar sonlandırın.

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'sı

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

Go SDK'sı

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'sı

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

JS Modüler SDK

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

Bir beceri bul

Erişebileceğiniz becerileri bir şemada listeleyin, sonra bir becerinin meta verisini kaynak adıyla alın.

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"

Liste yanıtı next_page_tokendahildiğinde, bir sonraki istekte olduğu page_token gibi ilet. Yok olana veya boş olana kadar devam next_page_token et.

CLI

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

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

Python SDK'sı

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 ve Python yinelemesi sayfa seçimini sizin için halleder.

Erişim izni ver

Bu örnekler beceriye destek verir READ VOLUME , bu da müdürün yeteneği okumasına ve paketini indirmesine olanak tanır. Diğer yetenek ayrıcalıkları için bkz. Yeteneklere erişim ver.

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

Databricks CLI ile hibe READ VOLUME :

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

Python SDK'sı

Python için Databricks SDK ile hibeREAD VOLUME:

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'sı

Grant ile 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 SDK'sı

Java için Databricks SDK ile hibeREAD 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)))));

Bir yeteneği güncelleme

Bu örnekler, değiştirebileceğiniz tek alan olan yetenek yorumunu güncelliyor. Becerinin adı değiştirilemez. Bir yeteneğin içeriğini değiştirmek için yeni paketi yükleyin ve yeteneği tekrar tamamlayın .

Koşullu güncelleme için önce beceriyi al ve güncellemeyle birlikte geç etag . Güncelleme ancak o okumadan beri beceri değişmediyse başarılı oluyor. URL-encode etag ile REST sorgu dizisine eklenir.

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'sı

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'sı

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'sı

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 Modüler 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'),
});

Bir beceriyi sil

Bir yeteneği silmek onu ve paketini kaldırır. Ajanlar artık onu yükleyemiyor.

Ayrıca yeteneğin mevcut durumunu etag da iletebilirsiniz, böylece silme şartı son okumadan beri değişmemiş olur. URL-encode in etag REST sorgu dizelerini kullanır.

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'sı

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

Go SDK'sı

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'sı

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

JS Modüler SDK

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

Ek kaynaklar

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Son güncelleştirme: 2026-10-15