Jak používat parametry, výrazy a funkce ve službě Azure Data Factory

Článek
12/09/2023

PLATÍ PRO: Azure Data Factory Azure Synapse Analytics

Tip

Vyzkoušejte si službu Data Factory v Microsoft Fabric, řešení pro analýzy typu all-in-one pro podniky. Microsoft Fabric zahrnuje všechno od přesunu dat až po datové vědy, analýzy v reálném čase, business intelligence a vytváření sestav. Přečtěte si, jak začít používat novou zkušební verzi zdarma.

V tomto dokumentu se zaměříme především na výuku základních konceptů s různými příklady, abychom prozkoumali možnost vytvářet parametrizované datové kanály ve službě Azure Data Factory. Parametrizace a dynamické výrazy jsou tak výraznými doplňky ADF, protože můžou ušetřit obrovské množství času a umožňují mnohem flexibilnější řešení extrakce, transformace, načítání (ETL) nebo extrakce, načítání, transformace (ELT), které výrazně sníží náklady na údržbu řešení a urychlí implementaci nových funkcí do stávajících kanálů. Tyto zisky jsou způsobené tím, že parametrizace minimalizuje objem pevného kódování a zvyšuje počet opakovaně použitelných objektů a procesů v řešení.

Uživatelské rozhraní a parametry služby Azure Data Factory

Pokud s používáním parametrů služby Azure Data Factory v uživatelském rozhraní ADF začínáte, projděte si uživatelské rozhraní služby Data Factory, kde najdete odkazované služby s parametry a uživatelským rozhraním služby Data Factory, kde najdete vizuální vysvětlení v kanálu řízeném metadaty s parametry.

Koncepty parametrů a výrazů

Pomocí parametrů můžete předávat externí hodnoty do kanálů, datových sad, propojených služeb a toků dat. Jakmile se parametr předá do prostředku, nelze ho změnit. Když parametrizujete prostředky, můžete je pokaždé znovu použít s různými hodnotami. Parametry lze použít jednotlivě nebo jako součást výrazů. Hodnoty JSON v definici můžou být literály nebo výrazy, které se vyhodnocují za běhu.

Příklad:

"name": "value"

nebo

"name": "@pipeline().parameters.password"

Výrazy se můžou objevit kdekoli v řetězcové hodnotě JSON a vždy vést k jiné hodnotě JSON. Tady je heslo parametrem kanálu ve výrazu. Pokud je hodnota JSON výrazem, text výrazu se extrahuje odebráním znaku at(@). Pokud je potřeba řetězec literálu, který začíná znakem @, musí být uchvácen pomocí @@. Následující příklady ukazují, jak se výrazy vyhodnocují.

Hodnota JSON	Výsledek
"parameters"	Vrátí se znaky "parameters".
"parameters[1]"	Vrátí se znaky parameters[1].
"@@"	Vrátí se řetězec 1 znaku, který obsahuje znak @.
" @"	Vrátí se řetězec 2 znaků, který obsahuje znak @.

Výrazy se mohou objevit také uvnitř řetězců pomocí funkce označované jako interpolace řetězců, ve které jsou výrazy zabaleny @{ ... }. Příklad: "name" : "First Name: @{pipeline().parameters.firstName} Last Name: @{pipeline().parameters.lastName}"

Pomocí interpolace řetězců je výsledkem vždy řetězec. Řekněme, že jsem definoval myNumber jako 42 a myString jako foo:

Hodnota JSON	Výsledek
"@pipeline().parameters.myString"	Vrátí `foo` jako řetězec.
"@{pipeline().parameters.myString}"	Vrátí `foo` jako řetězec.
"@pipeline().parameters.myNumber"	Vrátí `42` jako číslo.
"@{pipeline().parameters.myNumber}"	Vrátí `42` jako řetězec.
"Odpověď je: @{pipeline().parameters.myNumber}"	Vrátí řetězec `Answer is: 42`.
"@concat('Answer is: ', string(pipeline().parameters.myNumber)"	Vrátí řetězec. `Answer is: 42`
"Odpověď je: @@{pipeline().parameters.myNumber}"	Vrátí řetězec `Answer is: @{pipeline().parameters.myNumber}`.

Příklady použití parametrů ve výrazech

Příklad komplexního výrazu

Následující příklad ukazuje složitý příklad, který odkazuje na hluboké dílčí pole výstupu aktivity. Pokud chcete odkazovat na parametr kanálu, který se vyhodnotí jako dílčí pole, použijte místo operátoru tečk(.) syntaxi [] (jako v případě dílčího pole1 a dílčího pole2).

@activity('*activityName*').output.*subfield1*.*subfield2*[pipeline().parameters.*subfield3*].*subfield4*

Editor dynamického obsahu

Editor dynamického obsahu po dokončení úprav automaticky uchytá znaky v obsahu. Například následující obsah v editoru obsahu je interpolace řetězců se dvěma funkcemi výrazů.

{ 
  "type": "@{if(equals(1, 2), 'Blob', 'Table' )}",
  "name": "@{toUpper('myData')}"
}

Editor dynamického obsahu převede nad obsah na výraz "{ \n \"type\": \"@{if(equals(1, 2), 'Blob', 'Table' )}\",\n \"name\": \"@{toUpper('myData')}\"\n}". Výsledkem tohoto výrazu je řetězec formátu JSON uvedený níže.

{
  "type": "Table",
  "name": "MYDATA"
}

Datová sada s parametry

V následujícím příkladu přebírá blobDataset parametr pojmenovanou cestu. Jeho hodnota se používá k nastavení hodnoty vlastnosti folderPath pomocí výrazu: dataset().path.

{
    "name": "BlobDataset",
    "properties": {
        "type": "AzureBlob",
        "typeProperties": {
            "folderPath": "@dataset().path"
        },
        "linkedServiceName": {
            "referenceName": "AzureStorageLinkedService",
            "type": "LinkedServiceReference"
        },
        "parameters": {
            "path": {
                "type": "String"
            }
        }
    }
}

Kanál s parametry

V následujícím příkladu kanál přebírá parametry inputPath a outputPath . Cesta pro parametrizovanou datovou sadu objektů blob je nastavena pomocí hodnot těchto parametrů. Syntaxe použitá tady je: pipeline().parameters.parametername.

{
    "name": "Adfv2QuickStartPipeline",
    "properties": {
        "activities": [
            {
                "name": "CopyFromBlobToBlob",
                "type": "Copy",
                "inputs": [
                    {
                        "referenceName": "BlobDataset",
                        "parameters": {
                            "path": "@pipeline().parameters.inputPath"
                        },
                        "type": "DatasetReference"
                    }
                ],
                "outputs": [
                    {
                        "referenceName": "BlobDataset",
                        "parameters": {
                            "path": "@pipeline().parameters.outputPath"
                        },
                        "type": "DatasetReference"
                    }
                ],
                "typeProperties": {
                    "source": {
                        "type": "BlobSource"
                    },
                    "sink": {
                        "type": "BlobSink"
                    }
                }
            }
        ],
        "parameters": {
            "inputPath": {
                "type": "String"
            },
            "outputPath": {
                "type": "String"
            }
        }
    }
}

Volání funkcí ve výrazech

Funkce můžete volat ve výrazech. Následující části obsahují informace o funkcích, které lze použít ve výrazu.

Funkce řetězců

Pro práci s řetězci můžete použít tyto řetězcové funkce a také některé funkce kolekce. Řetězcové funkce fungují jenom na řetězcích.

Řetězcová funkce	Task
Concat	Zkombinujte dva nebo více řetězců a vraťte sloučený řetězec.
Endswith	Zkontrolujte, jestli řetězec končí zadaným podřetězcem.
Identifikátor guid	Vygenerujte globálně jedinečný identifikátor (GUID) jako řetězec.
Indexof	Vrátí počáteční pozici podřetězdce.
Lastindexof	Vrátí počáteční pozici posledního výskytu podřetězdce.
replace	Nahraďte podřetězce zadaným řetězcem a vraťte aktualizovaný řetězec.
split	Vrátí pole, které obsahuje podřetězce oddělené čárkami, od většího řetězce založeného na zadaném znaku oddělovače v původním řetězci.
Startswith	Zkontrolujte, jestli řetězec začíná určitým podřetězcem.
Podřetězec	Vrátí znaky z řetězce počínaje zadanou pozicí.
Tolower	Vrátí řetězec ve formátu malými písmeny.
Toupper	Vrátí řetězec ve formátu velkými písmeny.
Trim	Odeberte počáteční a koncové prázdné znaky z řetězce a vraťte aktualizovaný řetězec.

Funkce kolekcí

Pokud chcete pracovat s kolekcemi, obecně polemi, řetězci a někdy slovníky, můžete tyto funkce kolekce používat.

Funkce Kolekce	Task
Obsahuje	Zkontrolujte, jestli kolekce obsahuje konkrétní položku.
empty	Zkontrolujte, jestli je kolekce prázdná.
První	Vrátí první položku z kolekce.
Průsečíku	Vrátí kolekci, která obsahuje pouze společné položky v zadaných kolekcích.
join	Vrátí řetězec, který obsahuje všechny položky z pole oddělené zadaným znakem.
Poslední	Vrátí poslední položku z kolekce.
length	Vrátí počet položek v řetězci nebo poli.
Přeskočit	Odeberte položky z přední části kolekce a vraťte všechny ostatní položky.
vzít	Vrátí položky z přední části kolekce.
Unie	Vrátí kolekci, která obsahuje všechny položky ze zadaných kolekcí.

Logické funkce

Tyto funkce jsou užitečné v podmínkách, lze je použít k vyhodnocení libovolného typu logiky.

Logická funkce porovnání	Task
and	Zkontrolujte, jestli jsou všechny výrazy pravdivé.
equals	Zkontrolujte, jestli jsou obě hodnoty ekvivalentní.
greater	Zkontrolujte, jestli je první hodnota větší než druhá hodnota.
greaterOrEquals	Zkontrolujte, jestli je první hodnota větší nebo rovna druhé hodnotě.
Pokud	Zkontrolujte, jestli je výraz pravdivý nebo nepravda. Na základě výsledku vrátí zadanou hodnotu.
less	Zkontrolujte, jestli je první hodnota menší než druhá hodnota.
lessOrEquals	Zkontrolujte, jestli je první hodnota menší nebo rovna druhé hodnotě.
not	Zkontrolujte, jestli je výraz nepravda.
nebo	Zkontrolujte, jestli je alespoň jeden výraz pravdivý.

Převodní funkce

Tyto funkce slouží k převodu mezi jednotlivými nativními typy v jazyce:

string
integer
float (číslo s plovoucí řádovou čárkou)
boolean
Pole
Slovníky

Převodní funkce	Task
Pole	Vrátí pole z jednoho zadaného vstupu. Více vstupů naleznete v tématu createArray.
base64	Vrátí verzi zakódovanou v base64 pro řetězec.
base64ToBinary	Vrátí binární verzi řetězce s kódováním base64.
base64ToString	Vrátí verzi řetězce pro řetězec kódovaný v base64.
Binární	Vrátí binární verzi pro vstupní hodnotu.
bool	Vrátí logickou verzi pro vstupní hodnotu.
Coalesce	Vrátí první hodnotu, která není null, z jednoho nebo více parametrů.
createArray	Vrátí pole z více vstupů.
identifikátor dataURI	Vrátí identifikátor URI dat pro vstupní hodnotu.
dataUriToBinary	Vrátí binární verzi identifikátoru URI dat.
dataUriToString	Vrátí verzi řetězce pro identifikátor URI dat.
decodeBase64	Vrátí verzi řetězce pro řetězec kódovaný v base64.
decodeDataUri	Vrátí binární verzi identifikátoru URI dat.
decodeUriComponent	Vrátí řetězec, který nahradí řídicí znaky dekódovanými verzemi.
encodeUriComponent	Vrátí řetězec, který nahradí nebezpečné znaky adresy URL řídicími znaky.
float	Vrátí číslo s plovoucí desetinou čárkou pro vstupní hodnotu.
int	Vrátí celočíselnou verzi řetězce.
Json	Vrátí hodnotu typu JSON (JavaScript Object Notation) nebo objekt pro řetězec nebo XML.
string	Vrátí verzi řetězce pro vstupní hodnotu.
uriComponent	Vrátí verzi zakódovanou identifikátorem URI pro vstupní hodnotu nahrazením nebezpečných znaků adresy URL řídicími znaky.
uriComponentToBinary	Vrátí binární verzi řetězce kódovaného identifikátorem URI.
uriComponentToString	Vrátí verzi řetězce pro řetězec kódovaný identifikátorem URI.
xml	Vrátí verzi XML pro řetězec.
Xpath	Zkontrolujte kód XML pro uzly nebo hodnoty, které odpovídají výrazu XPath (XML Path Language) a vrátí odpovídající uzly nebo hodnoty.

Matematické funkce

Tyto funkce lze použít pro některý z typů čísel: celá čísla a float.

Matematické funkce	Task
add	Vrátí výsledek sčítání dvou čísel.
div	Vrátí výsledek dělení dvou čísel.
Max	Vrátí nejvyšší hodnotu ze sady čísel nebo pole.
Min	Vrátí nejnižší hodnotu ze sady čísel nebo pole.
Mod	Vrátí zbytek od dělení dvou čísel.
mul	Vrátí součin od vynásobení dvou čísel.
rand	Vrátí náhodné celé číslo ze zadaného rozsahu.
range	Vrátí celočíselnou matici, která začíná zadaným celočíselnou hodnotou.
Dílčí	Vrátí výsledek od odečtení druhého čísla od prvního čísla.

Datové funkce

Funkce data nebo času	Task
Adddays	Přidejte do časového razítka počet dní.
addHours	Přidejte do časového razítka počet hodin.
Addminutes	Přidejte do časového razítka několik minut.
addSeconds	Přidejte do časového razítka několik sekund.
addToTime	Přidejte do časového razítka řadu časových jednotek. Viz také getFutureTime.
convertFromUtc	Převeďte časové razítko z standardu UTC (Universal Time Coordinated) na cílové časové pásmo.
convertTimeZone	Převeďte časové razítko ze zdrojového časového pásma na cílové časové pásmo.
convertToUtc	Převeďte časové razítko ze zdrojového časového pásma na standard UTC (Universal Time Coordinated).
denOfMonth	Vrátí den součásti měsíce z časového razítka.
Dayofweek	Vrátí součást dne v týdnu z časového razítka.
Dayofyear	Vrátí den v roce z časového razítka.
formatDateTime	Vrátí časové razítko jako řetězec ve volitelném formátu.
getFutureTime	Vrátí aktuální časové razítko a zadané časové jednotky. Viz také addToTime.
getPastTime	Vrátí aktuální časové razítko minus zadané časové jednotky. Viz také odečítáníFromTime.
startOfDay	Vrátí začátek dne pro časové razítko.
startOfHour	Vrátí začátek hodiny pro časové razítko.
startOfMonth	Vrátí začátek měsíce pro časové razítko.
odečístFromTime	Odečte počet časových jednotek od časového razítka. Viz také getPastTime.
Klíšťata	`ticks` Vrátí hodnotu vlastnosti pro zadané časové razítko.
UtcNow	Vrátí aktuální časové razítko jako řetězec.

Podrobné příklady pro praxi

Podrobný kanál kopírování služby Azure Data Factory s parametry

Tento kurz předávání parametrů kanálu kopírování služby Azure Data Factory vás provede předáním parametrů mezi kanálem a aktivitou i mezi aktivitami.

Podrobný kanál mapování toku dat s parametry

Postupujte podle mapování toku dat s parametry , které poskytují komplexní příklad použití parametrů v toku dat.

Podrobný kanál řízený metadaty s parametry

Pokud chcete získat další informace o tom, jak pomocí parametrů navrhovat kanály řízené metadaty, postupujte podle parametrů . Toto je oblíbený případ použití parametrů.

Seznam systémových proměnných, které můžete použít ve výrazech, najdete v tématu Systémové proměnné.