Zarządzanie uprawnieniami pamięci agenta i magazynów sesji

Important

Ta funkcja jest dostępna w wersji beta. Aby z niego korzystać, administrator przestrzeni roboczej musi włączyć Sesje pamięci Agenta na stronie Podglądów . Zobacz Zarządzanie wersjami zapoznawczami usługi Azure Databricks.

Magazyny pamięci agenta i magazyny sesji korzystają z tego samego modelu uprawnień na poziomie magazynu. Uprawnienie dotyczy zawartości magazynu: każdego wpisu pamięci w magazynie pamięci lub każdej sesji i elementu sesji w magazynie sesji.

Możesz przyznać dostęp użytkownikowi Azure Databricks lub jednostce usługi. Identyfikuj użytkownika przez e-mail, a nazwę główną usługi według identyfikatora aplikacji (klienta). Uprawnienia do sklepu nie obsługują grup.

Requirements

Model dostępu na poziomie sklepu

Magazyn to granica bezpieczeństwa. Pola takie jak actor_id, session_id, path i metadata organizują i filtrują dane, ale nie ograniczają dostępu. Podmiot posiadający dostęp do sklepu może uzyskać dostęp do danych dla każdego aktora w sklepie. Aby odizolować dane między dzierżawami lub użytkownikami, utwórz osobne repozytorium dla każdej granicy izolacji.

Uprawnienia do sklepu mają następujące poziomy:

Pozwolenie Odczyt danych z magazynu Zapisz dane magazynu
READ Yes No
WRITE Yes Yes. WRITE zawiera element READ.
Brak dostępu No No. Nie możesz nadać tego statusu. Aby usunąć jawny dostęp podmiotu, użyj operacji Revoke. Operacja Get raportuje ten stan jako PERMISSION_LEVEL_UNSPECIFIED.

Tylko twórca sklepu i administratorzy przestrzeni roboczej mogą zarządzać uprawnieniami:

  • Twórca sklepu ma domyślny WRITE dostęp i może przyznawać, wyświetlać i cofać uprawnienia. Nie możesz odebrać twórcy praw własności.
  • Administrator przestrzeni roboczej może przyznawać, wyświetlać i cofać uprawnienia dla dowolnego sklepu w przestrzeni roboczej. Bycie administratorem przestrzeni roboczej samo w sobie nie daje dostępu do danych. Administrator bez istniejącego dostępu do danych musi nadać sobie READ lub WRITE, aby korzystać ze sklepu.
  • Użytkownik lub podmiot usługi z READ lub WRITE może korzystać z magazynu, ale nie może zarządzać jego uprawnieniami.

Dostęp dziedziczony wynika z członkostwa w roli Postgres w bazowym projekcie Lakebase, takiej jak rola databricks_superuser. Operacje na uprawnieniach sklepu nie zmieniają przynależności do tych ról. Zobacz artykuł Zarządzanie uprawnieniami dla ról Postgres.

Operacje uprawnień

Uprawnienia sklepu obsługują cztery operacje:

Operation Behavior
Grant Przyznaje READ lub WRITE jednemu użytkownikowi lub nazwie głównej usługi. Operacja jest idempotentna. Przyznanie READ podmiotowi zabezpieczeń, który ma już WRITE, nie obniża poziomu istniejącego uprawnienia.
Get Każdy uwierzytelniony wywołujący może uruchomić Get. Zwraca jedynie skuteczne uprawnienia wywołującego, w tym niejawny dostęp twórcy oraz dostęp dziedziczony. Zwraca PERMISSION_LEVEL_UNSPECIFIED, gdy wywołujący nie ma dostępu.
List Zwraca jawne uprawnienia użytkownikom i jednostkom usługi. Nie obejmuje on niejawnego dostępu twórcy, uprawnień administratora przestrzeni roboczej oraz dostępu dziedziczonego. Pusty wynik nie dowodzi, że żaden podmiot nie może uzyskać dostępu do magazynu certyfikatów.
Revoke Usuwa zarówno jawne granty READ, jak i jawne granty WRITE z jednego podmiotu zabezpieczeń. Operacja jest idempotentna. Nie usuwa własności ani dziedziczonego dostępu.

API List REST używa domyślnego rozmiaru strony 100 grantów i obsługuje do 1 000 grantów na stronę. SDK AgentKit automatycznie śledzi wszystkie strony. W CLI Agent Bricks użyj --all, aby zwrócić każdą stronę.

Aby obniżyć poziom podmiotu zabezpieczeń z WRITE do READ, cofnij istniejące przyznanie, a następnie przyznaj READ. Te operacje nie są atomowe, więc podmiot zabezpieczeń nie ma wyraźnego dostępu między tymi dwoma wywołaniami.

Zarządzaj uprawnieniami sklepu

Poniższe przykłady zarządzają uprawnieniami w magazynie pamięci. Dla magazynu sesji używaj sessions stores zamiast memory stores w Agent Bricks CLI, client.session_stores.get("<store-name>") w AgentKit SDK lub session-stores/<store-name> w ścieżce REST API.

Agent Bricks

Polecenia uprawnień akceptują te same identyfikatory sklepu co pozostałe polecenia sklepu. Magazyny pamięci przyjmują identyfikator magazynu, nazwę zasobu lub jednoznaczną nazwę wyświetlaną. Magazyny sesyjne akceptują nazwę magazynu lub nazwę zasobu.

Aby przyznać użytkownikowi dostęp do odczytu, wykonaj następujące procedury:

agentbricks memory stores permissions grant <store-id> \
  --user teammate@example.com --permission READ

Aby przyznać dostęp do zapisu jednostce usługi, wykonaj poniższe. Przekaż ID aplikacji jednostki usługi:

agentbricks memory stores permissions grant <store-id> \
  --service-principal <application-id> --permission WRITE

Aby uzyskać swoje efektywne uprawnienia, uruchom następujące polecenie:

agentbricks memory stores permissions get <store-id>

Aby wyświetlić wszystkie jawnie przyznane uprawnienia, uruchom następujące polecenie jako twórca sklepu lub administrator obszaru roboczego:

agentbricks memory stores permissions list <store-id> --all

Aby odebrać użytkownikowi jawnie przyznany dostęp, wykonaj następujące polecenie. Opcja --yes pomija monit potwierdzenia:

agentbricks memory stores permissions revoke <store-id> \
  --user teammate@example.com --yes

AgentKit SDK

Metody uprawnień są dostępne zarówno dla obiektów MemoryStore, jak i SessionStore. Poniższy przykład przekazuje poziom uprawnień i typ podmiotu zabezpieczeń wprost:

from databricks.sdk import WorkspaceClient
from databricks_agentkit import AgentKitClient

client = AgentKitClient(WorkspaceClient())
store = client.memory_stores.get("<store-id>")

# Grant a user read access.
store.grant_permission(
    "teammate@example.com",
    principal_type="USER",
    permission="READ",
)

# Return the authenticated caller's effective permission.
permission = store.get_permission()
print(permission.principal.name, permission.permission)

# List every explicit grant.
for grant in store.list_permissions(page_size=100):
    print(grant.principal.name, grant.principal.principal_type, grant.permission)

# Remove the user's explicit READ and WRITE grants.
store.revoke_permission("teammate@example.com", principal_type="USER")

grant_permission() i revoke_permission() używają SERVICE_PRINCIPAL jako domyślnego typu podmiotu. grant_permission() używa WRITE jako domyślnego uprawnienia. Przekażcie oba argumenty wyraźnie, gdy przyznajecie użytkownikowi dostęp lub dostęp tylko do odczytu.

interfejs API REST

Punkty końcowe uprawnień znajdują się pod /api/2.0/agents/memory-stores/<store-id>/permissions. Treść żądania identyfikuje użytkownika za pomocą USER i jednostkę usługi za pomocą SERVICE_PRINCIPAL.

Ustaw DATABRICKS_HOST na adres URL swojego workspace, w tym https://, oraz DATABRICKS_TOKEN na token dostępu.

Aby udzielić użytkownikowi dostępu do odczytu, wywołaj operację Grant:

curl -X POST "${DATABRICKS_HOST}/api/2.0/agents/memory-stores/<store-id>/permissions:grant" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "principal": {"principal_type": "USER", "name": "teammate@example.com"},
    "permission": "READ"
  }'

Aby uzyskać efektywne uprawnienie uwierzytelnionego wywołującego, wywołaj operację Get:

curl "${DATABRICKS_HOST}/api/2.0/agents/memory-stores/<store-id>/permissions/self" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Aby wyświetlić jawne uprawnienia, wywołaj operację List jako twórca magazynu lub administrator obszaru roboczego:

curl "${DATABRICKS_HOST}/api/2.0/agents/memory-stores/<store-id>/permissions?page_size=100" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Aby unieważnić użytkownikowi jawny dostęp, wywołaj operację Revoke:

curl -X POST "${DATABRICKS_HOST}/api/2.0/agents/memory-stores/<store-id>/permissions:revoke" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "principal": {"principal_type": "USER", "name": "teammate@example.com"}
  }'

Operacje Grant and Revoke nie zwracają obiektu uprawnień. Aby zweryfikować zmianę, uruchom List jako twórcę sklepu lub administratora przestrzeni roboczej. Aby sprawdzić efektywny dostęp, uwierzytelnij się jako dany principal i uruchom Get.

Uprawnienia zarządzane przez wdrożenie agenta

Gdy projekt agenta deklaruje magazyn pamięci lub sesji, agentbricks deploy przyznaje jednostce usługi wdrożonej aplikacji dostęp do tego magazynu. Późniejsze wdrożenie może przywrócić dostęp, który odebrałeś ręcznie.

Odłączenie magazynu usuwa wiązanie z projektu agenta. Nie cofa dostępu już przyznanego nazwie głównej usługi aplikacji. Użyj operacji Revoke, aby usunąć ten dostęp.

Dodatkowe zasoby

Resource Description
Pamięć agenta Daj agentom pamięć długotrwałą, która utrzymuje się między oddzielnymi rozmowami.
Sesje agentów Przechowuj historię rozmów agenta, aby mógł wznowić interakcję pomiędzy kolejnymi turami.
  • Ostatnia aktualizacja o