API delle competenze e riferimento SDK

Importante

Questa funzionalità è in versione beta. Gli amministratori dell'account possono gestire l'accesso a questa funzionalità dalla pagina Anteprime della console dell'account. Vedi Gestire le anteprime a livello di account.

Usa questi esempi per automatizzare la gestione delle competenze. L'API rappresenta ogni abilità come una Skill risorsa chiamata skills/{catalog}.{schema}.{skill}. Per creare e pubblicare una competenza con un agente, vedi Crea e condividi competenze. Per privilegi e governance, vedi Competenze di governo. Le abilità non hanno risorse di Terraform o Declarative Automation Bundles.

Prerequisiti

Imposta uno schema governato per le abilità.
Avere i permessi necessari per la tua operazione.
Installa e autentica il client che intendi usare. L'API REST non ha alcun requisito di versione; ogni strumento e SDK ha una versione minima:
- Databricks CLI: v1.20.0 e successive
- Python SDK: databricks-sdk 0.142.0 e oltre
- Go SDK: databricks-sdk-go v0.184.0 e superiori
- Go Modular SDK: github.com/databricks/sdk-go/aigateway v0.1.0 e superiori
- Java SDK: databricks-sdk-java 0.157.0 e superiori
- JavaScript SDK: @databricks/sdk-aigateway 0.23.0 e superiori
Gli snippet SDK assumono un client workspace autenticato, w; Gli snippet SDK modulari assumono un client Unity Gateway autenticato, c sia in Go che client in JavaScript.

Operazioni API

L'API Skills REST fornisce queste operazioni. Ognuno richiede USE CATALOG anche e USE SCHEMA sul genitore. Segui ogni link per i suoi campi, permessi e risposte.

Operation	Caso di utilizzo	Autorizzazioni necessarie
Creare	Crea una competenza e predisponi del suo pacchetto di archiviazione.	`CREATE VOLUME` sullo schema
Upload	Carica `SKILL.md` e qualsiasi file di supporto tramite l'API File.	`WRITE VOLUME` e `READ VOLUME` sull'abilità
Finalizzare	Leggi e convalida `SKILL.md`, poi imposta il nome e la descrizione del bundle della competenza.	`READ VOLUME` Sull'abilità
Elenco	Trova competenze accessibili in uno schema.	`READ VOLUME`, `READ METADATA`, o `MANAGE` sull'abilità
GET	Leggi i metadati di una competenza e i dati attuali `etag`di	`READ VOLUME`, `READ METADATA`, o `MANAGE` sull'abilità
Update	Cambia il commento dell'abilità.	`MANAGE` Sull'abilità
Elimina	Rimuovi un'abilità e il suo bundle.	`MANAGE` Sull'abilità

Il proprietario dell'abilità tiene tutto questo in vantaggio. Vedi Concedere accesso alle competenze.

Creare una competenza

Creare un'abilità richiede tre fasi: creare l'abilità, caricare il suo bundle e poi finalizzarlo. Finché non finalizzi un'abilità, il nome e la descrizione del bundle restano vuoti.

Passo 1: Crea l'abilità

Crea l'abilità in uno schema. comment è l'unico campo che puoi impostare. Azure Databricks deriva name, bundle_name, e description.

Sostituire main.default.my_skill e data-team con valori personalizzati.

REST API

Invia a POST/api/2.1/unity-catalog/skills, passando parent e skill_id come parametri di 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

Passa lo schema genitore e il nome dell'abilità, e fornisci il commento con --json:

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

PYTHON SDK

Crea e gestisce una competenza con l'SDK Databricks per 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"),
)

SDK di sviluppo Go

Crea e gestisce un'abilità con l'SDK Databricks per 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

Crea e gestisci un'abilità con il Go Modular SDK. I campi opzionali sono puntatori, quindi l'esempio utilizza una funzione di supporto su una sola riga, 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

Crea e gestisci una competenza con l'SDK Databricks per Java:

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

SDK modulare JS

Crea e gestisci un'abilità con l'SDK JavaScript:

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

Passo 2: Carica il bundle

Carica SKILL.md, e eventuali file di supporto nel percorso di archiviazione della competenza, /Skills/<catalog>/<schema>/<skill>/, tramite l'API File. SKILL.md deve iniziare con frontmatter YAML che imposta name e description. Salva questo esempio come 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

Invia A PUTall'API File. Imposta DATABRICKS_HOST l'URL del tuo workspace, come https://my-workspace.cloud.databricks.com, e DATABRICKS_TOKEN un token. Questo esempio passa il token a curl un input standard così che non appaia nella lista dei processi:

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

Crea la cartella della competenza, poi copia il file al suo interno:

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)

SDK di sviluppo Go

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

L'SDK modulare Go non include l'API Files. Carica invece con l'SDK Files per 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));
}

SDK modulare JS

L'SDK JavaScript Modular non include l'API File, quindi questo esempio chiama direttamente l'endpoint REST. Legge l'URL dello spazio di lavoro, come https://my-workspace.cloud.databricks.com, e un token dalle DATABRICKS_HOST variabili e DATABRICKS_TOKEN dell'ambiente:

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

Passo 3: Finalizza l'abilità

Finalizzando legge e valida SKILL.md, poi imposta la competenza bundle_name e description dal suo frontmatter. Se cambi il bundle in seguito, finalizza di nuovo.

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)

SDK di sviluppo Go

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

SDK modulare JS

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

Trova un'abilità

Elenca le abilità a cui puoi accedere in uno schema, poi ottieni i metadati di una abilità con il nome della risorsa.

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"

Quando la risposta della lista include next_page_token, passa come page_token nella prossima richiesta. Continua finché next_page_token non è mancante o vuoto.

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

La CLI e l'iteratore Python gestiscono la paginazione per te.

Concedi accesso

Questi esempi concedono READ VOLUME l'abilità che permette al principale di leggere l'abilità e scaricarne il pacchetto. Per gli altri privilegi delle abilità, vedi Concede accesso alle abilità.

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 con la CLI Databricks:

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

PYTHON SDK

Concedere READ VOLUME con SDK Databricks per 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])],
)

SDK di sviluppo Go

Concedere READ VOLUME con l'SDK di Databricks per 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

Concedere READ VOLUME con l'SDK di Databricks per 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)))));

Aggiornare una competenza

Questi esempi aggiornano il commento dell'abilità, l'unico campo che puoi cambiare. Il nome dell'abilità non può essere cambiato. Per modificare il contenuto di un'abilità, carica il nuovo bundle e finalizza di nuovo l'abilità.

Per un aggiornamento condizionato, prima prendi l'abilità e la etag superi con l'aggiornamento. L'aggiornamento ha successo solo se l'abilità non è cambiata da quella lettura. Codificare URL quando etag lo aggiungo a una stringa di query 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"),
)

SDK di sviluppo Go

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

SDK modulare JS

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

Eliminare una competenza

Eliminare un'abilità la rimuove insieme al suo bundle. Gli agenti non possono più caricarlo.

Puoi anche passare la corrente etag dell'abilità per rendere la cancellazione condizionata al fatto che non sia cambiata dall'ultima lettura. Codifica URL delle etag stringhe di query in 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")

SDK di sviluppo Go

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

SDK modulare JS

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

Risorse aggiuntive

Commenti e suggerimenti

Questa pagina è stata utile?

Ultimo aggiornamento: 2026-10-15