Lookup-Aktivität in Azure Data Factory und Azure Synapse Analytics

Gilt für: Azure Data Factory Azure Synapse Analytics

Die Lookup-Aktivität kann ein Dataset aus allen Datenquellen abrufen, die von Data Factory- und Synapse-Pipelines unterstützt werden. Sie können damit dynamisch ermitteln, welche Objekte in einer nachfolgenden Aktivität verarbeitet werden sollen, statt den Objektnamen hart zu codieren. Beispiele für Objekte sind Dateien und Tabellen.

Die Lookup-Aktivität liest die Daten und gibt den Inhalt einer Konfigurationsdatei oder Tabelle zurück. Zudem gibt sie auch das Ergebnis einer ausgeführten Abfrage oder gespeicherten Prozedur zurück. Die Ausgabe kann ein Singleton-Wert oder ein Array von Attributen sein, das in einer nachfolgenden Kopier-, Transformations-oder Ablaufsteuerungsaktivität wie einer ForEach-Aktivität verwendet werden kann.

Erstellen Sie eine Lookup-Aktivität mit UI

Führen Sie die folgenden Schritte aus, um eine Lookup-Aktivität in einer Pipeline zu verwenden:

1. Suchen Sie im Bereich mit den Pipelineaktivitäten nach Spark, und ziehen Sie eine Lookup-Aktivität in den Pipelinebereich.

2. Wählen Sie in diesem Bereich die neue Lookup-Aktivität aus (wenn sie noch nicht ausgewählt wurde), und wählen Sie anschließend die Registerkarte Einstellungen aus, um die Details zu bearbeiten.

   

3. Wählen Sie ein vorhandenes Quelldataset aus, oder wählen Sie die Schaltfläche Neu aus, um ein neues zu erstellen.

4. Die Optionen zum Identifizieren von Zeilen, die aus dem Quelldataset eingeschlossen werden sollen, variieren je nach Datasettyp. Das obige Beispiel zeigt die Konfigurationsoptionen für ein durch Trennzeichen getrenntes Textdataset. Nachfolgend finden Sie Beispiele für Konfigurationsoptionen für ein Azure SQL Tabellen-Dataset und ein OData-Dataset.

   

   

Unterstützte Funktionen

Beachten Sie Folgendes:

• Die Lookup-Aktivität kann bis zu 5000 Zeilen zurückgeben. Wenn das Resultset mehr Datensätze enthält, werden die ersten 5000 Zeilen zurückgegeben.
• Die Ausgabe der Lookup-Aktivität unterstützt eine Größe von bis zu 4 MB. Wenn die Größe diesen Grenzwert überschreitet, schlägt die Aktivität fehl.
• Die Höchstdauer für die Lookup-Aktivität vor dem Timeout beträgt 24 Stunden.

Die folgenden Datenquellen werden für die Lookup-Aktivität unterstützt.

Syntax

{
    "name":"LookupActivity",
    "type":"Lookup",
    "typeProperties":{
        "source":{
            "type":"<source type>"
        },
        "dataset":{
            "referenceName":"<source dataset name>",
            "type":"DatasetReference"
        },
        "firstRowOnly":<true or false>
    }
}

Typeigenschaften

Verwenden des Ergebnisses der Lookup-Aktivität

Das Lookupergebnis wird im Abschnitt output des Ergebnisses der Aktivitätsausführung zurückgegeben.

• Wenn firstRowOnly auf true (Standardwert) gesetzt ist, wird das Ausgabeformat wie im folgenden Code gezeigt. Das Nachschlageergebnis befindet sich unter dem festen Schlüssel firstRow. Um das Ergebnis in nachfolgenden Aktivitäten zu nutzen, verwenden Sie das Muster @{activity('LookupActivity').output.firstRow.table}.

  {
      "firstRow":
      {
          "Id": "1",
          "schema":"dbo",
          "table":"Table1"
      }
  }
  

• Wenn firstRowOnly auf false festgelegt ist, wird das Ausgabeformat wie im folgenden Code gezeigt. Ein Feld count gibt an, wie viele Datensätze zurückgegeben werden. Detaillierte Werte werden unter einem festen value-Array angezeigt. In diesem Fall folgt auf die Lookup-Aktivität eine ForEach-Aktivität. Um das Array value an das Feld items der ForEach-Aktivität zu übergeben, verwenden Sie das Muster @activity('MyLookupActivity').output.value. Für den Zugriff auf Elemente in Array value verwenden Sie die folgende Syntax: @{activity('lookupActivity').output.value[zero based index].propertyname}. Zum Beispiel @{activity('lookupActivity').output.value[0].schema}.

  {
      "count": "2",
      "value": [
          {
              "Id": "1",
              "schema":"dbo",
              "table":"Table1"
          },
          {
              "Id": "2",
              "schema":"dbo",
              "table":"Table2"
          }
      ]
  } 
  

Beispiel

In diesem Beispiel enthält die Pipeline zwei Aktivitäten: Lookup und Kopieren. Die Kopieaktivität kopiert Daten aus einer SQL-Tabelle in Ihrer Azure SQL-Datenbank Instanz in Azure Blob-Speicher. Der Name der SQL-Tabelle wird in einer JSON-Datei in Blob Storage gespeichert. Die Lookup-Aktivität sucht den Tabellennamen während der Laufzeit. Durch diesen Ansatz wird die JSON-Datei dynamisch geändert. Pipelines oder Datensätze müssen nicht erneut bereitgestellt werden.

Dieses Beispiel zeigt nur das Lookup für die erste Zeile. Um alle Zeilen nachzuschlagen und die Ergebnisse mit der ForEach-Aktivität zu verketten, sehen Sie sich die Beispiele in Massenkopieren mehrerer Tabellen an.

Pipeline

• Die Nachschlageaktivität ist so konfiguriert, dass LookupDataset verwendet wird, der sich auf einen Speicherort im Azure Blob-Speicher bezieht. Der Name der SQL-Tabelle wird von der Lookup-Aktivität aus einer JSON-Datei an diesem Speicherort gelesen.
• Die Kopieraktivität verwendet die Ausgabe der Lookup-Aktivität, also den Namen der SQL-Tabelle. Die tableName-Eigenschaft in SourceDataset ist für die Verwendung der Ausgabe der Lookup-Aktivität konfiguriert. Kopiervorgang kopiert Daten aus der SQL-Tabelle in einen Speicherort im Azure Blob-Speicher. Der Speicherort wird durch die SinkDataset-Eigenschaft festgelegt.

{
    "name": "LookupPipelineDemo",
    "properties": {
        "activities": [
            {
                "name": "LookupActivity",
                "type": "Lookup",
                "dependsOn": [],
                "policy": {
                    "timeout": "7.00:00:00",
                    "retry": 0,
                    "retryIntervalInSeconds": 30,
                    "secureOutput": false,
                    "secureInput": false
                },
                "userProperties": [],
                "typeProperties": {
                    "source": {
                        "type": "JsonSource",
                        "storeSettings": {
                            "type": "AzureBlobStorageReadSettings",
                            "recursive": true
                        },
                        "formatSettings": {
                            "type": "JsonReadSettings"
                        }
                    },
                    "dataset": {
                        "referenceName": "LookupDataset",
                        "type": "DatasetReference"
                    },
                    "firstRowOnly": true
                }
            },
            {
                "name": "CopyActivity",
                "type": "Copy",
                "dependsOn": [
                    {
                        "activity": "LookupActivity",
                        "dependencyConditions": [
                            "Succeeded"
                        ]
                    }
                ],
                "policy": {
                    "timeout": "7.00:00:00",
                    "retry": 0,
                    "retryIntervalInSeconds": 30,
                    "secureOutput": false,
                    "secureInput": false
                },
                "userProperties": [],
                "typeProperties": {
                    "source": {
                        "type": "AzureSqlSource",
                        "sqlReaderQuery": {
                            "value": "select * from [@{activity('LookupActivity').output.firstRow.schema}].[@{activity('LookupActivity').output.firstRow.table}]",
                            "type": "Expression"
                        },
                        "queryTimeout": "02:00:00",
                        "partitionOption": "None"
                    },
                    "sink": {
                        "type": "DelimitedTextSink",
                        "storeSettings": {
                            "type": "AzureBlobStorageWriteSettings"
                        },
                        "formatSettings": {
                            "type": "DelimitedTextWriteSettings",
                            "quoteAllText": true,
                            "fileExtension": ".txt"
                        }
                    },
                    "enableStaging": false,
                    "translator": {
                        "type": "TabularTranslator",
                        "typeConversion": true,
                        "typeConversionSettings": {
                            "allowDataTruncation": true,
                            "treatBooleanAsNumber": false
                        }
                    }
                },
                "inputs": [
                    {
                        "referenceName": "SourceDataset",
                        "type": "DatasetReference",
                        "parameters": {
                            "schemaName": {
                                "value": "@activity('LookupActivity').output.firstRow.schema",
                                "type": "Expression"
                            },
                            "tableName": {
                                "value": "@activity('LookupActivity').output.firstRow.table",
                                "type": "Expression"
                            }
                        }
                    }
                ],
                "outputs": [
                    {
                        "referenceName": "SinkDataset",
                        "type": "DatasetReference",
                        "parameters": {
                            "schema": {
                                "value": "@activity('LookupActivity').output.firstRow.schema",
                                "type": "Expression"
                            },
                            "table": {
                                "value": "@activity('LookupActivity').output.firstRow.table",
                                "type": "Expression"
                            }
                        }
                    }
                ]
            }
        ],
        "annotations": [],
        "lastPublishTime": "2020-08-17T10:48:25Z"
    }
}

Suchdataset

Das Dataset lookup ist die Datei sourcetable.json im durch den Typ AzureBlobStorageLinkedService angegebenen Nachschlageordner in Azure Storage.

{
    "name": "LookupDataset",
    "properties": {
        "linkedServiceName": {
            "referenceName": "AzureBlobStorageLinkedService",
            "type": "LinkedServiceReference"
        },
        "annotations": [],
        "type": "Json",
        "typeProperties": {
            "location": {
                "type": "AzureBlobStorageLocation",
                "fileName": "sourcetable.json",
                "container": "lookup"
            }
        }
    }
}

Quelldatensatz für die Kopieraktivität

Das source-Dataset verwendet die Ausgabe der Lookup-Aktivität, also den Namen der SQL-Tabelle. Die Kopieraktivität kopiert Daten aus dieser SQL-Tabelle an einen Speicherort im Azure Blob-Speicher. Der Speicherort wird durch das sink-Dataset festgelegt.

{
    "name": "SourceDataset",
    "properties": {
        "linkedServiceName": {
            "referenceName": "AzureSqlDatabase",
            "type": "LinkedServiceReference"
        },
        "parameters": {
            "schemaName": {
                "type": "string"
            },
            "tableName": {
                "type": "string"
            }
        },
        "annotations": [],
        "type": "AzureSqlTable",
        "schema": [],
        "typeProperties": {
            "schema": {
                "value": "@dataset().schemaName",
                "type": "Expression"
            },
            "table": {
                "value": "@dataset().tableName",
                "type": "Expression"
            }
        }
    }
}

Sink-Dataset für die Kopieraktivität

Die Kopieraktivität kopiert Daten aus der SQL-Tabelle in die Datei filebylookup.csv im Ordner csv in Azure Storage. Die Datei wird durch die Eigenschaft AzureBlobStorageLinkedServicefestgelegt.

{
    "name": "SinkDataset",
    "properties": {
        "linkedServiceName": {
            "referenceName": "AzureBlobStorageLinkedService",
            "type": "LinkedServiceReference"
        },
        "parameters": {
            "schema": {
                "type": "string"
            },
            "table": {
                "type": "string"
            }
        },
        "annotations": [],
        "type": "DelimitedText",
        "typeProperties": {
            "location": {
                "type": "AzureBlobStorageLocation",
                "fileName": {
                    "value": "@{dataset().schema}_@{dataset().table}.csv",
                    "type": "Expression"
                },
                "container": "csv"
            },
            "columnDelimiter": ",",
            "escapeChar": "\\",
            "quoteChar": "\""
        },
        "schema": []
    }
}

sourcetable.json

Sie können die folgenden zwei Arten von Formaten für die Datei sourcetable.json verwenden.

Satz von Objekten

{
   "Id":"1",
   "schema":"dbo",
   "table":"Table1"
}
{
   "Id":"2",
   "schema":"dbo",
   "table":"Table2"
}

Array von Objekten

[ 
    {
        "Id": "1",
        "schema":"dbo",
        "table":"Table1"
    },
    {
        "Id": "2",
        "schema":"dbo",
        "table":"Table2"
    }
]

Einschränkungen und Problemumgehungen

Hier werden einige Einschränkungen der Lookup-Aktivität und empfohlene Problemumgehungen aufgeführt.

Zugehöriger Inhalt

Sehen Sie sich weitere Steuerungsflussaktivitäten an, die von Azure Data Factory- und Synapse-Pipelines unterstützt werden:

• Aktivität „Pipeline ausführen“
• ForEach-Aktivität
• GetMetadata-Aktivität
• Webaktivität