Skills API och SDK-referens

Important

Den här funktionen finns i Beta. Kontoadministratörer kan hantera åtkomst till den här funktionen från sidan förhandsversioner av kontokonsolen. Se Hantera förhandsversioner på kontonivå.

Använd dessa exempel för att automatisera kompetenshantering. API:et representerar varje färdighet som en Skill resurs med namnet skills/{catalog}.{schema}.{skill}. För att skriva och publicera en färdighet tillsammans med en agent, se Skapa och dela färdigheter. För privilegier och styrning, se Styrsfärdigheter. Skills har inte resurser från Terraform eller Deklarative Automation Bundles.

Förutsättningar

API-åtgärder

Skills REST API tillhandahåller dessa operationer. Varje kräver USE CATALOG också och USE SCHEMA på föräldern. Följ varje länk för dess fält, behörigheter och svar.

Operation Användningsfall Behörigheter som krävs
Create Skapa en färdighet och förbered dess paketlagring. CREATE VOLUME för schemat
Ladda upp Ladda upp SKILL.md och eventuella stödjande filer via Files API. WRITE VOLUME och READ VOLUME på färdigheten
Slutföra Läs och verifiera SKILL.md, och ställ sedan in paketets namn och beskrivning. READ VOLUME Om färdigheten
Lista Hitta färdigheter du kan använda i ett schema. READ VOLUME, READ METADATA, eller MANAGE på färdigheten
Hämta Läs en färdighets metadata och aktuell etag. READ VOLUME, READ METADATA, eller MANAGE på färdigheten
Update Ändra kommentaren på färdigheten. MANAGE Om färdigheten
Delete Ta bort en färdighet och dess bunt. MANAGE Om färdigheten

Färdighetens ägare har alla dessa på färdigheten. Se Grant access to skills.

Skapa en färdighet

Att skapa en färdighet kräver tre steg: skapa färdigheten, ladda upp dess paket och slutföra den. Tills du har fastställt en färdighet är dess paket namn och beskrivning tomma.

Steg 1: Skapa färdigheten

Skapa färdigheten i ett schema. comment är det enda fältet du kan ställa. Azure Databricks härleder name, bundle_name, och description.

Ersätt main.default.my_skill och data-team med dina egna värden.

REST API

Skicka en POST till /api/2.1/unity-catalog/skills, skickar parent och skill_id som frågeparametrar:

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

Skicka föräldraschemat och färdighetsnamnet och ge kommentaren :--json

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

Python SDK

Skapa och hantera en färdighet med Databricks SDK för 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-mjukvaruutvecklingskit

Skapa och hantera en färdighet med Databricks SDK för 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"},
})

Välj Modular SDK

Skapa och hantera en färdighet med Go Modular SDK. Valfria fält är pekare, så exemplet använder en enradshjälpare, 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

Skapa och hantera en färdighet med Databricks SDK för 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

Skapa och hantera en färdighet med JavaScript SDK:

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

Steg 2: Ladda upp paketet

Ladda upp SKILL.md, och eventuella stödjande filer, till färdighetens lagringsbana, /Skills/<catalog>/<schema>/<skill>/, via Files API. SKILL.md måste börja med YAML frontmatter som sätter name och description. Spara detta exempel som 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

Skicka en PUT till Files API. Ställ DATABRICKS_HOST in din arbetsplats-URL, såsom https://my-workspace.cloud.databricks.com, och DATABRICKS_TOKEN en token. Detta exempel skickar token till curl på standardindata så att den inte syns i processlistan:

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

Skapa färdighetens mapp och kopiera sedan filen till den:

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

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,
})

Välj Modular SDK

Go Modular SDK inkluderar inte Files API. Ladda upp med Files SDK för Go istället:

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 inkluderar inte Files API, så detta exempel anropar REST-endpointen direkt. Den läser arbetsområdets URL, såsom https://my-workspace.cloud.databricks.com, och en token från DATABRICKS_HOST och DATABRICKS_TOKEN miljövariablerna:

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

Steg 3: Färdigställ färdigheten

Att färdigställa läser och validerar SKILL.md, sedan fastställer färdigheterna bundle_name och description dess frontmaterial. Om du ändrar paketet senare, slutför igen.

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

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

Välj 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' });

Hitta en färdighet

Lista de färdigheter du kan komma åt i ett schema, och hämta sedan en färdighets metadata via dess resursnamn.

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"

När listsvaret innehåller next_page_token, passa det som page_token i nästa begäran. Fortsätt tills next_page_token den saknas eller är tom.

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- och Python-iteratorn hanterar paginering åt dig.

Bevilja åtkomst

Dessa exempel ger READ VOLUME färdigheten, vilket låter rektorn läsa färdigheten och ladda ner dess paket. För de andra färdighetsprivilegierna, se Grant access to skills.

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 med Databricks CLI:

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

Python SDK

Grant READ VOLUME med Databricks SDK för 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-mjukvaruutvecklingskit

Bidrag READ VOLUME med Databricks SDK för 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

Grant READ VOLUME med Databricks SDK för 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)))));

Uppdatera en färdighet

Dessa exempel uppdaterar färdighetens kommentar, det enda fältet du kan ändra. Färdighetens namn kan inte ändras. För att ändra innehållet i en färdighet, ladda upp det nya paketet och slutför färdigheten igen.

För en villkorlig uppdatering, skaffa först färdigheten och skicka den etag med uppdateringen. Uppdateringen lyckas bara om färdigheten inte har ändrats sedan den läsningen. URL-koda när etag man lägger till det i en REST-frågesträng.

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

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

Välj 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'),
});

Ta bort en färdighet

Att ta bort en färdighet tar bort den och dess paket. Agenter kan inte längre ladda den.

Du kan också skicka färdighetens aktuella etag för att göra borttagningen villkorad av att den inte har ändrats sedan senaste läsningen. URL-koda de etag i REST-frågesträngarna.

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

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

Välj 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' });

Ytterligare resurser

  • Uppdaterades senast