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

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. Usarla nel seguente scenario:Use it in the following scenario:

  • Determinare in modo dinamico gli oggetti su cui operare in un'attività successiva, anziché impostare come hardcoded il nome dell'oggetto.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 dall'attività Lookup può essere usato in un'attività di trasformazione o di copia successiva se è un valore singleton.The output from Lookup activity can be used in a subsequent copy or transformation activity if it's a singleton value. Può essere usato in un'attività ForEach se è una matrice di attributi.The output can be used in a ForEach activity if it's an array of attributes.

Funzionalità supportateSupported capabilities

Per l'attività Lookup attualmente sono supportate le origini dati seguenti.The following data sources are supported for Lookup activity. Il numero massimo di righe restituite dall'attività Lookup è 5.000 e la dimensione massima è 2 MB.The largest number of rows that can be returned by Lookup activity is 5,000, up to 2 MB in size. Attualmente, la durata massima per l'attività Lookup prima del timeout è un'ora.Currently, the longest duration for Lookup activity before timeout is one hour.

CategoryCategory Archivio datiData store
AzureAzure Archivio BLOB di AzureAzure Blob storage
  Azure Cosmos DB (API SQL)Azure Cosmos DB (SQL API)
  Esplora dati di AzureAzure Data Explorer
  Azure Data Lake Storage Gen1Azure Data Lake Storage Gen1
  Azure Data Lake Storage Gen2Azure Data Lake Storage Gen2
  Database di Azure per MariaDBAzure Database for MariaDB
  Database di Azure per MySQLAzure Database for MySQL
  Database di Azure per PostgreSQLAzure Database for PostgreSQL
  File di AzureAzure Files
  Database SQL di AzureAzure SQL Database
  Istanza gestita di database SQL di AzureAzure SQL Database Managed Instance
  Azure SQL Data WarehouseAzure SQL Data Warehouse
  Archivio tabelle di AzureAzure Table storage
DatabaseDatabase Amazon RedshiftAmazon Redshift
  DB2DB2
  Drill (anteprima)Drill (Preview)
  Google BigQueryGoogle BigQuery
  GreenplumGreenplum
  HBaseHBase
  HiveHive
  Apache Impala (anteprima)Apache Impala (Preview)
  InformixInformix
  MariaDBMariaDB
  Microsoft AccessMicrosoft Access
  MySQLMySQL
  NetezzaNetezza
  OracleOracle
  PhoenixPhoenix
  PostgreSQLPostgreSQL
  Presto (anteprima)Presto (Preview)
  SAP Business Warehouse Open HubSAP Business Warehouse Open Hub
  SAP Business Warehouse via MDXSAP Business Warehouse via MDX
  SAP HANASAP HANA
  Tabella SAPSAP Table
  SparkSpark
  SQL ServerSQL Server
  SybaseSybase
  TeradataTeradata
  VerticaVertica
NoSQLNoSQL CassandraCassandra
  Couchbase (anteprima)Couchbase (Preview)
FileFile Amazon S3Amazon S3
  File systemFile System
  FTPFTP
  Google Cloud StorageGoogle Cloud Storage
  HDFSHDFS
  SFTPSFTP
Protocollo genericoGeneric protocol HTTP genericoGeneric HTTP
  OData genericoGeneric OData
  ODBC genericoGeneric ODBC
Servizi e appServices and apps Amazon Marketplace Web Service (anteprima)Amazon Marketplace Web Service (Preview)
  Common Data Service per le appCommon Data Service for Apps
  Concur (anteprima)Concur (Preview)
  Dynamics 365Dynamics 365
  Dynamics AX (Anteprima)Dynamics AX (Preview)
  Dynamics CRMDynamics CRM
  Google AdWords (Anteprima)Google AdWords (Preview)
  HubSpot (anteprima)HubSpot (Preview)
  Jira (anteprima)Jira (Preview)
  Magento (anteprima)Magento (Preview)
  Marketo (anteprima)Marketo (Preview)
  Oracle Eloqua (anteprima)Oracle Eloqua (Preview)
  Oracle Responsys (anteprima)Oracle Responsys (Preview)
  Oracle Service Cloud (anteprima)Oracle Service Cloud (Preview)
  PayPal (anteprima)Paypal (Preview)
  QuickBooks (anteprima)QuickBooks (Preview)
  SalesforceSalesforce
  Cloud del servizio SalesforceSalesforce Service Cloud
  Salesforce Marketing Cloud (anteprima)Salesforce Marketing Cloud (Preview)
  SAP Cloud for Customer (C4C)SAP Cloud for Customer (C4C)
  SAP ECCSAP ECC
  ServiceNowServiceNow
  Shopify (anteprima)Shopify (Preview)
  Square (anteprima)Square (Preview)
  Tabella Web (tabella HTML)Web Table (HTML table)
  Xero (anteprima)Xero (Preview)
  Zoho (anteprima)Zoho (Preview)

Nota

Se un connettore è contrassegnato come Anteprima, è possibile provarlo e inviare commenti e suggerimenti.Any connector marked as Preview means that you can try it out and give us feedback. Se si vuole accettare una dipendenza dai connettori in versione di anteprima nella propria soluzione, contattare il supporto tecnico di Azure.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>"
            <additional source specific properties (optional)>
        },
        "dataset": { 
            "referenceName": "<source dataset name>",
            "type": "DatasetReference"
        },
        "firstRowOnly": 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 YesYes
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 YesYes
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à Lookup in un'attività successivaUse the Lookup activity result in a subsequent activity

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 in un'attività successiva, usare il criterio di @{activity('MyLookupActivity').output.firstRow.TableName}.To use the result in subsequent activity, use the pattern of @{activity('MyLookupActivity').output.firstRow.TableName}.

    {
        "firstRow":
        {
            "Id": "1",
            "TableName" : "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].tablename}.An example is @{activity('lookupActivity').output.value[0].tablename}.

    {
        "count": "2",
        "value": [
            {
                "Id": "1",
                "TableName" : "Table1"
            },
            {
                "Id": "2",
                "TableName" : "Table2"
            }
        ]
    } 
    

Esempio di attività di copiaCopy Activity example

In questo esempio l'attività Copy copia i dati da una tabella SQL dell'istanza del database SQL di Azure in Archiviazione BLOB di Azure.In this example, 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

Questa pipeline contiene due attività: Lookup e Copy.This pipeline contains two activities: Lookup and Copy.

  • 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, ovvero il nome della tabella SQL.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",
                "typeProperties": {
                    "source": {
                        "type": "BlobSource"
                    },
                    "dataset": { 
                        "referenceName": "LookupDataset", 
                        "type": "DatasetReference" 
                    }
                }
            },
            {
                "name": "CopyActivity",
                "type": "Copy",
                "typeProperties": {
                    "source": { 
                        "type": "SqlSource", 
                        "sqlReaderQuery": "select * from @{activity('LookupActivity').output.firstRow.tableName}" 
                    },
                    "sink": { 
                        "type": "BlobSink" 
                    }
                },                
                "dependsOn": [ 
                    { 
                        "activity": "LookupActivity", 
                        "dependencyConditions": [ "Succeeded" ] 
                    }
                 ],
                "inputs": [ 
                    { 
                        "referenceName": "SourceDataset", 
                        "type": "DatasetReference" 
                    } 
                ],
                "outputs": [ 
                    { 
                        "referenceName": "SinkDataset", 
                        "type": "DatasetReference" 
                    } 
                ]
            }
        ]
    }
}

Set di dati di ricercaLookup dataset

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

{
    "name": "LookupDataset",
    "properties": {
        "type": "AzureBlob",
        "typeProperties": {
            "folderPath": "lookup",
            "fileName": "sourcetable.json",
            "format": {
                "type": "JsonFormat",
                "filePattern": "SetOfObjects"
            }
        },
        "linkedServiceName": {
            "referenceName": "AzureStorageLinkedService",
            "type": "LinkedServiceReference"
        }
    }
}

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": {
        "type": "AzureSqlTable",
        "typeProperties":{
            "tableName": "@{activity('LookupActivity').output.firstRow.tableName}"
        },
        "linkedServiceName": {
            "referenceName": "AzureSqlLinkedService",
            "type": "LinkedServiceReference"
        }
    }
}

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à AzureStorageLinkedService.The file is specified by the AzureStorageLinkedService property.

{
    "name": "SinkDataset",
    "properties": {
        "type": "AzureBlob",
        "typeProperties": {
            "folderPath": "csv",
            "fileName": "filebylookup.csv",
            "format": {
                "type": "TextFormat"                                                                    
            }
        },
        "linkedServiceName": {
            "referenceName": "AzureStorageLinkedService",
            "type": "LinkedServiceReference"
        }
    }
}

Servizio collegato Archiviazione di AzureAzure Storage linked service

Questo account di archiviazione contiene il file JSON con i nomi delle tabelle SQL.This storage account contains the JSON file with the names of the SQL tables.

{
    "properties": {
        "type": "AzureStorage",
        "typeProperties": {
            "connectionString": {
                "value": "DefaultEndpointsProtocol=https;AccountName=<StorageAccountName>;AccountKey=<StorageAccountKey>",
                "type": "SecureString"
            }
        }
    },
        "name": "AzureStorageLinkedService"
}

Servizio collegato per il database SQL di AzureAzure SQL Database linked service

L'istanza del database SQL di Azure contiene i dati da copiare in Archiviazione BLOB.This Azure SQL Database instance contains the data to be copied to Blob storage.

{
    "name": "AzureSqlLinkedService",
    "properties": {
        "type": "AzureSqlDatabase",
        "description": "",
        "typeProperties": {
            "connectionString": {
                "value": "Server=<server>;Initial Catalog=<database>;User ID=<user>;Password=<password>;",
                "type": "SecureString"
            }
        }
    }
}

sourcetable.jsonsourcetable.json

Set di oggettiSet of objects

{
  "Id": "1",
  "tableName": "Table1"
}
{
   "Id": "2",
  "tableName": "Table2"
}

Matrice di oggettiArray of objects

[ 
    {
        "Id": "1",
        "tableName": "Table1"
    },
    {
        "Id": "2",
        "tableName": "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
Per l'attività Lookup sono previsti un massimo di 5.000 righe e dimensioni massime di 2 MB.The Lookup activity has a maximum of 5,000 rows, and a maximum size of 2 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: