Skills API en SDK-referentie

Important

Deze functie bevindt zich in de bètaversie. Accountbeheerders kunnen de toegang tot deze functie beheren via de pagina Previews van de accountconsole. Zie Previews op accountniveau beheren.

Gebruik deze voorbeelden om vaardigheidsbeheer te automatiseren. De API vertegenwoordigt elke vaardigheid als een Skill bron skills/{catalog}.{schema}.{skill}genaamd . Om een vaardigheid te schrijven en te publiceren met een agent, zie Create and share skills. Voor privileges en bestuur, zie Bestuursvaardigheden. Skills hebben geen Terraform- of Declarative Automation Bundles-bronnen.

Voorwaarden

API-bewerkingen

De Skills REST API biedt deze bewerkingen. Elk vereist USE CATALOG ook en USE SCHEMA op de ouder. Volg elke link voor de velden, permissies en reacties.

Operation Gebruiksituatie Vereiste toestemmingen
Creëren Maak een vaardigheid aan en stel de bundelopslag ervan in. CREATE VOLUME in het schema
Upload Upload SKILL.md en eventuele ondersteunende bestanden via de Files API. WRITE VOLUME en READ VOLUME over de vaardigheid
Voltooien Lees en valideer SKILL.md, en stel dan de bundelnaam en beschrijving van de vaardigheid in. READ VOLUME Over de vaardigheid
Lijst Zoek vaardigheden die je kunt gebruiken in een schema. READ VOLUME, READ METADATA, of MANAGE op de vaardigheid
Downloaden Lees de metadata van een vaardigheid en actuele etag. READ VOLUME, READ METADATA, of MANAGE op de vaardigheid
Update Verander de opmerking van de vaardigheid. MANAGE Over de vaardigheid
Delete Verwijder een vaardigheid en het bundel ervan. MANAGE Over de vaardigheid

De eigenaar van de vaardigheid heeft al deze op de vaardigheid. Zie Toegang tot vaardigheden toekennen.

Een vaardigheid maken

Het creëren van een vaardigheid bestaat uit drie stappen: maak de vaardigheid aan, upload de bundel ervan, en maak deze dan af. Totdat je een vaardigheid definitief hebt afgerond, zijn de bundelnaam en beschrijving leeg.

Stap 1: Creëer de vaardigheid

Creëer de vaardigheid in een schema. comment is het enige veld dat je kunt instellen. Azure Databricks leidt name, bundle_name, en descriptionaf.

Vervang main.default.my_skill en data-team door uw eigen waarden.

REST API

Stuur een POST naar /api/2.1/unity-catalog/skills, waarbij en skill_id als queryparameters worden doorgegevenparent:

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

Geef het ouderschema en de vaardigheidsnaam door, en geef de opmerking met --json:

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

Python SDK

Maak en beheer een vaardigheid met de Databricks SDK voor 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 Softwareontwikkelingskit

Maak en beheer een vaardigheid met de Databricks SDK voor 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

Creëer en beheer een vaardigheid met de Go Modular SDK. Optionele velden zijn pointers, dus het voorbeeld gebruikt een eenregelige helper, 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

Maak een vaardigheid aan en beheer deze met de Databricks SDK voor 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

Maak en beheer een vaardigheid met de JavaScript SDK:

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

Stap 2: Upload de bundel

Upload SKILL.md, en eventuele ondersteunende bestanden, naar het opslagpad van de vaardigheid, /Skills/<catalog>/<schema>/<skill>/, via de Files API. SKILL.mdmoet beginnen met YAML frontmatter dat en descriptionzetname. Sla dit voorbeeld op als 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

Stuur een PUT naar de Files API. Stel DATABRICKS_HOST in op je workspace-URL, zoals https://my-workspace.cloud.databricks.com, en DATABRICKS_TOKEN op een token. Dit voorbeeld geeft het token door aan curl standaard invoer zodat het niet in de proceslijst verschijnt:

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

Maak de map van de vaardigheid aan en kopieer het bestand ernaar:

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 Softwareontwikkelingskit

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

De Go Modular SDK bevat de Files API niet. Upload in plaats daarvan met de Files SDK voor 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 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

De JavaScript Modular SDK bevat de Files API niet, dus dit voorbeeld roept direct het REST-eindpunt aan. Het leest de workspace-URL, zoals https://my-workspace.cloud.databricks.com, en een token uit de DATABRICKS_HOST en DATABRICKS_TOKEN omgevingsvariabelen:

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

Stap 3: Voltooi de vaardigheid

Het afronden leest en valideert SKILL.md, en stelt vervolgens de vaardigheid bundle_name en description de voorste inhoud vast. Als je de bundel later verandert, maak het dan opnieuw af.

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 Softwareontwikkelingskit

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

Vind een vaardigheid

Noem de vaardigheden die je kunt gebruiken in een schema, en haal dan de metadata van een vaardigheid op basis van de resourcenaam.

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"

Wanneer de lijstrespons bevat next_page_token, geef het door zoals page_token in het volgende verzoek. Ga door tot next_page_token het afwezig of leeg is.

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

De CLI- en Python-iterator regelen de paginering voor je.

Toegang verlenen

Deze voorbeelden geven READ VOLUME de vaardigheid, waarmee de directeur de vaardigheid kan lezen en de bundel downloadt. Voor de andere vaardigheidsprivileges, zie Verleen toegang tot vaardigheden.

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 met de Databricks CLI:

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

Python SDK

Toegang verlenen READ VOLUME met de Databricks SDK voor 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 Softwareontwikkelingskit

Grant READ VOLUME met de Databricks SDK voor 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 met de Databricks SDK voor 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)))));

Een vaardigheid bijwerken

Deze voorbeelden werken de opmerking van de vaardigheid bij, het enige veld dat je kunt wijzigen. De naam van de vaardigheid kan niet worden veranderd. Om de inhoud van een vaardigheid te wijzigen, upload je de nieuwe bundel en maak je de vaardigheid opnieuw af.

Voor een voorwaardelijke update haal eerst de vaardigheid en geef deze etag door met de update. De update slaagt alleen als de vaardigheid sinds die lezing niet is veranderd. URL-encoderen wanneer etag het wordt toegevoegd aan een REST-querystring.

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 Softwareontwikkelingskit

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

Een vaardigheid verwijderen

Het verwijderen van een vaardigheid verwijdert deze en het bundelpakket. Agenten kunnen het niet meer laden.

Je kunt ook de huidige etag vaardigheid doorgeven om verwijdering afhankelijk te maken van het feit dat deze sinds de laatste lezing niet is veranderd. URL-codeer de etag in REST-querystrings.

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 Softwareontwikkelingskit

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

Aanvullende bronnen

  • Laatst bijgewerkt om