Atividade de pesquisa no Azure Data FactoryLookup activity in Azure Data Factory

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

A atividade Lookup pode recuperar um conjunto de dados de quaisquer fontes de dados compatíveis com o Azure Data Factory.Lookup activity can retrieve a dataset from any of the Azure Data Factory-supported data sources. Use-a no seguinte cenário:Use it in the following scenario:

  • Determinar dinamicamente em quais objetos operar em uma atividade subsequente, em vez de embutir o nome do objeto.Dynamically determine which objects to operate on in a subsequent activity, instead of hard coding the object name. Alguns exemplos de objeto são arquivos e tabelas.Some object examples are files and tables.

A atividade Lookup lê e retorna o conteúdo de um arquivo de configuração ou tabela.Lookup activity reads and returns the content of a configuration file or table. Ela também retorna o resultado da execução de uma consulta ou procedimento armazenado.It also returns the result of executing a query or stored procedure. A saída da atividade Lookup pode ser usada em uma cópia subsequente ou atividade de transformação se for um valor de banco de dados individual.The output from Lookup activity can be used in a subsequent copy or transformation activity if it's a singleton value. A saída poderá ser usada em uma atividade ForEach se for uma matriz de atributos.The output can be used in a ForEach activity if it's an array of attributes.

Funcionalidades com suporteSupported capabilities

As seguintes fontes de dados são compatíveis com a atividade Lookup.The following data sources are supported for Lookup activity.

A atividade de pesquisa pode retornar até 5000 linhas; Se o conjunto de resultados contiver mais registros, as primeiras 5000 linhas serão retornadas.The Lookup activity can return up to 5000 rows; if the result set contains more records, the first 5000 rows will be returned. A saída da atividade de pesquisa dá suporte a até 4 MB de tamanho, a atividade falhará se o tamanho exceder o limite.The Lookup activity output supports up to around 4 MB in size, activity will fail if the size exceeds the limit. Atualmente, a duração mais longa para a atividade de pesquisa antes do tempo limite é de 24 horas.Currently, the longest duration for Lookup activity before timeout is 24 hours.

CategoriaCategory Armazenamento de dadosData store
AzureAzure Armazenamento de Blobs do AzureAzure Blob storage
  Azure Cosmos DB (API do SQL)Azure Cosmos DB (SQL API)
  Azure Data ExplorerAzure Data Explorer
  Azure Data Lake Storage Gen1Azure Data Lake Storage Gen1
  Azure Data Lake Storage Gen2Azure Data Lake Storage Gen2
  Banco de Dados do Azure para MariaDBAzure Database for MariaDB
  Banco de Dados do Azure para MySQLAzure Database for MySQL
  Banco de Dados do Azure para PostgreSQLAzure Database for PostgreSQL
  Delta Lake do Azure DatabricksAzure Databricks Delta Lake
  Arquivos do AzureAzure Files
  Banco de Dados SQL do AzureAzure SQL Database
  Instância Gerenciada do SQL do AzureAzure SQL Managed Instance
  Azure Synapse AnalyticsAzure Synapse Analytics
  Armazenamento de Tabelas do AzureAzure Table storage
Backup de banco de dadosDatabase Amazon RedshiftAmazon Redshift
  DB2DB2
  Aprofundar-seDrill
  Google BigQueryGoogle BigQuery
  GreenplumGreenplum
  HBaseHBase
  HiveHive
  Apache ImpalaApache Impala
  InformixInformix
  MariaDBMariaDB
  Microsoft AccessMicrosoft Access
  MySQLMySQL
  NetezzaNetezza
  OracleOracle
  PhoenixPhoenix
  PostgreSQLPostgreSQL
  ProntoPresto
  SAP Business Warehouse Open HubSAP Business Warehouse Open Hub
  SAP Business Warehouse via MDXSAP Business Warehouse via MDX
  SAP HANASAP HANA
  SAP TableSAP Table
  SnowflakeSnowflake
  SparkSpark
  SQL ServerSQL Server
  SybaseSybase
  TeradataTeradata
  VerticaVertica
NoSQLNoSQL CassandraCassandra
  Couchbase (versão prévia)Couchbase (Preview)
ArquivoFile Amazon S3Amazon S3
  Sistema de ArquivosFile System
  FTPFTP
  Google Cloud StorageGoogle Cloud Storage
  HDFSHDFS
  SFTPSFTP
Projeto genéricoGeneric protocol HTTP GenéricoGeneric HTTP
  OData GenéricoGeneric OData
  ODBC GenéricoGeneric ODBC
Serviços e aplicativosServices and apps Serviço Web do Amazon MarketplaceAmazon Marketplace Web Service
  Common Data Service para aplicativosCommon Data Service for Apps
  Concorrente (versão prévia)Concur (Preview)
  Dynamics 365Dynamics 365
  Dynamics AXDynamics AX
  Dynamics CRMDynamics CRM
  Google AdWordsGoogle AdWords
  HubSpotHubSpot
  JiraJira
  Magento (versão prévia)Magento (Preview)
  Marketo (versão prévia)Marketo (Preview)
  Oracle Eloqua (versão prévia)Oracle Eloqua (Preview)
  Oracle Responsys (versão prévia)Oracle Responsys (Preview)
  Serviço de Nuvem da Oracle (Versão prévia)Oracle Service Cloud (Preview)
  PayPal (versão prévia)PayPal (Preview)
  QuickBooks (versão prévia)QuickBooks (Preview)
  SalesforceSalesforce
  Nuvem de serviço SalesforceSalesforce Service Cloud
  Nuvem de Marketing SalesforceSalesforce Marketing Cloud
  SAP Cloud for Customer (C4C)SAP Cloud for Customer (C4C)
  SAP ECCSAP ECC
  ServiceNowServiceNow
  Shopify (versão prévia)Shopify (Preview)
  Lista do SharePoint OnlineSharePoint Online List
  Square (versão prévia)Square (Preview)
  Tabela da Web (tabela HTML)Web Table (HTML table)
  XeroXero
  Zoho (versão prévia)Zoho (Preview)

Observação

Um conector marcado como versão prévia significa que você pode experimentá-lo e nos enviar comentários.Any connector marked as Preview means that you can try it out and give us feedback. Se você quiser uma dependência de conectores em versão prévia em sua solução, entre em contato com suporte do Azure.If you want to take a dependency on preview connectors in your solution, please contact Azure support.

SintaxeSyntax

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

Propriedades de tipoType properties

NomeName DescriçãoDescription TypeType Obrigatório?Required?
datasetdataset Fornece a referência de conjunto de dados para a pesquisa.Provides the dataset reference for the lookup. Obtenha detalhes na seção Propriedades do conjunto de dados em cada artigo de conector correspondente.Get details from the Dataset properties section in each corresponding connector article. Pares chave/valorKey/value pair SimYes
sourcesource Contém propriedades de origem específicas do banco de dados, as mesmas que as da origem da atividade Copy.Contains dataset-specific source properties, the same as the Copy Activity source. Obtenha detalhes na seção Propriedades da atividade Copy em cada artigo de conector correspondente.Get details from the Copy Activity properties section in each corresponding connector article. Pares chave/valorKey/value pair SimYes
firstRowOnlyfirstRowOnly Indica se deve-se retornar apenas a primeira linha ou todas as linhas.Indicates whether to return only the first row or all rows. BooleanBoolean Não.No. O padrão é true.The default is true.

Observação

  • Não há suporte para as colunas de origem com o tipo ByteArray.Source columns with ByteArray type aren't supported.
  • Não há suporte para Estrutura nas definições do conjunto de dados.Structure isn't supported in dataset definitions. Para arquivos de formato de texto, use a linha de cabeçalho para fornecer o nome da coluna.For text-format files, use the header row to provide the column name.
  • Se sua origem da pesquisa for um arquivo JSON, não haverá suporte para a configuração jsonPathDefinition para remodelar o objeto JSON.If your lookup source is a JSON file, the jsonPathDefinition setting for reshaping the JSON object isn't supported. Os objetos inteiros serão recuperados.The entire objects will be retrieved.

Usar o resultado da atividade de pesquisaUse the Lookup activity result

O resultado de pesquisa é retornado na seção output do resultado da execução de atividade.The lookup result is returned in the output section of the activity run result.

  • Quando firstRowOnly é definido como true (padrão) , o formato de saída é como mostrado no código a seguir.When firstRowOnly is set to true (default), the output format is as shown in the following code. O resultado da pesquisa fica sob um chave firstRow fixa.The lookup result is under a fixed firstRow key. Para usar o resultado na atividade subsequente, use o padrão de @{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"
        }
    }
    
  • Quando firstRowOnly for definido como false (padrão) , o formato de saída será como mostrado no código a seguir.When firstRowOnly is set to false, the output format is as shown in the following code. Um campo count indica quantos registros são retornados.A count field indicates how many records are returned. Os valores detalhados são exibidos em uma matriz value fixa.Detailed values are displayed under a fixed value array. Nesse caso, a atividade Lookup é seguida por uma atividade Foreach.In such a case, the Lookup activity is followed by a Foreach activity. Passe a matriz value para o campo items da atividade ForEach usando o padrão de @activity('MyLookupActivity').output.value.You pass the value array to the ForEach activity items field by using the pattern of @activity('MyLookupActivity').output.value. Para acessar elementos na matriz value, use a seguinte sintaxe: @{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}. Um exemplo é @{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"
            }
        ]
    } 
    

ExemploExample

Neste exemplo, o pipeline contém duas atividades: Lookup e Copy.In this example, the pipeline contains two activities: Lookup and Copy. A atividade de cópia copia dados de uma tabela SQL em sua instância do banco de dados SQL do Azure para o armazenamento de BLOBs do Azure.The Copy Activity copies data from a SQL table in your Azure SQL Database instance to Azure Blob storage. O nome da tabela SQL é armazenado em um arquivo JSON em armazenamento de Blob.The name of the SQL table is stored in a JSON file in Blob storage. A atividade Lookup pesquisa o nome da tabela em runtime.The Lookup activity looks up the table name at runtime. O JSON é modificado dinamicamente usando essa abordagem.JSON is modified dynamically by using this approach. Não é necessário reimplantar pipelines ou conjuntos de dados.You don't need to redeploy pipelines or datasets.

Este exemplo demonstra a pesquisa apenas para a primeira linha.This example demonstrates lookup for the first row only. Para pesquisar por todas as linhas e para encadear os resultados com a atividade ForEach, consulte os exemplos em Copiar várias tabelas em massa usando o 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

  • A atividade Lookup está configurada para usar LookupDataset, que se refere a um local no armazenamento de Blobs do Azure.The Lookup activity is configured to use LookupDataset, which refers to a location in Azure Blob storage. A atividade Lookup lê o nome da tabela SQL de um arquivo JSON nesse local.The Lookup activity reads the name of the SQL table from a JSON file in this location.
  • A atividade de cópia usa a saída da atividade de pesquisa, que é o nome da tabela SQL.The Copy Activity uses the output of the Lookup activity, which is the name of the SQL table. A propriedade tableName no SourceDataset está configurada para usar a saída da atividade Lookup.The tableName property in the SourceDataset is configured to use the output from the Lookup activity. A atividade Copy copia dados da tabela SQL para um local no armazenamento de Blobs do Azure.Copy Activity copies data from the SQL table to a location in Azure Blob storage. O local é especificado pela propriedade 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"
    }
}

Conjunto de dados de pesquisaLookup dataset

O conjunto de pesquisa é o sourcetable.jsno arquivo na pasta de pesquisa do armazenamento do Azure especificada pelo 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"
            }
        }
    }
}

Conjunto de dados de origem da atividade CopySource dataset for Copy Activity

O conjunto de dados de origem usa a saída da atividade Lookup, que é o nome da tabela SQL.The source dataset uses the output of the Lookup activity, which is the name of the SQL table. A atividade Copy copia dados dessa tabela SQL para um local no armazenamento de Blobs do Azure.Copy Activity copies data from this SQL table to a location in Azure Blob storage. O local é especificado pelo conjunto de dados do coletor.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"
            }
        }
    }
}

Conjunto de dados do coletor da atividade CopySink dataset for Copy Activity

A atividade Copy copia dados da tabela SQL para o arquivo filebylookup.csv na pasta csv no Armazenamento do Azure.Copy Activity copies data from the SQL table to the filebylookup.csv file in the csv folder in Azure Storage. O arquivo é especificado pela propriedade 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

Você pode usar os dois tipos de formatos a seguir para sourcetable.jsno arquivo.You can use following two kinds of formats for sourcetable.json file.

Conjunto de objetosSet of objects

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

Matriz de objetosArray of objects

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

Limitações e Soluções AlternativasLimitations and workarounds

Aqui estão algumas limitações da atividade de pesquisa e soluções alternativas sugeridas.Here are some limitations of the Lookup activity and suggested workarounds.

LimitaçõesLimitation Solução alternativaWorkaround
A atividade de pesquisa tem um máximo de 5.000 linhas e um tamanho máximo de 2 MB.The Lookup activity has a maximum of 5,000 rows, and a maximum size of 2 MB. Crie um pipeline de dois níveis onde o pipeline externo itera em um pipeline interno que recupera os dados que não excedem o máximo de linhas ou o tamanho.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.

Próximas etapasNext steps

Consulte outras atividades de fluxo de controle com suporte pelo Data Factory:See other control flow activities supported by Data Factory: