Compartilhar via

Copiar e transformar dados de e para um ponto de extremidade REST usando o Azure Data Factory

  • Artigo

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Dica

Experimente o Data Factory no Microsoft Fabric, uma solução de análise tudo-em-um para empresas. O Microsoft Fabric abrange desde movimentação de dados até ciência de dados, análise em tempo real, business intelligence e relatórios. Saiba como iniciar uma avaliação gratuita!

Este artigo descreve como usar a Atividade de Cópia no Azure Data Factory para copiar dados de e para um ponto de extremidade REST. O artigo baseia-se em Atividade de Cópia no Azure Data Factory, que apresenta uma visão geral da Atividade de Cópia.

As diferenças entre o conector REST, o conector HTTP e o conector de tabela da Web são:

  • O conector REST oferece suporte especificamente à cópia de dados de APIs RESTful.
  • O conector HTTP é genérico e recupera dados de qualquer ponto de extremidade HTTP, por exemplo, fazendo o download de um arquivo. Antes do conector REST, você pode ter usado o conector HTTP para copiar dados das APIs RESTful, que tem suporte mas é menos funcional em comparação ao conector REST.
  • O conector da tabela da Web extrai o conteúdo da tabela de uma página da Web em HTML.

Funcionalidades com suporte

Há suporte para este conector do REST nas seguintes funcionalidades:

Funcionalidades com suporte IR
Atividade de cópia (origem/coletor) ① ②
Fluxo de dados de mapeamento (origem/coletor) ①

① Runtime de integração do Azure ② Runtime de integração auto-hospedada

Para obter uma lista de armazenamentos de dados com suporte como origens/coletores, consulte Armazenamentos de dados com suporte.

Especificamente, esse conector REST genérico dá suporte para:

  • Copiar dados de um ponto de extremidade REST usando os métodos GET ou POST e copiar dados para um ponto de extremidade REST usando os métodos POST, PUT ou PATCH.
  • Copiar dados usando uma das seguintes autenticações: Anônimo, Básico, Entidade de Serviço, Credencial de Cliente OAuth2, Identidade Gerenciada Atribuída pelo Sistema e Identidade Gerenciada Atribuída pelo Usuário.
  • Paginação no APIs REST.
  • No caso do REST como origem, copiar a resposta JSON do REST como está ou analisá-la usando um mapeamento de esquema. Somente o conteúdo de resposta na JSON tem suporte.

Dica

Para testar uma solicitação para recuperação de dados antes de configurar o conector REST no Data Factory, saiba mais sobre a especificação da API para os requisitos de cabeçalho e corpo. É possível usar as ferramentas como o Visual Studio, o Invoke-RestMethod do PowerShell ou um navegador da Web para validar.

Pré-requisitos

Se o armazenamento de dados estiver localizado dentro de uma rede local, em uma rede virtual do Azure ou na Amazon Virtual Private Cloud, você precisará configurar um runtime de integração auto-hospedada para se conectar a ele.

Se o armazenamento de dados for um serviço de dados de nuvem gerenciado, você poderá usar o Azure Integration Runtime. Se o acesso for restrito aos IPs que estão aprovados nas regras de firewall, você poderá adicionar IPs do Azure Integration Runtime à lista de permissões.

Você também pode usar o recurso de runtime de integração da rede virtual gerenciada no Azure Data Factory para acessar a rede local sem instalar e configurar um runtime de integração auto-hospedada.

Para obter mais informações sobre os mecanismos de segurança de rede e as opções compatíveis com o Data Factory, consulte Estratégias de acesso a dados.

Introdução

Para executar a atividade de Cópia com um pipeline, será possível usar as ferramentas ou os SDKs abaixo:

Criar um serviço vinculado REST usando a interface do usuário

Use as etapas a seguir para criar um serviço vinculado ao REST na interface do usuário do portal do Microsoft Azure.

  1. Navegue até a guia Gerenciar no workspace do Azure Data Factory ou do Synapse e selecione Serviços Vinculados. Depois, selecione Novo:

  2. Pesquise por REST e selecione o conector REST.

    Selecione o conector REST.

  3. Configure os detalhes do serviço, teste a conexão e crie o novo serviço vinculado.

    Configure o serviço vinculado REST.

Detalhes da configuração do conector

As seções a seguir fornecem detalhes sobre propriedades que você pode usar para definir entidades do Data Factory específicas do conector REST.

Propriedades do serviço vinculado

As seguintes propriedades são suportadas para o serviço vinculado REST:

Propriedade Descrição Obrigatório
type A propriedade type deve ser definida como RestService. Sim
url A URL base do serviço REST. Sim
enableServerCertificateValidation Validar ou não o certificado TLS/SSL no lado do servidor ao se conectar ao ponto de extremidade. Não
(o padrão é verdadeiro)
authenticationType Tipo de autenticação usado para se conectar ao serviço REST. Os valores permitidos são Anônimo, Básico, AadServicePrincipal, OAuth2ClientCredential e ManagedServiceIdentity. Também é possível configurar cabeçalhos de autenticação na propriedade authHeaders. Consulte respectivamente as seções correspondentes abaixo em mais propriedades e exemplos. Sim
authHeaders Cabeçalhos de solicitação HTTP adicionais para autenticação.
Por exemplo, para usar a autenticação de chave de API, você poderá selecionar o tipo de autenticação como “Anônimo” e especificar a chave de API no cabeçalho.		 Não
connectVia O runtime de integração a ser usado para se conectar ao armazenamento de dados. Saiba mais na seção Pré-requisitos. Se não especificado, essa propriedade usará o Azure Integration Runtime padrão. Não

Para diferentes tipos de autenticação, consulte as seções correspondentes para obter detalhes.

Usar autenticação básica

Defina a authenticationType na propriedade Básico. Além das propriedades genéricas descritas na seção anterior, especifique as seguintes propriedades:

Propriedade Descrição Obrigatório
userName O nome de usuário a ser usado para acessar o ponto de extremidade REST. Sim
password A senha do usuário (o nome de usuário valor). Marque esse campo como um tipo SecureString para armazená-lo com segurança no Data Factory. Você também pode referenciar um segredo armazenado no Cofre de Chaves do Azure. Sim

Exemplo

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "authenticationType": "Basic",
            "url" : "<REST endpoint>",
            "userName": "<user name>",
            "password": {
                "type": "SecureString",
                "value": "<password>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Usar a autenticação de Entidade de Serviço

Defina a authenticationType na propriedade AadServicePrincipal. Além das propriedades genéricas descritas na seção anterior, especifique as seguintes propriedades:

Propriedade Descrição Obrigatório
servicePrincipalId Especifique a ID do cliente do aplicativo do Microsoft Entra. Sim
servicePrincipalCredentialType Especifique o tipo de credencial a ser usada para autenticação da entidade de serviço. Os valores permitidos são ServicePrincipalKey e ServicePrincipalCert. Não
Para ServicePrincipalKey
servicePrincipalKey Especifique a chave do aplicativo do Microsoft Entra. Marque esse campo como SecureString para armazená-lo com segurança no Data Factory ou referencie um segredo armazenado no Cofre de Chaves do Azure. Não
Para ServicePrincipalCert
servicePrincipalEmbeddedCert Especifique o certificado codificado em base64 do aplicativo registrado no Microsoft Entra ID e cerifique-se de que o tipo de conteúdo do certificado é PKCS #12. Marque esse campo como SecureString para armazená-lo com segurança ou referencie um segredo armazenado no Azure Key Vault. Vá para esta seção para saber como salvar o certificado no Azure Key Vault. Não
servicePrincipalEmbeddedCertPassword Especifique a senha de seu certificado se o certificado for protegido por senha. Marque esse campo como SecureString para armazená-lo com segurança ou referencie um segredo armazenado no Azure Key Vault. Não
locatário Especifique as informações de locatário (domínio nome ou ID do Locatário) em que o aplicativo reside. Para recuperá-lo, passe o mouse no canto superior direito do portal do Azure. Sim
aadResourceId Especifique o recurso do Microsoft Entra para o qual você está solicitando autorização, por exemplo, https://management.core.windows.net. Sim
azureCloudType Para autenticação da Entidade de Serviço, especifique o tipo de ambiente de nuvem do Azure no qual o aplicativo do Microsoft Entra está registrado.
Os valores permitidos são AzurePublic, AzureChina, AzureUsGovernment e AzureGermany. Por padrão, o ambiente de nuvem do data factory é usado.		 Não

Exemplo 1: Usando autenticação de chave principal de serviço

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint e.g. https://www.example.com/>",
            "authenticationType": "AadServicePrincipal",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalCredentialType": "ServicePrincipalKey",
            "servicePrincipalKey": {
                "value": "<service principal key>",
                "type": "SecureString"
            },
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>",
            "aadResourceId": "<Azure AD resource URL e.g. https://management.core.windows.net>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Exemplo 2: Usando autenticação de certificado de entidade de serviço

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint e.g. https://www.example.com/>",
            "authenticationType": "AadServicePrincipal",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalCredentialType": "ServicePrincipalCert",
            "servicePrincipalEmbeddedCert": {
                "type": "SecureString",
                "value": "<the base64 encoded certificate of your application registered in Microsoft Entra ID>"
            },
            "servicePrincipalEmbeddedCertPassword": {
                "type": "SecureString",
                "value": "<password of your certificate>"
            },
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>",
            "aadResourceId": "<Azure AD resource URL e.g. https://management.core.windows.net>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

O certificado da entidade de serviço do Azure Key Vault

Você tem duas opções para salvar o certificado da entidade de serviço no Azure Key Vault:

  • Opção 1

    1. Converta o certificado da entidade de serviço em uma cadeia de caracteres base64. Saiba maisdeste artigo.

    2. Salve a cadeia de caracteres base64 como um segredo no Azure Key Vault.

      Captura de tela dos segredos.

      Captura de tela do valor do segredo.

  • Opção 2

    Se você não conseguir baixar o certificado do Azure Key Vault, poderá usar este modelo para salvar o certificado da entidade de serviço convertida como um segredo no Azure Key Vault.

    Captura de tela do pipeline de modelo para salvar o certificado da entidade de serviço como um segredo no AKV.

Usar a autenticação de credencial do cliente OAuth2

Defina o authenticationType na propriedade OAuth2ClientCredential. Além das propriedades genéricas descritas na seção anterior, especifique as seguintes propriedades:

Propriedade Descrição Obrigatório
tokenEndpoint O ponto de extremidade de token do servidor de autorização para adquirir o token de acesso. Sim
clientId A ID de cliente associada ao seu aplicativo. Sim
clientSecret O segredo de cliente associado ao seu aplicativo. Marque esse campo como um tipo SecureString para armazená-lo com segurança no Data Factory. Você também pode referenciar um segredo armazenado no Cofre de Chaves do Azure. Sim
scope O escopo do acesso necessário. Ele descreve que tipo de acesso será solicitado. No
recurso O serviço de destino ou o recurso ao qual o acesso será solicitado. Não

Exemplo

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint e.g. https://www.example.com/>",
            "enableServerCertificateValidation": true,
            "authenticationType": "OAuth2ClientCredential",
            "clientId": "<client ID>",
            "clientSecret": {
                "type": "SecureString",
                "value": "<client secret>"
            },
            "tokenEndpoint": "<token endpoint>",
            "scope": "<scope>",
            "resource": "<resource>"
        }
    }
}

Usar a autenticação de identidade gerenciada atribuída pelo sistema

Defina a authenticationType na propriedade ManagedServiceIdentity. Além das propriedades genéricas descritas na seção anterior, especifique as seguintes propriedades:

Propriedade Descrição Obrigatório
aadResourceId Especifique o recurso do Microsoft Entra para o qual você está solicitando autorização, por exemplo, https://management.core.windows.net. Sim

Exemplo

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint e.g. https://www.example.com/>",
            "authenticationType": "ManagedServiceIdentity",
            "aadResourceId": "<AAD resource URL e.g. https://management.core.windows.net>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Usar a autenticação de identidade gerenciada atribuída pelo usuário

Defina a authenticationType na propriedade ManagedServiceIdentity. Além das propriedades genéricas descritas na seção anterior, especifique as seguintes propriedades:

Propriedade Descrição Obrigatório
aadResourceId Especifique o recurso do Microsoft Entra para o qual você está solicitando autorização, por exemplo, https://management.core.windows.net. Sim
credenciais Especifique a identidade gerenciada atribuída pelo usuário como o objeto da credencial. Sim

Exemplo

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint e.g. https://www.example.com/>",
            "authenticationType": "ManagedServiceIdentity",
            "aadResourceId": "<Azure AD resource URL e.g. https://management.core.windows.net>",
            "credential": {
                "referenceName": "credential1",
                "type": "CredentialReference"
            }    
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Usar cabeçalhos de autenticação

Também é possível configurar cabeçalhos de solicitação para autenticação junto com os tipos de autenticação internos.

Exemplo: Usar a autenticação de chave de API

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint>",
            "authenticationType": "Anonymous",
            "authHeaders": {
                "x-api-key": {
                    "type": "SecureString",
                    "value": "<API key>"
                }
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Propriedades do conjunto de dados

Esta seção fornece uma lista de propriedades que o conjunto de dados REST suporta.

Para obter uma lista completa de seções e propriedades disponíveis para definição de conjuntos de dados, consulte Conjuntos de dados e serviços vinculados.

Para copiar dados do REST, há suporte para as seguintes propriedades:

Propriedade Descrição Obrigatório
type A propriedade tipo do conjunto de dados deve ser definida comoRestResource. Sim
relativeUrl Uma URL relativa para o recurso que contém os dados. Quando essa propriedade não é especificada, somente o URL especificado na definição de serviço vinculada é usado. O conector HTTP copia os dados da URL combinada: [URL specified in linked service]/[relative URL specified in dataset]. Não

Se você estiver definindo requestMethod, additionalHeaders, requestBody e paginationRules no conjunto de dados, ainda há suporte para eles no estado em que se encontram, mas, de agora em diante, recomendamos usar o novo modelo em atividade.

Exemplo:

{
    "name": "RESTDataset",
    "properties": {
        "type": "RestResource",
        "typeProperties": {
            "relativeUrl": "<relative url>"
        },
        "schema": [],
        "linkedServiceName": {
            "referenceName": "<REST linked service name>",
            "type": "LinkedServiceReference"
        }
    }
}

Propriedades da Atividade de Cópia

Esta seção fornece uma lista das propriedades com suporte da origem e do coletor REST.

Para obter uma lista completa de seções e propriedades que estão disponíveis para definir atividades, consulte Pipelines.

REST como fonte

As propriedades a seguir têm suporte na seção source da atividade de cópia:

Propriedade Descrição Obrigatório
type O tipo de propriedade da fonte da atividade de cópia deve ser definida como: RestSource. Sim
requestMethod O método HTTP. Os valores permitidos são GET (padrão) e POST. Não
additionalHeaders Cabeçalhos de solicitação HTTP adicionais. Não
requestBody O corpo da solicitação HTTP. Não
paginationRules As regras de paginação para compor as próximas solicitações de página. Consulte a seção suporte à paginação em detalhes. Não
httpRequestTimeout O tempo limite (o valor TimeSpan) para a solicitação HTTP para obter uma resposta. Esse valor é o tempo limite para obter uma resposta, não o tempo limite para ler os dados da resposta. O valor padrão é 01:00:40. Não
requestInterval O tempo de espera antes de enviar a solicitação para a próxima página. O valor padrão é 00:00:01 Não

Observação

O conector REST ignora qualquer cabeçalho "Accept" especificado em additionalHeaders. Como o conector REST só dá suporte à resposta em JSON, ele gerará automaticamente um cabeçalho de Accept: application/json.
A matriz de objeto como corpo da resposta não é suportada na paginação.

Exemplo 1: Usando o método Get com paginação

"activities":[
    {
        "name": "CopyFromREST",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<REST input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "RestSource",
                "additionalHeaders": {
                    "x-user-defined": "helloworld"
                },
                "paginationRules": {
                    "AbsoluteUrl": "$.paging.next"
                },
                "httpRequestTimeout": "00:01:00"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Exemplo 2: Usando o método Post

"activities":[
    {
        "name": "CopyFromREST",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<REST input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "RestSource",
                "requestMethod": "Post",
                "requestBody": "<body for POST REST request>",
                "httpRequestTimeout": "00:01:00"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

REST como coletor

As propriedades a seguir têm suporte na seção sink da atividade de cópia:

Propriedade Descrição Obrigatório
type A propriedade type do coletor da atividade de cópia deve ser definida como RestSink. Sim
requestMethod O método HTTP. Os valores permitidos são POST (padrão), PUTe PATCH. Não
additionalHeaders Cabeçalhos de solicitação HTTP adicionais. Não
httpRequestTimeout O tempo limite (o valor TimeSpan) para a solicitação HTTP para obter uma resposta. Esse valor é o tempo limite para obter uma resposta, não o tempo limite para gravar os dados. O valor padrão é 01:00:40. Não
requestInterval O intervalo entre diferentes solicitações em milissegundos. O valor do intervalo de solicitação deve ser um número entre [10, 60000]. Não
httpCompressionType Tipo de compactação HTTP a ser usada ao enviar dados com o Nível de Compactação Ideal. Os valores permitidos são nenhum e gzip. Não
writeBatchSize Número de registros a gravar no coletor REST por lote. O valor padrão é 10000. Não

O conector REST como coletor funciona com as APIs REST que aceitam JSON. Os dados serão enviados em JSON com o padrão a seguir. Conforme necessário, você pode usar o mapeamento de esquema da atividade de cópia para remodelar os dados de origem para que estejam em conformidade com a carga esperada pela API REST.

[
    { <data object> },
    { <data object> },
    ...
]

Exemplo:

"activities":[
    {
        "name": "CopyToREST",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<REST output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "RestSink",
                "requestMethod": "POST",
                "httpRequestTimeout": "00:01:40",
                "requestInterval": 10,
                "writeBatchSize": 10000,
                "httpCompressionType": "none",
            },
        }
    }
]

Propriedades do fluxo de dados de mapeamento

Há suporte para REST em fluxos de dados de conjuntos de dado de integração e conjuntos de dados embutidos.

Transformação de origem

Propriedade Descrição Obrigatório
requestMethod O método HTTP. Valores permitidos são Obtenha e POST. Sim
relativeUrl Uma URL relativa para o recurso que contém os dados. Quando essa propriedade não é especificada, somente o URL especificado na definição de serviço vinculada é usado. O conector HTTP copia os dados da URL combinada: [URL specified in linked service]/[relative URL specified in dataset]. Não
additionalHeaders Cabeçalhos de solicitação HTTP adicionais. Não
httpRequestTimeout O tempo limite (o valor TimeSpan) para a solicitação HTTP para obter uma resposta. Esse valor é o tempo limite para obter uma resposta, não o tempo limite para gravar os dados. O valor padrão é 01:00:40. Não
requestInterval O intervalo entre diferentes solicitações em milissegundos. O valor do intervalo de solicitação deve ser um número entre [10, 60000]. Não
QueryParameters.request_query_parameter OU QueryParameters['request_query_parameter'] O "request_query_parameter" é definido pelo usuário e faz referência a um nome de parâmetro de consulta na URL da próxima solicitação HTTP. No

Transformação de coletor

Propriedade Descrição Obrigatório
additionalHeaders Cabeçalhos de solicitação HTTP adicionais. Não
httpRequestTimeout O tempo limite (o valor TimeSpan) para a solicitação HTTP para obter uma resposta. Esse valor é o tempo limite para obter uma resposta, não o tempo limite para gravar os dados. O valor padrão é 01:00:40. Não
requestInterval O intervalo entre diferentes solicitações em milissegundos. O valor do intervalo de solicitação deve ser um número entre [10, 60000]. Não
httpCompressionType Tipo de compactação HTTP a ser usada ao enviar dados com o Nível de Compactação Ideal. Os valores permitidos são nenhum e gzip. Não
writeBatchSize Número de registros a gravar no coletor REST por lote. O valor padrão é 10000. Não

Você pode definir os métodos excluir, inserir, atualizar e executar upsert, bem como os dados de linha relativos para enviar ao coletor REST para operações CRUD.

Coletor REST de fluxo de dados

Script de fluxo de dados de amostra

Observe o uso de uma transformação de alteração de linha antes do coletor instruir o Azure Data Factory sobre que tipo de ação deve ser tomada com seu coletor REST. Por exemplo, inserir, atualizar, executar upsert, excluir.

AlterRow1 sink(allowSchemaDrift: true,
	validateSchema: false,
	deletable:true,
	insertable:true,
	updateable:true,
	upsertable:true,
	rowRelativeUrl: 'periods',
	insertHttpMethod: 'PUT',
	deleteHttpMethod: 'DELETE',
	upsertHttpMethod: 'PUT',
	updateHttpMethod: 'PATCH',
	timeout: 30,
	requestFormat: ['type' -> 'json'],
	skipDuplicateMapInputs: true,
	skipDuplicateMapOutputs: true) ~> sink1

Suporte à paginação

Quando você copia os dados, a API REST normalmente limita o tamanho do conteúdo da resposta de uma única solicitação a um número razoável; por outro lado, ao retornar uma grande quantidade de dados, a API REST divide o resultado em várias páginas e requer que os chamadores enviem solicitações consecutivas para obter a próxima página do resultado. Geralmente, a solicitação para uma página é dinâmica e composta por informações retornadas da resposta de página anterior.

Esse conector genérico REST suporta os seguintes padrões de paginação:

  • URL absoluta ou relativa da próxima solicitação = valor de propriedade no corpo de resposta atual
  • Próxima solicitação de URL absoluta = valor de cabeçalho nos cabeçalhos de resposta atuais
  • Próxima solicitação de consulta de parâmetro = valor de propriedade no corpo de resposta atual
  • Próxima solicitação de consulta de parâmetro = valor de cabeçalho nos cabeçalhos de resposta atuais
  • Próxima solicitação de cabeçalho = valor de propriedade no corpo de resposta atual
  • Próxima solicitação de cabeçalho = valor de cabeçalho nos cabeçalhos de resposta atuais

As Regras de paginação são definidas como um dicionário no conjunto de dados, que contém um ou mais pares de chave-valor que diferenciam maiúsculas de minúsculas. A configuração será usada para gerar a solicitação a partir da segunda página. O conector irá interromper a iteração quando obtiver o código de status HTTP 204 (sem conteúdo) ou quando qualquer uma das expressões JSONPath em "paginationRules" retornar nula.

O Suporte para chaves nas regras de paginação:

Chave Descrição
AbsoluteUrl Indica a URL para emitir a próxima solicitação. Pode ser uma URL absoluta ou uma URL relativa.
QueryParameters.request_query_parameter OU QueryParameters['request_query_parameter'] O "request_query_parameter" é definido pelo usuário e faz referência a um nome de parâmetro de consulta na URL da próxima solicitação HTTP.
Headers.request_header OU Headers['request_header'] O "request_header" é definido pelo usuário e faz referência a um nome de parâmetro de cabeçalho da próxima solicitação HTTP.
EndCondition:end_condition "end_condition" é definido pelo usuário, que indica a condição que encerrará o loop de paginação na próxima solicitação HTTP.
MaxRequestNumber Indica o número máximo de solicitações de paginação. Deixar como vazio significa sem limite.
SupportRFC5988 Por padrão, isso será definido como true se nenhuma regra de paginação for definida. Você pode desabilitar essa regra definindo supportRFC5988 como false ou remova essa propriedade do script.

Os Valores com suporte nas regras de paginação:

Valor Descrição
Headers.response_header OU Headers['response_header'] O "response_header" é definido pelo usuário e faz referência a um nome de cabeçalho na resposta HTTP atual, valor que será usado para emitir a próxima solicitação.
Uma expressão JSONPath começando com "$" (que representa a raiz do corpo da resposta) O corpo da resposta deve conter apenas um objeto JSON e a matriz do objeto, pois o corpo da resposta não é compatível. A expressão JSONPath deve retornar um único valor primitivo, que será usado para emitir a próxima solicitação.

Observação

As regras de paginação nos fluxos de dados de mapeamento são diferentes disso na atividade de cópia nos seguintes aspectos:

  1. Não há suporte para intervalo em fluxos de dados de mapeamento.
  2. Não há suporte para [''] em fluxos de dados de mapeamento. Em vez disso, use {} para escapar de caracteres especiais. Por exemplo, body.{@odata.nextLink}, cujo nó de JSON @odata.nextLink contém o caractere especial ..
  3. A condição final tem suporte em fluxos de dados de mapeamento, mas a sintaxe de condição é diferente dela na atividade de cópia. body é usado para indicar o corpo da resposta em vez de $. header é usado para indicar o cabeçalho da resposta em vez de headers. Seguem dois exemplos que mostram essa diferença:
    • Exemplo 1:
      Atividade Copy: "EndCondition:$.data": "Empty"
      Fluxos de dados de mapeamento: "EndCondition:body.data": "Empty"
    • Exemplo 2:
      Atividade Copy: "EndCondition:headers.complete": "Exist"
      Fluxos de dados de mapeamento: "EndCondition:header.complete": "Exist"

Exemplos de regras de paginação

Esta seção fornece uma lista de exemplos para configurações de regras de paginação.

Exemplo 1: variáveis em QueryParameters

Este exemplo fornece as etapas de configuração para enviar várias solicitações cujas variáveis estão em QueryParameters.

Várias solicitações:

baseUrl/api/now/table/incident?sysparm_limit=1000&sysparm_offset=0,
baseUrl/api/now/table/incident?sysparm_limit=1000&sysparm_offset=1000,
...... 
baseUrl/api/now/table/incident?sysparm_limit=1000&sysparm_offset=10000

Etapa 1: dntrada sysparm_offset={offset} na URL base ou na URL relativa, conforme mostrado nas capturas de tela a seguir:

Captura de tela mostrando uma configuração para enviar várias solicitações cujas variáveis estão em Query Parameters.

ou

Captura de tela mostrando outra configuração para enviar várias solicitações cujas variáveis estão em Query Parameters.

Etapa 2: definir Regras de paginação como a opção 1 ou a opção 2:

  • Option1: "QueryParameters.{offset}" : "RANGE:0:10000:1000"

  • Option2: "AbsoluteUrl.{offset}" : "RANGE:0:10000:1000"

Exemplo 2: variáveis em AbsoluteUrl

Este exemplo fornece as etapas de configuração para enviar várias solicitações cujas variáveis estão em AbsoluteUrl.

Várias solicitações:

BaseUrl/api/now/table/t1
BaseUrl/api/now/table/t2
...... 
BaseUrl/api/now/table/t100

Etapa 1: entrada {id} na URL base na página de configuração de serviço vinculado ou na URL relativa no painel de conexão do conjuntos de dados.

Captura de tela mostrando uma configuração para enviar várias solicitações cujas variáveis estão em Absolute Url.

ou

Captura de tela mostrando outra configuração para enviar várias solicitações cujas variáveis estão em Absolute Url.

Etapa 2: definir Regras de paginação como "AbsoluteUrl.{id}" :"RANGE:1:100:1".

Exemplo 3: variáveis em Headers

Este exemplo fornece as etapas de configuração para enviar várias solicitações cujas variáveis estão em Headers.

Várias solicitações:
RequestUrl: https://example/table
Solicitação 1: Header(id->0)
Solicitação 2: Header(id->10)
......
Solicitação 100: Header(id->100)

Etapa 1: entrada {id} em Cabeçalhos adicionais.

Etapa 2: definir Regras de paginação como "Headers.{id}" : "RANGE:0:100:10".

Captura de tela mostrando a regra de paginação para enviar várias solicitações cujas variáveis estão em Headers.

Exemplo 4: as variáveis estão em AbsoluteUrl/QueryParameters/Headers, a variável final não é predefinida e a condição de término é baseada na resposta

Este exemplo fornece etapas de configuração para enviar várias solicitações cujas variáveis estejam em AbsoluteUrl/QueryParameters/Headers, mas a variável final não esteja definida. Para respostas diferentes, diferentes configurações de regra de condição final são mostradas no Exemplo 4.1-4.6.

Várias solicitações:

Request 1: baseUrl/api/now/table/incident?sysparm_limit=1000&sysparm_offset=0, 
Request 2: baseUrl/api/now/table/incident?sysparm_limit=1000&sysparm_offset=1000,
Request 3: baseUrl/api/now/table/incident?sysparm_limit=1000&sysparm_offset=2000,
......

Duas respostas encontradas neste exemplo:

Resposta 1：

{
    Data: [
        {key1: val1, key2: val2
        },
        {key1: val3, key2: val4
        }
    ]
}

Resposta 2：

{
    Data: [
        {key1: val5, key2: val6
        },
        {key1: val7, key2: val8
        }
    ]
}

Etapa 1: definir o intervalo de Regras de paginação como Exemplo 1 e deixar o final do intervalo vazio como "AbsoluteUrl.{offset}": "RANGE:0::1000".

Etapa 2: definir regras de condição de término diferentes de acordo com as últimas respostas diferentes. Veja os exemplos a seguir:

  • Exemplo 4.1: a paginação termina quando o valor do nó específico em resposta está vazio

    A API REST retorna a última resposta na seguinte estrutura:

    {
    Data: []
}

    Definir a regra de condição final como "EndCondition:$.data": "Empty" para encerrar a paginação quando o valor do nó específico em resposta estiver vazio.

    Captura de tela mostrando a definição da condição final para o Exemplo 4.1.

  • Exemplo 4.2: a paginação termina quando o valor do nó específico em resposta não existir

    A API REST retorna a última resposta na seguinte estrutura:

    {}

    Definir a regra de condição final como "EndCondition:$.data": "NonExist" para encerrar a paginação quando o valor do nó específico em resposta não existir.

    Captura de tela mostrando a definição da condição final para o Exemplo 4.2.

  • Exemplo 4.3: a paginação termina quando o valor do nó específico em resposta existe

    A API REST retorna a última resposta na seguinte estrutura:

    {
    Data: [
        {key1: val991, key2: val992
        },
        {key1: val993, key2: val994
        }
    ],
            Complete: true
}

    Definir a regra de condição final como "EndCondition:$.Complete": "Exist" para encerrar a paginação quando o valor do nó específico em resposta existir.

    Captura de tela mostrando a definição da condição final para o Exemplo 4.3.

  • Exemplo 4.4: a paginação termina quando o valor do nó específico em resposta for um valor const definido pelo usuário

    A API REST retorna a resposta na seguinte estrutura:

    {
    Data: [
        {key1: val1, key2: val2
        },
        {key1: val3, key2: val4
        }
    ],
            Complete: false
}

    ......

    E a última resposta está na seguinte estrutura:

    {
    Data: [
        {key1: val991, key2: val992
        },
        {key1: val993, key2: val994
        }
    ],
            Complete: true
}

    Definir a regra de condição final como "EndCondition:$.Complete": "Const:true" para encerrar a paginação quando o valor do nó específico em resposta for um valor const definido pelo usuário.

    Captura de tela mostrando a definição da condição final para o Exemplo 4.4.

  • Exemplo 4.5: a paginação termina quando o valor da chave do cabeçalho em resposta for igual a um valor const definido pelo usuário

    As chaves de cabeçalho nas respostas da API REST são mostradas na estrutura abaixo:

    Cabeçalho de resposta 1: header(Complete->0)
    ......
    Último cabeçalho de resposta: header(Complete->1)

    Definir a regra de condição final como "EndCondition:headers.Complete": "Const:1" para encerrar a paginação quando o valor da chave do cabeçalho em resposta for igual a um valor const definido pelo usuário.

    Captura de tela mostrando a definição da condição final para o Exemplo 4.5.

  • Exemplo 4.6: a paginação termina quando a chave existir no cabeçalho de resposta

    As chaves de cabeçalho nas respostas da API REST são mostradas na estrutura abaixo:

    Cabeçalho de resposta 1: header()
    ......
    Último cabeçalho de resposta: header(CompleteTime->20220920)

    Defina a regra de condição final como "EndCondition:headers.completeTime": "Exist" para encerrar a paginação quando a chave existir no cabeçalho de resposta.

    Captura de tela mostrando a definição da condição final para o Exemplo 4.6.

Exemplo 5: definir a condição de término para evitar solicitações infinitas quando a regra de intervalo não estiver definida

Este exemplo fornece as etapas de configuração para enviar várias solicitações quando a regra de intervalo não for usada. A condição final pode ser definida. Consulte o exemplo 4.1-4.6 para evitar solicitações infinitas. A API REST retorna a resposta na próxima estrutura, em cada casa a URL da próxima página é representada por paging.next.

{
    "data": [
        {
            "created_time": "2017-12-12T14:12:20+0000",
            "name": "album1",
            "id": "1809938745705498_1809939942372045"
        },
        {
            "created_time": "2017-12-12T14:14:03+0000",
            "name": "album2",
            "id": "1809938745705498_1809941802371859"
        },
        {
            "created_time": "2017-12-12T14:14:11+0000",
            "name": "album3",
            "id": "1809938745705498_1809941879038518"
        }
    ],
    "paging": {
        "cursors": {
            "after": "MTAxNTExOTQ1MjAwNzI5NDE=",
            "before": "NDMyNzQyODI3OTQw"
        },
        "previous": "https://graph.facebook.com/me/albums?limit=25&before=NDMyNzQyODI3OTQw",
        "next": "https://graph.facebook.com/me/albums?limit=25&after=MTAxNTExOTQ1MjAwNzI5NDE="
    }
}
...

A última resposta é:

{
    "data": [],
    "paging": {
        "cursors": {
            "after": "MTAxNTExOTQ1MjAwNzI5NDE=",
            "before": "NDMyNzQyODI3OTQw"
        },
        "previous": "https://graph.facebook.com/me/albums?limit=25&before=NDMyNzQyODI3OTQw",
        "next": "Same with Last Request URL"
    }
}

Etapa 1: definir Regras de paginação como "AbsoluteUrl": "$.paging.next".

Etapa 2: se next na última resposta for sempre o mesmo com a última URL de solicitação e não estiver vazia, solicitações infinitas serão enviadas. A condição final pode ser usada para evitar solicitações infinitas. Portanto, defina a regra de condição final. Consulte o exemplo 4.1-4.6.

Exemplo 6: definir o número máximo de solicitações para evitar solicitações infinitas

Defina MaxRequestNumber para evitar solicitações infinitas, conforme mostrado na seguinte captura de tela:

Captura de tela mostrando a definição de número máximo de solicitações para o Exemplo 6.

Exemplo 7: a regra de paginação RFC 5988 tem suporte por padrão

O back-end receberá automaticamente a próxima URL com base nos links de estilo RFC 5988 no cabeçalho.

Captura de tela mostrando exemplos do cabeçalho http que compõe o R F C 5988.

Dica

Se não quiser habilitar essa regra de paginação padrão, você poderá definir supportRFC5988 como false ou apenas excluí-lo no script.

Captura de tela mostrando como desativar a definição de R F C 5988 para o Exemplo 7.

Exemplo 8: a próxima URL de solicitação é do corpo da resposta ao usar a paginação no fluxo de dados de mapeamento

Este exemplo informa como definir a regra de paginação e a regra de condição final no fluxo de dados de mapeamento quando a próxima URL de solicitação for do corpo da resposta.

O esquema de resposta é mostrado abaixo:

Captura de tela mostrando o esquema de resposta do Exemplo 8.

As regras de paginação devem ser definidas como a captura de tela a seguir:

Captura de tela mostrando como definir a regra de paginação para o Exemplo 8.

Por padrão, a paginação irá parar quando body.{@odata.nextLink}** for nulo ou estiver vazio.

Mas se o valor de @odata.nextLink no corpo da última resposta for igual à última URL de solicitação, ele levará ao loop infinito. Para evitar essa condição, defina regras de condição final.

  • Se o Valor na última resposta estiver Vazio, a regra de condição final poderá ser definida como abaixo:

    Captura de tela mostrando a definição da regra de condição final quando a última resposta é vazia.

  • Se o valor da chave completa no cabeçalho de resposta for igual a true, isto indica o final da paginação e, em seguida, a regra de condição final poderá ser definida como abaixo:

    Captura de tela mostrando a definição da regra de condição final a chave completa no cabeçalho de resposta for igual a true, isto indica o final da paginação.

Exemplo 9: o formato da resposta é XML e a próxima URL de solicitação é do corpo da resposta ao usar a paginação no fluxo de dados de mapeamento

Este exemplo informa como definir a regra de paginação nos fluxos de dados de mapeamento quando o formato da resposta for XML e a próxima URL de solicitação for do corpo da resposta. Conforme mostrado na captura de tela a seguir, o primeiro URL é https://<user>.dfs.core.windows.NET/bugfix/test/movie_1.xml

Captura de tela mostrando que o formato de resposta é X M L e a próxima U R L de solicitação é do corpo de resposta.

O esquema de resposta é mostrado abaixo:

Captura de tela mostrando o esquema de resposta do Exemplo 9.

A sintaxe da regra de paginação é a mesma do exemplo 8 e deve ser definida como abaixo neste exemplo:

Captura de tela mostrando a definção da regra de paginação para o Exemplo 9.

Exportar a resposta JSON como ela aparece

Você pode usar esse conector REST para exportar a resposta JSON de API REST como ela aparece para vários armazenamentos baseados em arquivo. Para efetuar essa cópia independente de esquema, ignore a seção da "estrutura" (também chamada de esquema) no conjunto de dados e mapeamento de esquema na atividade de cópia.

Mapeamento de esquema

Para copiar dados do ponto de extremidade REST para o coletor de tabela, confira o mapeamento do esquema.

Conteúdo relacionado

Para obter uma lista de armazenamentos de dados que o Copy Activity suporta como fontes e coletores no Azure Data Factory, consulte Armazenamentos e formatos de dados compatíveis.