Delen via

Gegevens transformeren met behulp van de scriptactiviteit in Azure Data Factory of Synapse Analytics

  • Artikel

VAN TOEPASSING OP: Azure Data Factory Azure Synapse Analytics

Tip

Probeer Data Factory uit in Microsoft Fabric, een alles-in-één analyseoplossing voor ondernemingen. Microsoft Fabric omvat alles, van gegevensverplaatsing tot gegevenswetenschap, realtime analyses, business intelligence en rapportage. Meer informatie over het gratis starten van een nieuwe proefversie .

U gebruikt activiteiten voor gegevenstransformatie in een Data Factory- of Synapse-pijplijn om onbewerkte gegevens te transformeren en te verwerken in voorspellingen en inzichten. De scriptactiviteit is een van de transformatieactiviteiten die door pijplijnen worden ondersteund. Dit artikel bouwt voort op het artikel over transformatiegegevens, waarin een algemeen overzicht wordt weergegeven van gegevenstransformatie en de ondersteunde transformatieactiviteiten.

Met behulp van de scriptactiviteit kunt u algemene bewerkingen uitvoeren met DML (Data Manipulation Language) en Data Definition Language (DDL). Met DML-instructies zoals INSERT, UPDATE, DELETE en SELECT kunnen gebruikers gegevens in de database invoegen, wijzigen, verwijderen en ophalen. Met DDL-instructies zoals CREATE, ALTER en DROP kan een databasebeheerder databaseobjecten, zoals tabellen, indexen en gebruikers, maken, wijzigen en verwijderen.

U kunt de scriptactiviteit gebruiken om een SQL-script aan te roepen in een van de volgende gegevensarchieven in uw onderneming of op een virtuele Azure-machine (VM):

  • Azure SQL Database
  • Azure Synapse Analytics
  • SQL Server Database. Als u SQL Server gebruikt, installeert u zelf-hostende Integration Runtime op dezelfde computer die als host fungeert voor de database of op een afzonderlijke computer die toegang heeft tot de database. Zelf-hostende integratieruntime is een onderdeel dat gegevensbronnen on-premises/on Azure VM verbindt met cloudservices op een veilige en beheerde manier. Zie het artikel over zelf-hostende Integration Runtime voor meer informatie.
  • Oracle
  • Snowflake

Het script kan één SQL-instructie of meerdere SQL-instructies bevatten die opeenvolgend worden uitgevoerd. U kunt de scripttaak voor de volgende doeleinden gebruiken:

  • Een tabel afkappen ter voorbereiding op het invoegen van gegevens.
  • Databaseobjecten zoals tabellen en weergaven maken, wijzigen en verwijderen.
  • Maak feiten- en dimensietabellen opnieuw voordat er gegevens in worden geladen.
  • Opgeslagen procedures uitvoeren. Als de SQL-instructie een opgeslagen procedure aanroept die resultaten van een tijdelijke tabel retourneert, gebruikt u de optie WITH RESULT SETS om metagegevens voor de resultatenset te definiëren.
  • Sla de rijenset op die wordt geretourneerd vanuit een query als activiteitsuitvoer voor downstreamverbruik.

Syntaxisdetails

Dit is de JSON-indeling voor het definiëren van een scriptactiviteit:

{ 
   "name": "<activity name>", 
   "type": "Script", 
   "linkedServiceName": { 
      "referenceName": "<name>", 
      "type": "LinkedServiceReference" 
    }, 
   "typeProperties": { 
      "scripts" : [ 
         { 
            "text": "<Script Block>", 
            "type": "<Query> or <NonQuery>", 
            "parameters":[ 
               { 
                  "name": "<name>", 
                  "value": "<value>", 
                  "type": "<type>", 
                  "direction": "<Input> or <Output> or <InputOutput>", 
                  "size": 256 
               }, 
               ... 
            ] 
         }, 
         ... 
      ],     
         ... 
         ] 
      }, 
      "scriptBlockExecutionTimeout": "<time>",  
      "logSettings": { 
         "logDestination": "<ActivityOutput> or <ExternalStore>", 
         "logLocationSettings":{ 
            "linkedServiceName":{ 
               "referenceName": "<name>", 
               "type": "<LinkedServiceReference>" 
            }, 
            "path": "<folder path>" 
         } 
      } 
    } 
}

In de volgende tabel worden deze JSON-eigenschappen beschreven:

Eigenschapsnaam Beschrijving Vereist
naam De naam van de activiteit. Ja
type Het type activiteit, ingesteld op 'Script'. Ja
typeProperties Geef eigenschappen op om de scriptactiviteit te configureren. Ja
linkedServiceName De doeldatabase waarop het script wordt uitgevoerd. Dit moet een verwijzing naar een gekoppelde service zijn. Ja
scripts Een matrix met objecten die het script vertegenwoordigen. Nee
scripts.text De tekst zonder opmaak van een blok query's. Nee
scripts.type Het type van het blok query's. Dit kan query's of niet-query's zijn. Standaard: Query. Nee
scripts.parameter De matrix van parameters van het script. Nee
scripts.parameter.name De naam van de parameter. Nee
scripts.parameter.value De waarde van de parameter. Nee
scripts.parameter.type Het gegevenstype van de parameter. Het type is een logisch type en volgt de typetoewijzing van elke connector. Nee
scripts.parameter.direction De richting van de parameter. Dit kan Input, Output, InputOutput zijn. De waarde wordt genegeerd als de richting Uitvoer is. Type ReturnValue wordt niet ondersteund. Stel de retourwaarde van SP in op een uitvoerparameter om deze op te halen. Nee
scripts.parameter.size De maximale grootte van de parameter. Alleen van toepassing op de richtingparameter Output/InputOutput van het type tekenreeks/byte[]. Nee
scriptBlockExecutionTimeout De wachttijd voor de uitvoering van het scriptblok voordat er een time-out optreedt. Nee
logSettings De instellingen voor het opslaan van de uitvoerlogboeken. Als dit niet is opgegeven, wordt het scriptlogboek uitgeschakeld. Nee
logSettings.logDestination Het doel van logboekuitvoer. Dit kan ActivityOutput of ExternalStore zijn. Standaard: ActivityOutput. Nee
logSettings.logLocationSettings De instellingen van de doellocatie als logDestination ExternalStore is. Nee
logSettings.logLocationSettings.linkedServiceName De gekoppelde service van de doellocatie. Alleen blobopslag wordt ondersteund. Nee
logSettings.logLocationSettings.path Het mappad waaronder logboeken moeten worden opgeslagen. Nee

Activiteitsuitvoer

Voorbeelduitvoer:

{ 
    "resultSetCount": 2, 
    "resultSets": [ 
        { 
            "rowCount": 10, 
            "rows":[ 
                { 
                    "<columnName1>": "<value1>", 
                    "<columnName2>": "<value2>", 
                    ... 
                } 
            ] 
        }, 
        ... 
    ], 
    "recordsAffected": 123, 
    "outputParameters":{ 
        "<parameterName1>": "<value1>", 
        "<parameterName2>": "<value2>" 
    }, 
    "outputLogs": "<logs>", 
    "outputLogsLocation": "<folder path>", 
    "outputTruncated": true, 
    ... 
}
Eigenschapsnaam Beschrijving Voorwaarde
resultSetCount Het aantal resultatensets dat door het script wordt geretourneerd. Altijd
resultSets De matrix die alle resultatensets bevat. Altijd
resultSets.rowCount Totaalrijen in de resultatenset. Altijd
resultSets.rows De matrix met rijen in de resultatenset. Altijd
betrokken records Het aantal rijen van betrokken rijen door het script. Als scriptType NietQuery is
outputParameters De uitvoerparameters van het script. Als het parametertype Output of InputOutput is.
outputLogs De logboeken die zijn geschreven door het script, bijvoorbeeld een afdrukinstructie. Als de connector logboekinstructie ondersteunt en enableScriptLogs waar is en logLocationSettings niet is opgegeven.
outputLogsPath Het volledige pad van het logboekbestand. Als enableScriptLogs waar is en logLocationSettings is opgegeven.
outputTruncated Indicator van of de uitvoer de limieten overschrijdt en wordt afgekapt. Als de uitvoer de limieten overschrijdt.

Notitie

  • De uitvoer wordt verzameld telkens wanneer een scriptblok wordt uitgevoerd. De uiteindelijke uitvoer is het samengevoegde resultaat van alle uitvoer van scriptblokken. De uitvoerparameter met dezelfde naam in een ander scriptblok wordt overschreven.
  • Omdat de uitvoer een beperking voor grootte/rijen heeft, wordt de uitvoer afgekapt in de volgende volgorde: logboeken -> parameters -> rijen. Opmerking: dit geldt voor één scriptblok, wat betekent dat de uitvoerrijen van het volgende scriptblok geen eerdere logboeken verwijderen.
  • Eventuele fouten die worden veroorzaakt door logboeken mislukken de activiteit niet.
  • Raadpleeg de documentatie over het resultaat van de lookup-activiteit voor het verbruik van resultatensets van activiteit in de down stream-activiteit.
  • Gebruik outputLogs wanneer u print-instructies gebruikt voor logboekregistratie. Als de query resultSets retourneert, is deze beschikbaar in de uitvoer van de activiteit en is deze beperkt tot de limiet van 5000 rijen/4 MB.

De scriptactiviteit configureren met behulp van de gebruikersinterface

Inlinescript

Schermopname van de gebruikersinterface voor het configureren van een inlinescript.

Inlinescripts kunnen goed worden geïntegreerd met pijplijn-CI/CD omdat het script wordt opgeslagen als onderdeel van de metagegevens van de pijplijn.

Logboekregistratie

Schermopname van de gebruikersinterface voor de logboekinstellingen voor een script.

Opties voor logboekregistratie:

  • Uitschakelen : er wordt geen uitvoer van de uitvoering vastgelegd.
  • Activiteitsuitvoer : de uitvoer van de scriptuitvoering wordt toegevoegd aan de uitvoer van de activiteit. Downstreamactiviteiten kunnen deze vervolgens gebruiken. De uitvoergrootte is beperkt tot 4 MB.
  • Externe opslag : behoudt uitvoer naar opslag. Gebruik deze optie als de uitvoer groter is dan 2 MB of als u de uitvoer expliciet wilt behouden in uw opslagaccount.

Notitie

Facturering : de scriptactiviteit wordt gefactureerd als pijplijnactiviteiten.

Gerelateerde inhoud

Zie de volgende artikelen waarin wordt uitgelegd hoe u gegevens op andere manieren kunt transformeren: