API навыков и справочник по SDK

Important

Эта функция доступна в бета-версии. Администраторы учетных записей могут управлять доступом к этой функции на странице «Предварительные версии» в консоли учетной записи. См. статью "Управление предварительными версиями на уровне учетной записи".

Используйте эти примеры для автоматизации управления навыками. API представляет каждый навык в виде Skill ресурса с названием skills/{catalog}.{schema}.{skill}. Чтобы написать и опубликовать навык с агентом, смотрите раздел «Создать и поделиться навыками». О привилегиях и управлении см. раздел «Навыки управления». У навыков нет ресурсов Terraform или Declarative Automation Bundles.

Необходимые условия

Создайте управляемую схему для навыков.
Имейте необходимые разрешения для вашей операции.
Установите и аутентифицируйте клиента, который планируете использовать. REST API не требует версии; у каждого инструмента и SDK есть минимальная версия:
- Databricks CLI: версия 1.20.0 и выше
- Python SDK: databricks-sdk 0.142.0 и выше
- Go SDK: databricks-sdk-go версия 0.184.0 и выше
- Go Modular SDK: github.com/databricks/sdk-go/aigateway версия 0.1.0 и выше
- Java SDK: databricks-sdk-java 0.157.0 и выше
- JavaScript SDK: @databricks/sdk-aigateway 0.23.0 и выше
Фрагменты SDK предполагают аутентифицированный клиент рабочего пространства, w; Модульные SDK-фрагменты предполагают аутентифицированный клиент Unity Gateway, c как в Go и client JavaScript.

Операции API

API Skills REST обеспечивает эти операции. Каждый также требует USE CATALOG и USE SCHEMA на родителя. Перейдите по каждой ссылке для получения её полей, разрешений и ответов.

Operation	Сценарий использования	Необходимые разрешения
Создать	Создайте навык и предоставите хранилище его пакета.	`CREATE VOLUME` на схеме
Upload	Загружайте `SKILL.md` и отправляйте все поддерживающие файлы через API файлов.	`WRITE VOLUME` и `READ VOLUME` по мастерству
завершение	Читайте и проверяйте `SKILL.md`, затем задайте название и описание навыка.	`READ VOLUME` О навыке
Список	Найдите навыки, доступные в схеме.	`READ VOLUME`, `READ METADATA`, или `MANAGE` по навыку
Get	Читайте метаданные и текущие `etag`данные навыка.	`READ VOLUME`, `READ METADATA`, или `MANAGE` по навыку
Update	Измените комментарий к навыку.	`MANAGE` О навыке
Удалить	Удалите навык и его набор.	`MANAGE` О навыке

Владелец навыка держит всё это на навыке. См. Предоставление доступа к навыкам.

Создание навыка

Создание навыка требует трёх шагов: создать навык, загрузить его набор, а затем завершить его. Пока вы не завершите навык, его название и описание в наборе пусты.

Шаг 1: Создайте навык

Создайте навык в схеме. comment это единственное поле, которое вы можете установить. Azure Databricks выводит name, bundle_name, и description.

Замените main.default.my_skill и data-team собственными значениями.

REST API

Отправьте POST запрос в /api/2.1/unity-catalog/skills, передавая parent и skill_id как параметры запроса:

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

Передайте основную схему и имя навыка, а также приведите комментарий:--json

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

пакет SDK Python

Создайте и управляйте навыком с помощью SDK Databricks для 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 для GO

Создайте и управляйте навыком с помощью Databricks SDK для 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

Создайте и управляйте навыком с помощью SDK Go Modular. Необязательные поля являются указателями, поэтому в примере используется однострочная вспомогательная функция, 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")},
})

пакет SDK для Java

Создайте и управляйте навыком с помощью Databricks SDK для 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

Создайте и управляйте навыком с помощью JavaScript SDK:

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

Шаг 2: Загрузите пакет

Загрузите SKILL.md, и все поддерживающие файлы в путь хранения навыка /Skills/<catalog>/<schema>/<skill>/через API Files. SKILL.md должен начинать с YAML-фронтматера, который устанавливает name и description. Сохраните этот пример как 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

Отправьте в PUTAPI файлов. Установите DATABRICKS_HOST URL вашего рабочего пространства, например https://my-workspace.cloud.databricks.com, и DATABRICKS_TOKEN токен. В этом примере токен передаётся curl на стандартном входе, поэтому он не отображается в списке процессов:

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

Создайте папку навыка, затем скопируйте файл в неё:

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

пакет SDK Python

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

Пакет 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,
})

Go Modular SDK

В SDK Go Modular нет API Files. Загрузите с помощью SDK файлов для 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))

пакет 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));
}

JS Modular SDK

JavaScript Modular SDK не включает API файлов, поэтому в этом примере напрямую вызывается конечная точка REST. Он читает URL рабочего пространства, например https://my-workspace.cloud.databricks.com, и токен из DATABRICKS_HOST переменных среды и 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}`);
}

Шаг 3: Завершите навык

Финализация считывает и валидирует SKILL.md, затем устанавливает навык bundle_name и description исходя из его фронта. Если позже измените пакет, завершите снова.

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

пакет SDK Python

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

Пакет SDK для 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"),
})

пакет SDK для Java

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

Найди навык

Перечислите навыки, которые можно получить в схеме, затем получите метаданные навыка по названию ресурса.

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"

Когда ответ в списке включает next_page_token, передайте его как page_token в следующем запросе. Продолжайте, пока next_page_token не отсутствует или не опустеет.

CLI

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

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

пакет 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")

Итератор CLI и Python занимается пагинацией за вас.

Предоставление доступа

Эти примеры дают READ VOLUME навык, который позволяет директору прочитать навык и скачать его набор. О других привилегиях навыков см. раздел «Предоставление доступа к навыкам».

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

Грант READ VOLUME с Databricks CLI:

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

пакет SDK Python

Предоставление READ VOLUME с помощью 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])],
)

Пакет SDK для GO

Предоставление READ VOLUME с помощью Databricks SDK for 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},
	}},
})

пакет SDK для Java

Предоставьте доступ READ VOLUME с помощью Databricks SDK for 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)))));

Обновить навык

Эти примеры обновляют комментарий к навыку — единственное поле, которое можно изменить. Название навыка нельзя изменить. Чтобы изменить содержимое навыка, загрузите новый набор и снова завершите навык.

Для условного обновления сначала возьмите навык и передайте его etag вместе с обновлением. Обновление работает только если навык не изменился с тех пор. URL-кодирование при etag добавлении его в строку запроса 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"}'

пакет 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"),
)

Пакет 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"},
})

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

пакет 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")));

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

Удалить навык

Удаление навыка убирает его и его набор. Агенты больше не могут его загружать.

Вы также можете передавать текущий etag уровень навыка, чтобы удаление было зависеть от того, что оно не изменилось с момента последнего прочтения. URL-кодировать etag строки запроса в 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

пакет SDK Python

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

Пакет SDK для 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"),
})

пакет SDK для Java

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

JS Modular SDK

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

Дополнительные ресурсы

Обратная связь

Были ли сведения на этой странице полезными?

Последнее обновление: 2026-10-15