API des compétences et référence SDK

Important

Cette fonctionnalité est en version bêta. Les administrateurs de compte peuvent gérer l’accès à cette fonctionnalité à partir de la page Aperçus de la console de compte. Consultez Gérer les versions préliminaires du compte.

Utilisez ces exemples pour automatiser la gestion des compétences. L’API représente chaque compétence comme une Skill ressource nommée skills/{catalog}.{schema}.{skill}. Pour rédiger et publier une compétence avec un agent, voir Créer et partager des compétences. Pour les privilèges et la gouvernance, voir Compétences de gouvernance. Les compétences ne disposent pas de ressources Terraform ni Declarative Automation Bundles.

Conditions préalables

  • Mettez en place un schéma gouverné pour les compétences.

  • Ayez les autorisations nécessaires pour votre exploitation.

  • Installez et authentifiez le client que vous comptez utiliser. L’API REST n’a aucune exigence de version ; chaque outil et SDK a une version minimale :

    • Databricks CLI : v1.20.0 et versions supérieures
    • SDK Python : databricks-sdk 0.142.0 et plus
    • Go SDK : databricks-sdk-go v0.184.0 et plus
    • Go Modular SDK : github.com/databricks/sdk-go/aigateway v0.1.0 et supérieur
    • Java SDK : databricks-sdk-java 0.157.0 et au-dessus
    • SDK JavaScript : @databricks/sdk-aigateway 0.23.0 et supérieur

    Les extraits de SDK supposent un client d’espace de travail authentifié, w; Les extraits de SDK modulaires supposent un client Unity Gateway authentifié, c dans Go et client en JavaScript.

Opérations d’API

L’API Skills REST fournit ces opérations. Chacun nécessite USE CATALOG également et USE SCHEMA sur le parent. Suivez chaque lien pour ses champs, permissions et réponses.

Operation Cas d’utilisation Autorisations requises
Créer Créez une compétence et provisionnez son stockage en bundle. CREATE VOLUME dans le schéma
Upload Téléverser SKILL.md et tout fichier de support via l’API des fichiers. WRITE VOLUME et READ VOLUME sur la compétence
Finaliser Lisez et validez SKILL.md, puis définissez le nom et la description du bundle de la compétence. READ VOLUME sur la compétence
Liste Trouvez des compétences accessibles dans un schéma. READ VOLUME, READ METADATA, ou MANAGE sur la compétence
Obtenir Lisez les métadonnées d’une compétence et les fichiers actuels etagde la compétence. READ VOLUME, READ METADATA, ou MANAGE sur la compétence
Update Changez le commentaire de la compétence. MANAGE sur la compétence
Supprimer Supprimez une compétence et son ensemble. MANAGE sur la compétence

Le propriétaire de la compétence détient tout cela sur la compétence. Voir Accorder l’accès aux compétences.

Créer une compétence

Créer une compétence prend trois étapes : créer la compétence, télécharger son bundle, puis la finaliser. Jusqu’à ce que vous finalisiez une compétence, son nom et sa description du bundle restent vides.

Étape 1 : Créer la compétence

Créez la compétence dans un schéma. comment c’est le seul champ que tu peux définir. Azure Databricks dérive name, bundle_name, et description.

Remplacez main.default.my_skill et data-team par vos propres valeurs.

REST API

Envoyez un POST à /api/2.1/unity-catalog/skills, en passant parent et skill_id comme paramètres de requête :

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

Passez le schéma parent et le nom de la compétence, et fournissez le commentaire avec --json:

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

Kit de développement logiciel (SDK) Python

Créez et gérez une compétence avec le SDK Databricks pour 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"),
)

Kit de développement logiciel (SDK) Go

Créez et gérez une compétence avec le SDK Databricks for 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"},
})

SDK modulaire Go

Créez et gérez une compétence avec le SDK modulaire Go. Les champs optionnels sont des pointeurs, donc l’exemple utilise un assistant en une ligne, 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")},
})

Kit de développement logiciel (SDK) Java

Créez et gérez une compétence avec le SDK Databricks pour 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 modulaire JS

Créez et gérez une compétence avec le SDK JavaScript :

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

Étape 2 : Téléchargez le bundle

Téléverser SKILL.md, ainsi que tous les fichiers supportés, sur le chemin de stockage de la compétence, /Skills/<catalog>/<schema>/<skill>/, via l’API des fichiers. SKILL.md doit commencer par un frontmatter YAML qui définit name et description. Enregistrez cet exemple comme SKILL.mdsuit :

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

Envoyez A PUT à l’API des fichiers. Définissez DATABRICKS_HOST à l’URL de votre espace de travail, comme https://my-workspace.cloud.databricks.com, et DATABRICKS_TOKEN à un jeton. Cet exemple transmet le jeton à curl une entrée standard afin qu’il n’apparaisse pas dans la liste des processus :

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

Créez le dossier de la compétence, puis copiez le fichier dedans :

databricks fs mkdir dbfs:/Skills/main/default/my_skill
databricks fs cp SKILL.md dbfs:/Skills/main/default/my_skill/SKILL.md --overwrite

Kit de développement logiciel (SDK) Python

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

Kit de développement logiciel (SDK) 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,
})

SDK modulaire Go

Le SDK Go Modular n’inclut pas l’API Files. Téléchargez avec le SDK Fichiers pour Go à la place :

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

Kit de développement logiciel (SDK) Java

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 modulaire JS

Le SDK modulaire JavaScript n’inclut pas l’API Files, donc cet exemple appelle directement le point de terminaison REST. Il lit l’URL de l’espace de travail, comme https://my-workspace.cloud.databricks.com, et un jeton provenant des DATABRICKS_HOST variables d’environnement et DATABRICKS_TOKEN :

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

Étape 3 : Finaliser la compétence

La finalisation lit et valide SKILL.md, puis définit la compétence bundle_name et description de son matériau principal. Si vous changez le bundle plus tard, finalisez à nouveau.

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

Kit de développement logiciel (SDK) Python

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

Kit de développement logiciel (SDK) Go

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

SDK modulaire Go

finalized, err := c.FinalizeSkill(ctx, aigateway.FinalizeSkillRequest{
	Name: ptr("skills/main.default.my_skill"),
})

Kit de développement logiciel (SDK) Java

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

SDK modulaire JS

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

Trouvez une compétence

Listez les compétences auxquelles vous pouvez accéder dans un schéma, puis obtenez les métadonnées d’une compétence par le nom de sa ressource.

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"

Lorsque la réponse de la liste inclut next_page_token, passe comme page_token dans la demande suivante. Continuez jusqu’à ce next_page_token qu’il soit absent ou vide.

CLI

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

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

Kit de développement logiciel (SDK) Python

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 et l’itérateur Python gèrent la pagination pour vous.

Accorder l'accès

Ces exemples accordent READ VOLUME une compétence, ce qui permet au principal de lire la compétence et de télécharger son pack. Pour les autres privilèges de compétence, voir Accorder l’accès aux compétences.

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 avec la interface de code de Databricks :

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

Kit de développement logiciel (SDK) Python

Accorder READ VOLUME avec le Databricks SDK for 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])],
)

Kit de développement logiciel (SDK) Go

Accorder READ VOLUME avec le SDK Databricks pour 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},
	}},
})

Kit de développement logiciel (SDK) Java

Subvention READ VOLUME avec le SDK Databricks pour 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)))));

Mettre à jour une compétence

Ces exemples mettent à jour le commentaire de la compétence, le seul champ que vous pouvez changer. Le nom de la compétence ne peut pas être changé. Pour modifier le contenu d’une compétence, téléchargez le nouveau pack et finalisez à nouveau la compétence.

Pour une mise à jour conditionnelle, obtiens d’abord la compétence et la etag réussis avec la mise à jour. La mise à jour ne réussit que si la compétence n’a pas changé depuis cette lecture. Encoder URL lors etag de l’ajout à une chaîne de requête 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"}'

Kit de développement logiciel (SDK) Python

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

Kit de développement logiciel (SDK) 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"},
})

SDK modulaire Go

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

Kit de développement logiciel (SDK) Java

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

Supprimer une compétence

Supprimer une compétence la supprime, elle et son bundle. Les agents ne peuvent plus le charger.

Vous pouvez aussi transmettre le courant etag de la compétence pour conditionner la suppression au fait qu’elle n’ait pas changé depuis la dernière lecture. Encodage URL des etag chaînes de requête 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

Kit de développement logiciel (SDK) Python

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

Kit de développement logiciel (SDK) Go

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

SDK modulaire Go

err := c.DeleteSkill(ctx, aigateway.DeleteSkillRequest{
	Name: ptr("skills/main.default.my_skill"),
})

Kit de développement logiciel (SDK) Java

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

SDK modulaire JS

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

Ressources additionnelles

  • Dernière mise à jour :