Dienstrichtlinienfunktionsreferenz

Wichtig

Dieses Feature befindet sich in der Betaversion. Kontoadministratoren können den Zugriff auf dieses Feature über die Seite " Vorschau" der Kontokonsole steuern. Siehe Manage Azure Databricks Previews.

Eine benutzerdefinierte Dienstrichtlinie ist eine benutzerdefinierte SQL-Funktion (User-Defined Function, UDF), die im Unity-Katalog registriert ist, die Azure Databricks für jede Interaktion mit dem Dienst ausgewertet wird, an den sie angefügt ist. Diese Seite ist der Feld- und Syntaxverweis für diese Funktionen. Die End-to-End-Prozedur finden Sie unter Erstellen und Anfügen einer Dienstrichtlinie.

Funktionssignatur

Eine Dienstrichtlinienfunktion verwendet einen einzelnen eventVARIANT Parameter und gibt folgendes VARIANTzurück:

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

Die Funktion wird an beiden Auswertungspunkten ausgeführt. Verzweigen Sie weiter event:type::string , um sie auseinander zu setzen:

  • 'request': die Eingabephase (ON CALL), bevor der Dienst aufgerufen wird.
  • 'response': die Ausgangsphase (ON RESULT), nachdem der Dienst reagiert.

Das event Argument

event trägt die Interaktionsdaten und den Kontext. Die verfügbaren Felder hängen vom Diensttyp ab:

Field Gilt für: Description
event:type Alle Dienste Die Phase: 'request' (Eingang, ON CALL) oder 'response' (Ausgang, ON RESULT).
event:target Alle Dienste Der vollständige Name des Unity-Katalogs des Diensts, dem die Richtlinie angefügt ist (optional).
event:context.actor.run_as Alle Dienste Die Run-as-Identität, für die die Anforderung autorisiert wird.
event:context.actor.context.is_on_behalf_of Alle Dienste true wenn ein Agent oder eine App im Namen eines Benutzers (im Auftrag von oder OBO) handelt. Verwenden Sie sie, um Agent-fähige Richtlinien zu schreiben, die nur gelten, wenn ein Agent für einen Benutzer fungiert.
event:context.actor.context.client_id Alle Dienste Die OAuth-Client-ID der handelnden Identität, wenn vorhanden (OBO-Aufrufe).
event:context.actor.context.actor_resource Alle Dienste Die Ressource der handelnden Identität, z. B. eines Agents, wenn vorhanden.
event:context.actor.context.is_actor_authenticated Alle Dienste true wenn die handelnde Identität als vertraulicher Client authentifiziert wurde.
event:context.tool.name, event:context.tool.arguments MCP-Dienste Das aufgerufene Tool und seine Argumente (z. B event:context.tool.arguments.repo. ).
event:context.message Modelldienste, Modellanbieterdienste Die extrahierte letzte Benutzer- oder Assistentennachricht (API-agnostic). Verwenden Sie dies für Inhaltsüberprüfungen.
event:data Modelldienste, Modellanbieterdienste Die vollständige Anforderungs- oder Antwortnutzlast.
event:request_data Modelldienste, Modellanbieterdienste Die ursprüngliche Anfrage, verfügbar während der Ausgabephase (ON RESULT).

Hinweis

Pfadzugriff (event:...) gibt einen VARIANT. Cast it to a scalar type before comparison it to a literal (for example, event:type::string = 'request'); otherwise the comparison fails with a DATATYPE_MISMATCH error.

Zurückgegebener Wert

Eine benutzerdefinierte Richtlinie ist eine Entscheidungsrichtlinie: Sie gibt ein VARIANT Feld von result, oder ALLOWDENY (Groß-/Kleinschreibung) und eine optionale ASK.reason Der result Wert bestimmt, was passiert:

  • ALLOW: Die Interaktion wird fortgesetzt.
  • DENY: Azure Databricks blockiert die Interaktion. Anstelle eines Fehlers erhält der Anrufer eine erfolgreiche (HTTP 200) Antwort, deren Assistenten-Turn den Block meldet, wobei sich das reason in einem obersten Objekt databricks_service_policy befindet.
  • ASK: Die Interaktion wird vor dem Fortfahren für die menschliche Genehmigung angehalten.

Erstellen Sie das Ergebnis mit named_struct und umschließen Sie es so to_variant_object , dass die Funktion ein VARIANT, beibehaltenes result und reason als Felder der obersten Ebene zurückgibt. Eine Bare named_struct gibt ein STRUCT, und CAST(... AS VARIANT) wird nicht unterstützt.

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

Das Gateway akzeptiert auch ein zukunftsgerichtetes Umschlagformular:

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

Hinweis

Fehler beim schließenden Feldzugriff: Der Zugriff auf ein Feld, das nicht im VARIANT Parameter vorhanden ist, löst einen Fehler aus und führt zu DENY einem Fehler (standard SQL VARIANT access returns NULL for missing fields). Dadurch wird verhindert, dass eine Richtlinie eine Interaktion zulässt, wenn erwartete Felder fehlen.

Unterstützte SQL

Azure Databricks transpiliert den Richtlinientext in CEL und wertet ihn zur Laufzeit aus, sodass der Funktionstext nur eine eingeschränkte Teilmenge von SQL unterstützt. Azure Databricks lehnt eine nicht unterstützte Funktion ab oder erstellt, wenn Sie die Richtlinie anfügen, und die Richtlinie schlägt bei der Auswertung geschlossen (DENY) fehl.

Kategorie Unterstützt im Richtlinientext
Betriebspersonal Vergleichs-, logische und arithmetische Operatoren; \|\|, IN, , LIKEund IS [NOT] NULL
Kontrollfluss CASE und IF
Wirft CASTan INT/BIGINT, DOUBLE/FLOAT, , STRINGoder BOOLEAN; der :: Operator
Datenzugriff VARIANT /JSON-Pfadzugriff
Zeichenfolgenfunktionen CONCAT, LENGTH, , CHAR_LENGTH, UPPER, LOWERSUBSTRING, TRIM, , LTRIM, RTRIM, , REPLACESTARTSWITH, , ENDSWITHCONTAINS
Andere Funktionen COALESCE, NULLIF, , IFNULLNVL, ABS, MOD, ISNULL, , , ISNOTNULL, , NAMED_STRUCTTO_VARIANT_OBJECT

Nicht unterstützt:ai_query, Unterabfragen, BETWEEN, Aggregatfunktionen, Lambdas / EXISTSund variadisch CONCAT oder COALESCE.

  • Last updated on