Partilhar via

Copiar dados da Lista do SharePoint Online usando o Azure Data Factory ou o Azure Synapse Analytics

  • Artigo

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Gorjeta

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

Este artigo descreve como usar a Atividade de Cópia no Azure Data Factory e nos pipelines do Azure Synapse para copiar dados da Lista do SharePoint Online. O artigo baseia-se na Atividade de Cópia, que apresenta uma visão geral da Atividade de Cópia.

Capacidades suportadas

Este conector de Lista do SharePoint Online é suportado para os seguintes recursos:

Capacidades suportadas IR
Atividade de cópia (fonte/-) (1) (2)
Atividade de Pesquisa (1) (2)

(1) Tempo de execução de integração do Azure (2) Tempo de execução de integração auto-hospedado

Para obter uma lista de armazenamentos de dados suportados como fontes ou coletores, consulte a tabela Armazenamentos de dados suportados.

Especificamente, esse conector da Lista Online do SharePoint usa a autenticação da entidade de serviço e recupera dados por meio do protocolo OData.

Gorjeta

Este conector suporta a cópia de dados da Lista do SharePoint Online, mas não de ficheiros. Saiba como copiar arquivo da seção Copiar arquivo do SharePoint Online .

Começar agora

Para executar a atividade Copiar com um pipeline, você pode usar uma das seguintes ferramentas ou SDKs:

Criar um serviço vinculado a uma Lista do SharePoint Online usando a interface do usuário

Use as etapas a seguir para criar um serviço vinculado a uma Lista do SharePoint Online na interface do usuário do portal do Azure.

  1. Navegue até a guia Gerenciar em seu espaço de trabalho do Azure Data Factory ou Synapse e selecione Serviços Vinculados e clique em Novo:

  2. Procure o SharePoint e selecione o conector de Lista do SharePoint Online.

    Captura de ecrã do conector de Lista do SharePoint Online.

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

    Captura de tela da configuração do serviço vinculado para uma Lista do SharePoint Online.

Detalhes de configuração do conector

As seções a seguir fornecem detalhes sobre as propriedades que você pode usar para definir entidades que são específicas para o conector de Lista do SharePoint Online.

Propriedades do serviço vinculado

As seguintes propriedades são suportadas para um serviço vinculado de Lista do SharePoint Online:

Propriedade Descrição Obrigatório
tipo A propriedade type deve ser definida como: SharePointOnlineList. Sim
siteUrl A URL do site do SharePoint Online, por exemplo. https://contoso.sharepoint.com/sites/siteName Sim
servicePrincipalId A ID do aplicativo (cliente) do aplicativo registrado no Microsoft Entra ID. Sim
servicePrincipalCredentialType Especifique o tipo de credencial a ser usado para autenticação da entidade de serviço. Os valores permitidos são ServicePrincipalCert e ServicePrincipalKey. Não
Para ServicePrincipalCert
serviçoPrincipalEmbeddedCert Especifique o certificado codificado base64 do seu aplicativo registrado no Microsoft Entra ID e verifique se o tipo de conteúdo do certificado é PKCS #12. Marque este campo como um SecureString para armazená-lo com segurança ou faça referência a um segredo armazenado no Cofre de Chaves do Azure. Você precisa definir as configurações de permissão referentes a este artigo. Não
servicePrincipalEmbeddedCertPassword Especifique a senha do seu certificado se ele estiver protegido com uma senha. Marque este campo como um SecureString para armazená-lo com segurança ou faça referência a um segredo armazenado no Cofre de Chaves do Azure. Não
Para ServicePrincipalKey
servicePrincipalKey A chave do aplicativo. Marque este campo como um SecureString para armazená-lo com segurança ou faça referência a um segredo armazenado no Cofre de Chaves do Azure. Consulte esta seção para obter mais detalhes, incluindo as configurações de permissão. Não
tenantId O ID do locatário sob o qual seu aplicativo reside. Sim
ConecteVia O tempo de execução de integração a ser usado para se conectar ao armazenamento de dados. Se não for especificado, o Tempo de Execução de Integração do Azure padrão será usado. Não

Nota

Se você estiver usando a autenticação de chave da entidade de serviço, que é baseada no Azure ACS (Serviços de Controle de Acesso), recomendamos alternar para a autenticação de certificado da entidade de serviço devido ao plano de aposentadoria do ACS.

Exemplo 1: Usando a autenticação de chave da entidade de serviço

{
    "name": "SharePointOnlineList",
    "properties": {
        "type": "SharePointOnlineList",
        "typeProperties": {
            "siteUrl": "<site URL>",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalCredentialType":  "ServicePrincipalKey",
            "servicePrincipalKey": {
                "type": "SecureString",
                "value": "<service principal key>"
            },
            "tenantId": "<tenant ID>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

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

{
    "name": "SharePointOnlineList",
    "properties": {
        "type": "SharePointOnlineList",
        "typeProperties": {
            "siteUrl": "<site URL>",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalCredentialType": "ServicePrincipalCert",
            "servicePrincipalEmbeddedCert": { 
                "type": "SecureString", 
                "value": "<base64 encoded string of (.pfx) certificate data>"
            },
            "servicePrincipalEmbeddedCertPassword": { 
                "type": "SecureString", 
                "value": "<password of your certificate>"
            },
            "tenantId": "<tenant ID>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Conceder permissão para usar a chave principal de serviço

O conector da Lista do SharePoint Online usa a autenticação da entidade de serviço para se conectar ao SharePoint. Siga estas etapas para configurá-lo:

  1. Registre um aplicativo com a plataforma de identidade da Microsoft. Para saber como, consulte Guia de início rápido: registrar um aplicativo com a plataforma de identidade da Microsoft. Anote estes valores, que você usa para definir o serviço vinculado:

    • ID da aplicação
    • Chave de aplicação
    • ID de Inquilino do

  2. Conceda permissão de site do SharePoint Online para seu aplicativo registrado seguindo as etapas abaixo. Para fazer isso, você precisa de uma função de administrador do site.

    1. Abra o link do site do SharePoint Online. Por exemplo, a URL no formato https://<your-site-url>/_layouts/15/appinv.aspx em que o espaço reservado <your-site-url> é seu site.

    2. Pesquise o ID do aplicativo que você cadastrou, preencha os campos vazios e clique em "Criar".

      • Domínio do aplicativo: contoso.com

      • URL de redirecionamento: https://www.contoso.com

      • XML de solicitação de permissão:

        <AppPermissionRequests AllowAppOnlyPolicy="true">
    <AppPermissionRequest Scope="http://sharepoint/content/sitecollection/web" Right="Read"/>
</AppPermissionRequests>

        Conceda permissão de site do SharePoint Online ao seu aplicativo registrado quando tiver a função de administrador do site.

      Nota

      No contexto da configuração do conector do SharePoint, o "Domínio do aplicativo" e a "URL de redirecionamento" referem-se ao aplicativo do SharePoint que você registrou no Microsoft Entra ID para permitir o acesso aos seus dados do SharePoint. O "Domínio do aplicativo" é o domínio onde seu site do SharePoint está hospedado. Por exemplo, se o seu site do SharePoint estiver localizado em "https://contoso.sharepoint.com", o "Domínio do aplicativo" será "contoso.sharepoint.com". A "URL de redirecionamento" é a URL para a qual o aplicativo do SharePoint redirecionará depois que o usuário tiver autenticado e concedido permissões para o aplicativo. Essa URL deve ser uma página em seu site do SharePoint que o aplicativo tenha permissão para acessar. Por exemplo, você pode usar a URL de uma página que exibe uma lista de arquivos em uma biblioteca ou uma página que exibe o conteúdo de um documento.

    3. Clique em "Confiar" para este aplicativo.

Propriedades do conjunto de dados

Para obter uma lista completa de seções e propriedades disponíveis para definir conjuntos de dados, consulte Conjuntos de dados e serviços vinculados. A seção a seguir fornece uma lista das propriedades suportadas pelo conjunto de dados da tabela SAP.

Property Descrição Obrigatório
tipo A propriedade type do conjunto de dados deve ser definida como SharePointOnlineLResource. Sim
listName O nome da Lista do SharePoint Online. Observe que o apóstrofo (') não é permitido em nomes de arquivo. Sim

Exemplo

{
    "name": "SharePointOnlineListDataset",
    "properties":
    {
        "type": "SharePointOnlineListResource",
        "linkedServiceName": {
            "referenceName": "<SharePoint Online List linked service name>",
            "type": "LinkedServiceReference"
        },
        "typeProperties":
        {
            "listName": "<name of the list>"
        }
    }
}

Copiar propriedades da atividade

Para obter uma lista completa de seções e propriedades disponíveis para definir atividades, consulte Pipelines. A seção a seguir fornece uma lista das propriedades suportadas pela fonte da Lista do SharePoint Online.

Lista do SharePoint Online como origem

Para copiar dados da Lista do SharePoint Online, as seguintes propriedades são suportadas na seção Copiar fonte de atividade:

Property Descrição Obrigatório
tipo A propriedade type da fonte Copy Activity deve ser definida como SharePointOnlineListSource. Sim
query Opções de consulta OData personalizadas para filtrar dados. Exemplo: "$top=10&$select=Title,Number". Não
httpRequestTimeout O tempo limite (em segundo) para a solicitação HTTP obter uma resposta. O padrão é 300 (5 minutos). Não

Exemplo

"activities":[
    {
        "name": "CopyFromSharePointOnlineList",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<SharePoint Online List input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "SharePointOnlineListSource",
                "query": "<OData query e.g. $top=10&$select=Title,Number>"
            }, 
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Nota

Não é possível selecionar mais de um tipo de dados de escolha para uma fonte de Lista do SharePoint Online.

Mapeamento de tipo de dados para Lista do SharePoint Online

Quando você copia dados da Lista do SharePoint Online, os mapeamentos a seguir são usados entre os tipos de dados da Lista do SharePoint Online e os tipos de dados provisórios usados pelo serviço internamente.

Tipo de dados do SharePoint Online Tipo de dados OData Tipo de dados provisórios
Uma linha de texto Edm.String String
Várias linhas de texto Edm.String String
Escolha (menu para escolher) Edm.String String
Número (1, 1.0, 100) Edm.Double Duplo
Moeda ($, ¥, €) Edm.Double Duplo
Data e Hora Edm.DateTime DateTime
Procura (informação que já se encontra neste site) Edm.Int32 Int32
Sim/Não (caixa de verificação) Edm.Boolean Boolean
Pessoa ou Grupo Edm.Int32 Int32
Hiperligação ou Imagem Edm.String String
Calculado (cálculo com base noutras colunas) Edm.String / Edm.Double / Edm.DateTime / Edm.Boolean Corda / Duplo / DateTime / Booleano
Anexo Não suportado
Resultado da Tarefa Não suportado
Dados Externos Não suportado
Metadados Geridos Não suportado

Copiar arquivo do SharePoint Online

Você pode copiar arquivo do SharePoint Online usando a atividade da Web para autenticar e pegar o token de acesso do SPO e, em seguida, passar para a atividade de cópia subsequente para copiar dados com o conector HTTP como origem.

Fluxo de arquivos de cópia do SharePoint

  1. Siga a seção Conceder permissão para usar a chave principal de serviço para criar o aplicativo Microsoft Entra e conceder permissão ao SharePoint Online.

  2. Crie uma Atividade da Web para obter o token de acesso do SharePoint Online:

    • https://accounts.accesscontrol.windows.net/[Tenant-ID]/tokens/OAuth/2URL: . Substitua o ID do locatário.
    • Método: POST
    • Cabeçalhos:
      • Tipo de conteúdo: application/x-www-form-urlencoded
    • Corpo: grant_type=client_credentials&client_id=[Client-ID]@[Tenant-ID]&client_secret=[Client-Secret]&resource=00000003-0000-0ff1-ce00-000000000000/[Tenant-Name].sharepoint.com@[Tenant-ID]. Substitua a ID do cliente (ID do aplicativo), o segredo do cliente (chave do aplicativo), a ID do locatário e o nome do locatário (do locatário do SharePoint).

    Atenção

    Defina a opção Saída segura como true na atividade da Web para impedir que o valor do token seja registrado em texto sem formatação. Quaisquer outras atividades que consumam esse valor devem ter sua opção de entrada segura definida como true.

  3. Encadear com uma atividade de cópia com conector HTTP como origem para copiar o conteúdo do arquivo do SharePoint Online:

    • Serviço vinculado HTTP:
      • URL base: https://[site-url]/_api/web/GetFileByServerRelativeUrl('[relative-path-to-file]')/$value. Substitua a URL do site e o caminho relativo para o arquivo. Certifique-se de incluir a URL do site do SharePoint junto com o nome de domínio, como https://[sharepoint-domain-name].sharepoint.com/sites/[sharepoint-site]/_api/web/GetFileByServerRelativeUrl('/sites/[sharepoint-site]/[relative-path-to-file]')/$value.
      • Tipo de autenticação: Anônimo (para usar o token de portador configurado na fonte de atividade de cópia mais tarde)
    • Conjunto de dados: escolha o formato desejado. Para copiar o arquivo no estado em que se encontra, selecione o tipo "Binário".
    • Copiar fonte da atividade:
      • Método de solicitação: GET
      • Cabeçalho adicional: use a seguinte expressão@{concat('Authorization: Bearer ', activity('<Web-activity-name>').output.access_token)}, que usa o token Bearer gerado pela atividade da Web upstream como cabeçalho de autorização. Substitua o nome da atividade da Web.
    • Configure o coletor de atividade de cópia para qualquer destino de coletor suportado.

Nota

Mesmo que um aplicativo do Microsoft Entra tenha FullControl permissões no SharePoint Online, você não poderá copiar arquivos de bibliotecas de documentos com o IRM habilitado.

Propriedades da atividade de pesquisa

Para saber detalhes sobre as propriedades, verifique Atividade de pesquisa.

Conteúdos relacionados

Para obter uma lista de armazenamentos de dados que a Atividade de Cópia suporta como fontes e coletores, consulte Formatos e armazenamentos de dados suportados.