Référence de l’API et du SDK Skills

info

Bêta

Cette fonctionnalité est en bêta. Les administrateurs de compte peuvent gérer l’accès à cette fonctionnalité depuis la page Aperçus de la console du compte. Consultez Gérer les aperçus au niveau du compte.

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

Prérequis

Configurez un schéma gouverné pour les compétences.
Disposez des autorisations requises pour votre opération.
Installez et authentifiez le client que vous prévoyez d’utiliser. L’API REST n’a aucune exigence de version ; chaque outil et SDK a une version minimale :
- CLI de Databricks: v1.20.0 et versions ultérieures
- SDK Python: databricks-sdk 0.142.0 et versions ultérieures
- Go SDK: databricks-sdk-go v0.184.0 et versions ultérieures
- Go Modular SDK: github.com/databricks/sdk-go/aigateway v0.1.0 et au-dessus
- Java SDK: databricks-sdk-java 0.157.0 et versions ultérieures
- SDK JavaScript: @databricks/sdk-aigateway 0.23.0 et versions ultérieures
Les extraits de code du SDK supposent un client Workspace authentifié, w; les extraits de code du SDK modulaire supposent un client Unity Gateway authentifié, c en Go et client en JavaScript.

Opérations de l’API

L’ API REST des compétences fournit les opérations suivantes. Chacun nécessite également USE CATALOG et USE SCHEMA sur l’élément parent. Suivez chaque Link pour connaître ses champs, ses autorisations et ses réponses.

Opérations	Cas d'usage	Autorisations requises
Créer	Créez une compétence et provisionnez son stockage de bundle.	`CREATE VOLUME` sur le schéma
Import	Upload `SKILL.md` ainsi que tous les fichiers associés via l’API Files.	`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 les compétences auxquelles vous pouvez accéder dans un schéma.	`READ VOLUME`, `READ METADATA`, ou `MANAGE` sur la compétence
Obtenir	Lisez les métadonnées et le `etag` actuel d’une compétence.	`READ VOLUME`, `READ METADATA`, ou `MANAGE` sur la compétence
Mettre à jour	Modifiez le commentaire de la compétence.	`MANAGE` sur la compétence
Supprimer	Supprimez une compétence et son bundle.	`MANAGE` sur la compétence

Opérations	Cas d'usage	Autorisations requises
Créer	Créez une compétence et provisionnez son stockage de bundle.	`CREATE VOLUME` sur le schéma
Import	Upload `SKILL.md` ainsi que tous les fichiers associés via l’API Files.	`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 les compétences auxquelles vous pouvez accéder dans un schéma.	`READ VOLUME`, `READ METADATA`, ou `MANAGE` sur la compétence
Obtenir	Lisez les métadonnées et le `etag` actuel d’une compétence.	`READ VOLUME`, `READ METADATA`, ou `MANAGE` sur la compétence
Mettre à jour	Modifiez le commentaire de la compétence.	`MANAGE` sur la compétence
Supprimer	Supprimez une compétence et son bundle.	`MANAGE` sur la compétence

Le propriétaire de la compétence détient tous ces éléments pour cette compétence. Consultez Accorder l’accès aux compétences.

Créer une compétence

La création d’une compétence comporte trois étapes : créer la compétence, effectuer l’upload de son bundle, puis la finaliser. Jusqu’à ce que vous finalisiez une compétence, le nom et la description de son bundle sont vides.

Étape 1 : créer la compétence

Créez la compétence dans un schéma. comment est le seul champ que vous pouvez définir. Databricks déduit name, bundle_name, et description.

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

Envoyez un POST à /api/2.1/unity-catalog/skills, en transmettant parent et skill_id comme parameters de query :

Bash
databricks api post \
  "/api/2.1/unity-catalog/skills?parent=schemas/main.default&skill_id=my_skill" \
  --json '{"comment": "Team-shared math helper skill"}'

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

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

Créer et gérer une compétence avec le SDK Databricks pour Python:

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

Créez et gérez une compétence avec le Databricks SDK pour Go:

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

Créez et gérez une compétence avec le Go Modular SDK. Les champs facultatifs sont des pointeurs, c’est pourquoi l’exemple utilise une fonction auxiliaire sur une seule ligne, func ptr[T any](v T) *T { return &v }.

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

Créez et gérez une compétence avec le Databricks SDK pour Java:

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

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

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

Étape 2 : upload du bundle

Upload SKILL.md, ainsi que tous les fichiers associés, vers le chemin de stockage de la compétence, /Skills/<catalog>/<schema>/<skill>/, via l’API Files. SKILL.md doit start par un frontmatter YAML qui définit name et description. Enregistrez cet exemple sous SKILL.md:

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

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

Bash
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}\""

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

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

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

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

Le SDK modulaire Go n’inclut pas l’API Files. Effectuez plutôt l’upload avec le SDK Files pour Go :

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

Le SDK modulaire JavaScript n’inclut pas l’API Files ; cet exemple appelle donc directement l’endpoint REST. Il lit l’URL du workspace, telle que https://my-workspace.cloud.databricks.com, ainsi qu’un jeton provenant des variables d’environnement DATABRICKS_HOST et DATABRICKS_TOKEN :

TypeScript
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 bundle_name et description de la compétence à partir de son frontmatter. Si vous modifiez le bundle ultérieurement, finalisez-le à nouveau.

Bash
databricks api post "/api/2.1/unity-catalog/skills/main.default.my_skill/finalize" --json '{}'

Bash
databricks ai-gateway finalize-skill skills/main.default.my_skill

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

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

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

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

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

Rechercher une compétence

Répertoriez les compétences auxquelles vous pouvez accéder dans un schéma, puis récupérez les métadonnées d’une compétence à partir de son nom de ressource.

REST API
CLI
Python SDK

Bash
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, transmettez-le comme page_token dans la requête suivante. Continuez jusqu’à ce que next_page_token soit absent ou vide.

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

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

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

Le CLI et l’itérateur Python gèrent la pagination pour vous.

Accorder l’accès

Ces exemples accordent READ VOLUME à la compétence, ce qui permet au principal de lire la compétence et d’effectuer le download de son bundle. Pour les autres privilèges liés aux compétences, consultez Accorder l’accès aux compétences.

REST API
CLI
Python SDK
Go SDK
Java SDK

Bash
databricks api patch \
  "/api/2.1/unity-catalog/permissions/skill/main.default.my_skill" \
  --json '{
    "changes": [
      { "principal": "data-team", "add": ["READ_VOLUME"] }
    ]
  }'

Accorder READ VOLUME avec la CLI Databricks :

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

Accorder READ VOLUME avec le SDK Databricks pour Python:

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

Accordez READ VOLUME à l’aide du SDK Databricks pour Go:

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

Accordez READ VOLUME à l’aide du SDK Databricks pour Java:

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 modifier. Le nom de la compétence ne peut pas être modifié. Pour modifier le contenu d’une compétence, upload le nouveau bundle et finalisez à nouveau la compétence.

Pour effectuer une mise à jour conditionnelle, commencez par récupérer la compétence et transmettez son etag avec la mise à jour. La mise à jour réussit uniquement si la compétence n’a pas changé depuis sa lecture. Encodez etag au format URL lorsque vous l’ajoutez à une chaîne de query REST.

Bash
databricks api patch \
  "/api/2.1/unity-catalog/skills/main.default.my_skill?update_mask=comment" \
  --json '{"comment": "Updated: team-shared math helper"}'

Bash
databricks ai-gateway update-skill skills/main.default.my_skill comment \
  --json '{"comment": "Updated: team-shared math helper"}'

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

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

TypeScript
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

La suppression d’une compétence supprime celle-ci ainsi que son bundle. Les agents ne peuvent plus la charger.

Vous pouvez également transmettre le etag actuel de la compétence afin que la suppression ne soit effectuée que s’il n’a pas changé depuis la dernière lecture. Encodez le etag au format URL dans les chaînes de query REST.

Bash
databricks api delete "/api/2.1/unity-catalog/skills/main.default.my_skill"

Bash
databricks ai-gateway delete-skill skills/main.default.my_skill

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

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

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

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

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

Prérequis​

Opérations de l’API​

Créer une compétence​

Étape 1 : créer la compétence​

Étape 2 : upload du bundle​

Étape 3 : finaliser la compétence​

Rechercher une compétence​

Accorder l’accès​

Mettre à jour une compétence​

Supprimer une compétence​

Ressources supplémentaires​