Attività Lookup in Azure Data FactoryLookup activity in Azure Data Factory

SI APPLICA A: Azure Data Factory Azure Synapse Analytics

L'attività Lookup consente di recuperare un set di dati da qualsiasi origine dati supportata da Azure Data Factory.Lookup activity can retrieve a dataset from any of the Azure Data Factory-supported data sources. è possibile usarlo per determinare in modo dinamico gli oggetti su cui operare in un'attività successiva, anziché codificare in modo rigido il nome dell'oggetto.you can use it to dynamically determine which objects to operate on in a subsequent activity, instead of hard coding the object name. Alcuni esempi di oggetti sono file e tabelle.Some object examples are files and tables.

L'attività Lookup legge e restituisce il contenuto di un file di configurazione o una tabella.Lookup activity reads and returns the content of a configuration file or table. Restituisce anche il risultato dell'esecuzione di una query o di una stored procedure.It also returns the result of executing a query or stored procedure. L'output può essere un valore singleton o una matrice di attributi, che può essere utilizzato in un'attività di copia, trasformazione o flusso di controllo successiva come l'attività ForEach.The output can be a singleton value or an array of attributes, which can be consumed in a subsequent copy, transformation, or control flow activities like ForEach activity.

Funzionalità supportateSupported capabilities

Tenere presente quanto segue:Note the following:

  • L'attività Lookup può restituire fino a 5000 righe; Se il set di risultati contiene più record, verranno restituite le prime 5000 righe.The Lookup activity can return up to 5000 rows; if the result set contains more records, the first 5000 rows will be returned.
  • L'output dell'attività di ricerca supporta fino a 4 MB di dimensioni. l'attività avrà esito negativo se le dimensioni superano il limite.The Lookup activity output supports up to 4 MB in size, activity will fail if the size exceeds the limit.
  • La durata più lunga per l'attività di ricerca prima del timeout è di 24 ore.The longest duration for Lookup activity before timeout is 24 hours.
  • Quando si utilizza query o stored procedure per la ricerca dei dati, assicurarsi di restituire uno e un set di risultati esatto.When you use query or stored procedure to lookup data, make sure to return one and exact one result set. In caso contrario, l'attività di ricerca non riesce.Otherwise, Lookup activity fails.

Per l'attività Lookup attualmente sono supportate le origini dati seguenti.The following data sources are supported for Lookup activity.

Category Data store
Azure Azure Blob storage
  Azure Cosmos DB (SQL API)
  Azure Data Explorer
  Azure Data Lake Storage Gen1
  Azure Data Lake Storage Gen2
  Azure Database for MariaDB
  Azure Database for MySQL
  Azure Database for PostgreSQL
  Azure Databricks Delta Lake
  Azure Files
  Azure SQL Database
  Azure SQL Managed Instance
  Azure Synapse Analytics
  Azure Table storage
Database Amazon Redshift
  DB2
  Drill
  Google BigQuery
  Greenplum
  HBase
  Hive
  Apache Impala
  Informix
  MariaDB
  Microsoft Access
  MySQL
  Netezza
  Oracle
  Phoenix
  PostgreSQL
  Presto
  SAP Business Warehouse Open Hub
  SAP Business Warehouse via MDX
  SAP HANA
  SAP Table
  Snowflake
  Spark
  SQL Server
  Sybase
  Teradata
  Vertica
NoSQL Cassandra
  Couchbase (Preview)
File Amazon S3
  File System
  FTP
  Google Cloud Storage
  HDFS
  SFTP
Generic protocol Generic HTTP
  Generic OData
  Generic ODBC
Services and apps Amazon Marketplace Web Service
  Common Data Service for Apps
  Concur (Preview)
  Dynamics 365
  Dynamics AX
  Dynamics CRM
  Google AdWords
  HubSpot
  Jira
  Magento (Preview)
  Marketo (Preview)
  Oracle Eloqua (Preview)
  Oracle Responsys (Preview)
  Oracle Service Cloud (Preview)
  PayPal (Preview)
  QuickBooks (Preview)
  Salesforce
  Salesforce Service Cloud
  Salesforce Marketing Cloud
  SAP Cloud for Customer (C4C)
  SAP ECC
  ServiceNow
  Shopify (Preview)
  SharePoint Online List
  Square (Preview)
  Web Table (HTML table)
  Xero
  Zoho (Preview)

Nota

Any connector marked as Preview means that you can try it out and give us feedback. If you want to take a dependency on preview connectors in your solution, please contact Azure support.

SintassiSyntax

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

Proprietà del tipoType properties

NomeName DescrizioneDescription TypeType Obbligatorio?Required?
datasetdataset Fornisce il riferimento al set di dati per la ricerca.Provides the dataset reference for the lookup. Per i dettagli, vedere la sezione Proprietà del set di dati nell'articolo del connettore corrispondente.Get details from the Dataset properties section in each corresponding connector article. Coppia chiave/valoreKey/value pair Yes
sourcesource Contiene proprietà di origine specifiche del set di dati, come per l'origine dell'attività Copy.Contains dataset-specific source properties, the same as the Copy Activity source. Visualizzare i dettagli della sezione Proprietà dell'attività di copia nell'articolo del connettore corrispondente.Get details from the Copy Activity properties section in each corresponding connector article. Coppia chiave/valoreKey/value pair Yes
firstRowOnlyfirstRowOnly Indica se restituire solo la prima riga o tutte le righe.Indicates whether to return only the first row or all rows. BooleanBoolean No.No. Il valore predefinito è true.The default is true.

Nota

  • Le colonne Source con tipo ByteArray non sono supportate.Source columns with ByteArray type aren't supported.
  • Structure non è supportato nella definizione del set di dati.Structure isn't supported in dataset definitions. Per i file in formato testo, è possibile usare la riga di intestazione per specificare il nome della colonna.For text-format files, use the header row to provide the column name.
  • Se l'origine della ricerca è un file JSON, l'impostazione jsonPathDefinition per la modifica della forma dell'oggetto JSON non è supportata.If your lookup source is a JSON file, the jsonPathDefinition setting for reshaping the JSON object isn't supported. Vengono recuperati gli interi oggetti.The entire objects will be retrieved.

Usare il risultato dell'attività di ricercaUse the Lookup activity result

Il risultato della ricerca viene restituito nella sezione output del risultato dell'esecuzione attività.The lookup result is returned in the output section of the activity run result.

  • Se firstRowOnly è impostato su true (impostazione predefinita) , il formato di output è mostrato nel codice seguente.When firstRowOnly is set to true (default), the output format is as shown in the following code. Il risultato della ricerca è sotto una chiave firstRow fissa.The lookup result is under a fixed firstRow key. Per usare il risultato nell'attività successiva, usare il modello di @{activity('LookupActivity').output.firstRow.table} .To use the result in subsequent activity, use the pattern of @{activity('LookupActivity').output.firstRow.table}.

    {
        "firstRow":
        {
            "Id": "1",
            "schema":"dbo",
            "table":"Table1"
        }
    }
    
  • Se firstRowOnly è impostato su false , il formato di output è mostrato nel codice seguente.When firstRowOnly is set to false, the output format is as shown in the following code. Un campo count indica il numero di record restituiti.A count field indicates how many records are returned. I valori dettagliati sono visualizzati sotto una matrice value fissa.Detailed values are displayed under a fixed value array. In questo caso l'attività Lookup è seguita da un'attività ForEach.In such a case, the Lookup activity is followed by a Foreach activity. Per passare l'array value al campo items dell'attività ForEach, usare il criterio di @activity('MyLookupActivity').output.value.You pass the value array to the ForEach activity items field by using the pattern of @activity('MyLookupActivity').output.value. Per accedere agli elementi nell'array value, usare la sintassi seguente: @{activity('lookupActivity').output.value[zero based index].propertyname}.To access elements in the value array, use the following syntax: @{activity('lookupActivity').output.value[zero based index].propertyname}. Un esempio è @{activity('lookupActivity').output.value[0].schema}.An example is @{activity('lookupActivity').output.value[0].schema}.

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

EsempioExample

In questo esempio la pipeline contiene due attività: Lookup e Copy.In this example, the pipeline contains two activities: Lookup and Copy. L'attività di copia copia i dati da una tabella SQL nell'istanza del database SQL di Azure all'archivio BLOB di Azure.The Copy Activity copies data from a SQL table in your Azure SQL Database instance to Azure Blob storage. Il nome della tabella SQL viene archiviato in un file JSON in Archiviazione BLOB.The name of the SQL table is stored in a JSON file in Blob storage. L'attività Lookup cerca il nome della tabella in fase di esecuzione.The Lookup activity looks up the table name at runtime. Il file JSON viene modificato in modo dinamico usando questo approccio.JSON is modified dynamically by using this approach. Non è necessario ridistribuire le pipeline o i set di dati.You don't need to redeploy pipelines or datasets.

