Freigeben über


Was ist eine dynamische Wertreferenz?

Dynamische Wertverweise beschreiben eine Sammlung von Variablen, die beim Konfigurieren von Aufträgen und Aufgaben verfügbar sind. Verwenden Sie dynamische Wertverweise, um bedingte Anweisungen für Vorgänge zu konfigurieren oder Informationen als Parameter oder Argumente zu übergeben.

Dynamische Wertverweise enthalten Informationen wie:

  • Konfigurierte Werte für den Auftrag, einschließlich Auftragsname, Aufgabennamen und Triggertyp.
  • Generierte Metadaten über den Auftrag, einschließlich der Auftragskennung, der Laufkennung und der Startzeit des Auftragslaufs.
  • Informationen darüber, wie viele Reparaturversuche ein Auftrag unternommen hat oder wie viele Wiederholungsversuche für eine Aufgabe durchgeführt wurden.
  • Der Ergebnisstatus für einen angegebenen Vorgang.
  • Werte, die mithilfe von Auftragsparametern, Vorgangsparametern oder Vorgangswerten konfiguriert wurden.

Dynamische Wertverweise verwenden

Verwenden Sie dynamische Wertverweise beim Konfigurieren von Aufträgen oder Aufgaben. Sie können nicht direkt auf dynamische Wertverweise von Ressourcen verweisen, die mit Aufgaben wie Notebooks, Abfragen oder JARs konfiguriert sind. Dynamische Wertverweise müssen mit Hilfe von Parametern oder Feldern definiert werden, die den Kontext an die Aufgaben weitergeben.

Dynamische Wertverweise verwenden doppelte geschweifte Klammern ({{ }}). Wenn ein Auftrag oder eine Aufgabe ausgeführt wird, ersetzt ein Zeichenfolgenliteral den dynamischen Wertverweis. Wenn Sie beispielsweise das folgende Schlüssel-Wert-Paar als Aufgabenparameter konfigurieren:

{"job_run_id": "job_{{job.run_id}}"}

Wenn Ihre Lauf-ID 550315892394120 ist, wird der Wert für job_run_id als job_550315892394120 ausgewertet.

Hinweis

Inhalte zwischen zwei geschweiften Klammern werden nicht als Ausdruck ausgewertet. Sie können keine Vorgänge oder Funktionen innerhalb von geschweiften Klammern ausführen.

Vom Benutzer bereitgestellte Wertbezeichner unterstützen alphanumerische Zeichen und Unterstriche. Escapetasten, die Sonderzeichen enthalten, indem sie den Bezeichner mit Backticks (` `) umgeben.

Syntaxfehler, einschließlich nicht vorhandener dynamischer Referenzwerte und fehlender geschweifter Klammern, werden stillschweigend ignoriert und als literale Zeichenfolgen behandelt. Eine Fehlermeldung wird angezeigt, wenn Sie einen ungültigen Verweis angeben, der zu einem bekannten Namespace gehört, z. B. {{job.notebook_url}}.

Verwendung dynamischer Wertverweise in der Benutzeroberfläche von Jobs

Felder, die dynamische Wertreferenzen akzeptieren, bieten eine Abkürzung zum Einfügen verfügbarer dynamischer Wertreferenzen. Klicken Sie auf { }, um diese Liste anzuzeigen und in das angegebene Feld einzufügen.

Hinweis

Die Benutzeroberfläche vervollständigt die Schlüssel nicht automatisch, um auf Aufgabenwerte zu verweisen.

Viele Felder, die dynamische Wertverweise akzeptieren, erfordern zusätzliche Formatierungen, um sie richtig zu verwenden. Weitere Informationen finden Sie unter Konfigurieren von Aufgabenparametern.

Verwendung dynamischer Wertverweise in einem Auftrags-JSON

Verwenden Sie die {{ }}-Syntax, um dynamische Werte in den JSON-Definitionen von Databricks CLI und REST API zu verwenden.

Auftrags- und Aufgabenparameter haben eine unterschiedliche Syntax, und die Syntax der Aufgabenparameter variiert je nach Aufgabentyp.

Das folgende Beispiel zeigt die partielle JSON-Syntax zum Konfigurieren von Auftragsparametern mithilfe dynamischer Wertverweise:

{
  "parameters": [
    {
      "name": "my_job_id",
      "default": "{{job.id}}"
    },
    {
      "name": "run_date",
      "default": "{{job.start_time.iso_date}}"
    }
  ]
}

Das folgende Beispiel zeigt die partielle JSON-Syntax zum Konfigurieren von Notebook-Aufgaben mithilfe dynamischer Wertverweise:

{
  "notebook_task": {
    "base_parameters": {
      "workspace_id": "workspace_{{workspace.id}}",
      "file_arrival_location": "{{job.trigger.file_arrival.location}}"
    }
  }
}

Überprüfen von Parametern für eine Auftragsausführung

Nach Abschluss einer Aufgabe können Sie aufgelöste Werte für Parameter unter Parameter auf der Seite „Ausführungsdetails“ anzeigen. Siehe Anzeigen von Details zur Auftragsausführung.

Unterstützte Wertverweise

Die folgenden dynamischen Wertverweise werden unterstützt:

Verweis Beschreibung
{{job.id}} Der eindeutige Bezeichner, der einem Auftrag zugewiesen ist.
{{job.name}} Der Name des Auftrags zum Zeitpunkt der Ausführung des Auftrags.
{{job.run_id}} Der eindeutige Bezeichner, der der Auftragsausführung zugewiesen ist.
{{job.repair_count}} Die Anzahl der Reparaturversuche für die aktuelle Auftragsausführung.
{{job.start_time.<argument>}} Ein Wert basierend auf der Zeit (in UTC-Zeitzone), zu der die Auftragsausführung begonnen hat. Der Rückgabewert basiert auf der argument-Option. Siehe Optionen für Datums- und Uhrzeitwerte.
{{job.parameters.<name>}} Der Wert des Parameters auf Auftragsebene mit dem Schlüssel <name>.
{{job.trigger.type}} Der Triggertyp des Auftragsausführung. Die möglichen Werte sind periodic, one_time , run_job_task, file_arrival, continuous, und table.
{{job.trigger.file_arrival.location}} Wenn ein Dateiankunftstrigger für diesen Auftrag konfiguriert ist, der Wert des Speicherorts.
{{job.trigger.time.<argument>}} Ein Wert basierend auf dem Zeitpunkt (in UTC-Zeitzone), zu dem der Auftrag ausgelöst wurde, abgerundet auf die nächstgelegene Minute für Aufträge mit einem Cron-Zeitplan. Der Rückgabewert basiert auf der argument-Option. Siehe Optionen für Datums- und Uhrzeitwerte.
{{task.name}} Der Name der aktuellen Aufgabe.
{{task.run_id}} Der eindeutige Bezeichner der aktuellen Aufgabenausführung.
{{task.execution_count}} Die Häufigkeit, mit der die aktuelle Aufgabe ausgeführt wurde (einschließlich Wiederholungen und Reparaturen).
{{task.notebook_path}} Der Notizbuchpfad der aktuellen Notizbuchaufgabe.
{{tasks.<task_name>.run_id}} Der eindeutige Bezeichner, der der Aufgabenausführung für <task_name> zugewiesen wurde.
{{tasks.<task_name>.result_state}} Der Ergebniszustand einer Ausführung <task_name>. Die möglichen Werte sind success, failed, excluded, canceled, evicted, timedout, upstream_canceled, upstream_evicted und upstream_failed.
{{tasks.<task_name>.error_code}} Der Fehlercode für die Aufgabe <task_name>, wenn beim Ausführen der Aufgabe ein Fehler aufgetreten ist. Beispiele für mögliche Werte sind RunExecutionError, ResourceNotFound und UnauthorizedError. Bei erfolgreichen Vorgängen wird dies als leere Zeichenfolge ausgewertet.
{{tasks.<task_name>.execution_count}} Die Häufigkeit, mit der die Aufgabe <task_name> ausgeführt wurde (einschließlich Wiederholungen und Reparaturen).
{{tasks.<task_name>.notebook_path}} Der Pfad zum Notizbuch für die Notizbuchaufgabe <task_name>.
{{tasks.<task_name>.values.<value_name>}} Der Aufgabenwert mit dem Schlüssel <value_name>, der von Aufgabe <task_name> festgelegt wurde.
{{workspace.id}} Der eindeutige Bezeichner, der dem Arbeitsbereich zugewiesen ist.
{{workspace.url}} Die URL des Arbeitsbereichs.

Sie können diese Verweise mit jeder Aufgabe festlegen. Weitere Informationen finden Sie unter Konfigurieren von Aufgabenparametern.

Sie können auch Parameter zwischen Aufgaben in einem Auftrag mit Vorgangswerten übergeben. Siehe Verwenden von Aufgabenwerten zur Weitergabe von Informationen zwischen Aufgaben..

Optionen für Datums- und Uhrzeitwerte

Verwenden Sie die folgenden Argumente, um den Rückgabewert aus zeitbasierten Parametervariablen anzugeben. Alle Rückgabewerte basieren auf einem Zeitstempel in der UTC-Zeitzone.

Argument Beschreibung
iso_weekday Gibt eine Ziffer von 1 bis 7 zurück, die den Wochentag des Zeitstempels darstellt.
is_weekday Gibt true zurück, wenn der Zeitstempel an einem Wochentag liegt.
iso_date Gibt das Datum im ISO-Format zurück.
iso_datetime Gibt das Datum und die Uhrzeit im ISO-Format zurück.
year Gibt den Jahresteil des Zeitstempels zurück.
month Gibt den Monatsteil des Zeitstempels zurück.
day Gibt den Tagesteil des Zeitstempels zurück.
hour Gibt den Stundenteil des Zeitstempels zurück.
minute Gibt den Minutenteil des Zeitstempels zurück.
second Gibt den Sekundenteil des Zeitstempels zurück.
timestamp_ms Gibt den Zeitstempel in Millisekunden zurück.

Veraltete dynamische Wertverweise

Die folgenden dynamischen Wertverweise sind veraltet. Der empfohlene Ersatzverweis ist in der Beschreibung jeder Variablen enthalten.

Variable Beschreibung
{{job_id}} Der eindeutige Bezeichner, der einem Auftrag zugewiesen ist. Verwenden Sie stattdessen job.id.
{{run_id}} Der eindeutige Bezeichner, der einer Aufgabenausführung zugewiesen wurde. Verwenden Sie stattdessen task.run_id.
{{start_date}} Das Datum, an dem eine Aufgabenausführung gestartet wird. Das Format lautet in der UTC-Zeitzone „JJJJ-MM-TT“. Verwenden Sie stattdessen job.start_time.<argument>.
{{start_time}} Der Zeitstempel für den Ausführungsbeginn, nachdem der Cluster erstellt wurde und bereit ist. Als Format wird die UNIX-Zeit in der UTC-Zeitzone verwendet, wie zurückgegeben durch System.currentTimeMillis(). Verwenden Sie stattdessen job.start_time.<format>.
{{task_retry_count}} Die Anzahl der durchgeführten Wiederholungsversuche zum Ausführen einer Aufgabe, wenn der erste Versuch fehlschlägt. Der Wert lautet beim ersten Versuch 0 und erhöht sich bei jedem weiteren Versuch. Verwenden Sie stattdessen task.execution_count.
{{parent_run_id}} Der eindeutige Bezeichner, der der Ausführung eines Auftrags mit mehreren Aufgaben zugeordnet ist. Verwenden Sie stattdessen job.run_id.
{{task_key}} Der eindeutige Name, der einer Aufgabe zugewiesen wurde, die Teil eines Auftrags mit mehreren Aufgaben ist. Verwenden Sie stattdessen task.name.