Funktionsreferens för tjänstprincip

Important

Den här funktionen finns i Beta. Kontoadministratörer kan styra åtkomsten till den här funktionen från sidan förhandsversioner av kontokonsolen. Se Hantera förhandsversioner av Azure Databricks.

En anpassad tjänstprincip är en SQL-användardefinierad funktion (UDF) som registrerats i Unity Catalog och som Azure Databricks utvärderar varje interaktion med den tjänst som den är kopplad till. Den här sidan är fält- och syntaxreferensen för dessa funktioner. För proceduren från slutpunkt till slutpunkt, se Skapa och koppla en tjänstprincip.

Funktionssignatur

En tjänstprincipfunktion tar en enskild eventVARIANT parameter och returnerar en VARIANT:

CREATE OR REPLACE FUNCTION <catalog>.<schema>.<function_name>(
  event VARIANT
)
RETURNS VARIANT
LANGUAGE SQL
RETURN <expression>;

Funktionen körs på båda utvärderingsplatserna. Förgrena på event:type::string för att skilja dem åt:

  • 'request': indatafasen (ON CALL), innan tjänsten anropas.
  • 'response': utgångsfasen (ON RESULT), efter att tjänsten svarar.

Argumentet event

event innehåller interaktionsdata och kontext. Vilka fält som är tillgängliga beror på tjänsttypen:

Fält Gäller för Beskrivning
event:type Alla tjänster Fasen: 'request' (ingång, ON CALL) eller 'response' (utgång, ON RESULT).
event:target Alla tjänster Unity-katalogens fullständiga namn på tjänsten som principen är kopplad till (valfritt).
event:context.actor.run_as Alla tjänster Den kör som-identitet som begäran auktoriserar mot.
event:context.actor.context.is_on_behalf_of Alla tjänster true när en agent eller app agerar för en användares räkning (å användarens vägnar eller OBO). Använd den för att skriva agentmedvetna principer som endast gäller när en agent agerar för en användare.
event:context.actor.context.client_id Alla tjänster OAuth-klient-ID för den tillförordnade identiteten, när det finns (OBO-anrop).
event:context.actor.context.actor_resource Alla tjänster Resursen för den tillförordnade identiteten, till exempel en agent, när den finns.
event:context.actor.context.is_actor_authenticated Alla tjänster true när den tillförordnade identiteten autentiseras som en konfidentiell klient.
event:context.tool.name, event:context.tool.arguments MCP-tjänster Verktyget som anropas och dess argument (till exempel event:context.tool.arguments.repo).
event:context.message Modelltjänster, modellprovidertjänster Det extraherade senaste användar- eller assistentmeddelandet (API-agnostisk). Använd detta för innehållskontroller.
event:data Modelltjänster, modellprovidertjänster Den fullständiga nyttolasten för begäran eller svar.
event:request_data Modelltjänster, modellprovidertjänster Den ursprungliga förfrågan, tillgänglig under utdatafasen (ON RESULT).

Anmärkning

Sökvägsåtkomst (event:...) returnerar en VARIANT. Omvandla den till en skalär typ innan du jämför den med en literal (till exempel event:type::string = 'request'); annars misslyckas jämförelsen med ett DATATYPE_MISMATCH fel.

Returvärde

En anpassad princip är en beslutsprincip: den returnerar ett VARIANT med fältet resultALLOW , DENY, eller ASK (skiftlägesokänslig) och en valfri reason. Värdet result avgör vad som händer:

  • ALLOW: interaktionen fortsätter.
  • DENY: Azure Databricks blockerar interaktionen. Istället för ett fel får anroparen ett lyckat (HTTP 200) svar vars assistent-tur rapporterar blocket, med i reason ett objekt på toppnivå databricks_service_policy .
  • ASK: interaktionen pausar för mänskligt godkännande innan du fortsätter.

Skapa resultatet med named_struct och omslut det to_variant_object så att funktionen returnerar ett VARIANT, som behåller result och reason som fält på den översta nivån. En bare named_struct returnerar en STRUCT, och CAST(... AS VARIANT) stöds inte.

to_variant_object(named_struct('result', 'DENY', 'reason', 'GitHub push operations are not permitted by policy.'))

Gatewayen accepterar också ett framåtblickande kuvertformulär:

to_variant_object(named_struct('decision', named_struct('result', 'DENY', 'reason', '...')))

Anmärkning

Fältåtkomst som inte har stängts: Åtkomst till ett fält som inte finns i parametern VARIANT genererar ett fel och resulterar i DENY (sql-standardåtkomst VARIANT returneras NULL för fält som saknas). Detta förhindrar att en princip tillåter interaktion när förväntade fält saknas.

SQL som stöds

Azure Databricks överför principtexten till CEL och utvärderar den vid körning, så funktionstexten stöder endast en begränsad delmängd av SQL. Azure Databricks avvisar en funktion eller konstruktion som inte stöds när du kopplar principen och principen misslyckas stängd (DENY) vid utvärderingen.

Kategori Stöds i principtexten
Operatorer Jämförelse,logiska och aritmetiska operatorer; \|\|, IN, LIKEoch IS [NOT] NULL
Kontrollflöde CASE och IF
Sändningar CASTtill INT/BIGINT, DOUBLE/FLOAT, STRING, eller BOOLEAN; operatorn ::
Dataåtkomst VARIANT-/JSON-sökvägsåtkomst
Strängfunktioner CONCAT, LENGTH, CHAR_LENGTH, UPPER, LOWER, SUBSTRING, TRIM, LTRIM, , RTRIM, REPLACE, STARTSWITH, , , ENDSWITHCONTAINS
Andra funktioner COALESCE, NULLIF, IFNULL, NVL, ABS, MOD, , ISNULL, ISNOTNULL, , NAMED_STRUCTTO_VARIANT_OBJECT

Stöds inte:ai_query, underfrågor, BETWEEN, mängdfunktioner, lambdas/ EXISTS, och variadic CONCAT eller COALESCE.

  • Last updated on