In questo esempio viene illustrata la ricerca solo per la prima riga.This example demonstrates lookup for the first row only. Per la ricerca per tutte le righe e per concatenare i risultati con l'attività ForEach, vedere gli esempi in Copiare più tabelle in blocco con Azure Data Factory.For lookup for all rows and to chain the results with ForEach activity, see the samples in Copy multiple tables in bulk by using Azure Data Factory.

PipelinePipeline

  • L'attività Lookup è configurata per usare LookupDataset, che fa riferimento a un percorso di Archiviazione BLOB di Azure.The Lookup activity is configured to use LookupDataset, which refers to a location in Azure Blob storage. L'attività Lookup legge il nome della tabella SQL da un file JSON in questo percorso.The Lookup activity reads the name of the SQL table from a JSON file in this location.
  • L'attività Copy usa l'output dell'attività Lookup, che è il nome della tabella SQL.The Copy Activity uses the output of the Lookup activity, which is the name of the SQL table. La proprietà tableName in SourceDataset è configurata in modo da usare l'output dell'attività Lookup.The tableName property in the SourceDataset is configured to use the output from the Lookup activity. L'attività Copy copia i dati dalla tabella SQL in un percorso di Archiviazione BLOB di Azure.Copy Activity copies data from the SQL table to a location in Azure Blob storage. Il percorso è specificato dalla proprietà SinkDataset.The location is specified by the SinkDataset property.
{
    "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"
    }
}

Set di dati di ricercaLookup dataset

Il set di dati di ricerca è il sourcetable.js file nella cartella di ricerca di archiviazione di Azure specificata dal tipo AzureBlobStorageLinkedService .The lookup dataset is the sourcetable.json file in the Azure Storage lookup folder specified by the AzureBlobStorageLinkedService type.

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

Set di dati di origine per l'attività CopySource dataset for Copy Activity

Il set di dati di origine usa l'output dell'attività Lookup, ovvero il nome della tabella SQL.The source dataset uses the output of the Lookup activity, which is the name of the SQL table. L'attività Copy copia i dati da questa tabella SQL in un percorso di Archiviazione BLOB di Azure.Copy Activity copies data from this SQL table to a location in Azure Blob storage. Il percorso è specificato dal set di dati sink.The location is specified by the sink dataset.

{
    "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"
            }
        }
    }
}

Set di dati sink per l'attività CopySink dataset for Copy Activity

L'attività Copy copia i dati dalla tabella SQL nel file filebylookup.csv file della cartella csv in Archiviazione di Azure.Copy Activity copies data from the SQL table to the filebylookup.csv file in the csv folder in Azure Storage. Il file è specificato dalla proprietà AzureBlobStorageLinkedService .The file is specified by the AzureBlobStorageLinkedService property.

{
    "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.jsonsourcetable.json

È possibile utilizzare i due tipi di formati seguenti per sourcetable.jssu file.You can use following two kinds of formats for sourcetable.json file.

Set di oggettiSet of objects

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

Matrice di oggettiArray of objects

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

Limitazioni e soluzioni alternativeLimitations and workarounds

Di seguito vengono descritte alcune limitazioni dell'attività Lookup con le soluzioni alternative suggerite.Here are some limitations of the Lookup activity and suggested workarounds.

LimitazioneLimitation Soluzione alternativaWorkaround
L'attività Lookup ha un massimo di 5.000 righe e una dimensione massima di 4 MB.The Lookup activity has a maximum of 5,000 rows, and a maximum size of 4 MB. Progettare una pipeline a due livelli in cui la pipeline esterna esegue l'iterazione su una pipeline interna, che recupera i dati che non superano il numero massimo di righe o le dimensioni massime.Design a two-level pipeline where the outer pipeline iterates over an inner pipeline, which retrieves data that doesn't exceed the maximum rows or size.

Passaggi successiviNext steps

Vedere altre attività del flusso di controllo supportate da Data Factory:See other control flow activities supported by Data Factory: