Compartilhar 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

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 pipeline do Azure Data Factory e do Azure Synapse para copiar dados de/para a lista do SharePoint Online. O artigo se baseia na Atividade de Cópia, que apresenta uma visão geral da Atividade de Cópia.

Funcionalidades com suporte

Este conector da Lista do SharePoint Online é compatível com as seguintes funcionalidades:

Funcionalidades com suporte IR
Atividade de cópia (origem/-) ① ②
Atividade de pesquisa ① ②

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

Para obter uma lista de armazenamentos de dados com suporte como origens ou coletores, confira a tabela Armazenamentos de dados com suporte.

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

Dica

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

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 para uma lista do SharePoint Online usando a interface do usuário

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

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

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

    Captura de tela do conector 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 da configuração do conector

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

Propriedades do serviço vinculado

As seguintes propriedades são compatíveis com o serviço vinculado da Lista do SharePoint Online:

Propriedade Descrição Necessário
type A propriedade type precisa ser definida para: 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 usada para autenticação da entidade de serviço. Os valores permitidos são ServicePrincipalCert e ServicePrincipalKey. 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. Você precisa definir as configurações de permissão referentes a este artigo. 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
Para ServicePrincipalKey
servicePrincipalKey A chave do aplicativo. Marque esse campo como SecureString para armazená-lo com segurança ou referencie um segredo armazenado no Azure Key Vault. Consulte essa seção para obter mais detalhes, incluindo as configurações de permissão. Não
tenantId O ID do locatário em que o aplicativo reside. Sim
connectVia O runtime de integração a ser usado para se conectar ao armazenamento de dados. Se não especificado, o Azure Integration Runtime padrão será usado. Não

Observação

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

Exemplo 1: Usando autenticação de chave principal 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 autenticação de certificado de 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 do serviço

Esse 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. Registrar um aplicativo na plataforma de identidade da Microsoft. Para saber como, confira Início Rápido: registrar um aplicativo na plataforma de identidade da Microsoft. Anote estes valores; ele são usados para definir o serviço vinculado:

    • ID do aplicativo
    • Chave do aplicativo
    • ID do locatário

  2. Conceda permissão de site do SharePoint Online para o 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> é o seu site.

    2. Pesquise a ID do aplicativo que você registrou, 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 para o aplicativo registrado quando tiver a função de administrador do site.

      Observação

      No contexto da configuração do conector do SharePoint, "Domínio do Aplicativo" e "URL de Redirecionamento" referem-se ao aplicativo do SharePoint que você registrou no Microsoft Entra ID para permitir o acesso aos dados do SharePoint. O "Domínio do Aplicativo" é o domínio onde o site do SharePoint está hospedado. Por exemplo, se o 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 será redirecionado depois que o usuário autenticar e conceder permissões ao aplicativo. Essa URL deve ser uma página no site do SharePoint que o aplicativo tem 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 de uma página que exibe o conteúdo de um documento.

    3. Clique em “Confie” para este aplicativo.

Propriedades do conjunto de dados

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. A seção a seguir fornece uma lista das propriedades compatíveis pelo conjunto de dados da tabela do SAP.

Propriedade Descrição Obrigatório
type A propriedade tipo 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>"
        }
    }
}

Propriedades da Atividade de Cópia

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

Lista do SharePoint Online como origem

Para a cópia de dados da Lista do SharePoint Online, as propriedades a seguir na seção de origem da Atividade de Cópia são compatíveis:

Propriedade Descrição Obrigatório
type A propriedade tipo da origem da Atividade de Cópia deve ser definida como SharePointOnlineListSource. Sim
Consulta Opções personalizadas de consulta do OData para filtrar dados. Exemplo: "$top=10&$select=Title,Number". Não
httpRequestTimeout O tempo limite (em segundos) 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>"
            }
        }
    }
]

Observação

Não é possível selecionar mais de uma opção em escolher tipos de dados para uma origem da Lista do SharePoint Online.

Mapeamento do tipo de dados para a Lista do SharePoint Online

Ao copiar 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 do OData Tipo de dados provisórios
Linha única 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 Double
Moeda ($, ¥, €) Edm.Double Double
Data e hora Edm.DateTime Datetime
Pesquisa (informações já presentes nesse site) Edm.Int32 Int32
Sim/Não (caixa de seleção) Edm.Boolean Boolean
Pessoa ou Grupo Edm.Int32 Int32
Hiperlink ou Imagem Edm.String String
Calculado (cálculo baseado em outras colunas) Edm.String/Edm.Double/Edm.DateTime/Edm.Boolean String/Double/DateTime/Boolean
Anexo Sem suporte
Resultado da tarefa Sem suporte
Dados externos Sem suporte
Metadados gerenciado Sem suporte

Copiar arquivo do SharePoint Online

Você pode copiar o arquivo do SharePoint Online usando atividade da Web para autenticar e obter o token de acesso do SPO, passando 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 do serviço para criar o aplicativo Microsoft Entra e conceder permissão ao SharePoint Online.

  2. Crie um Atividades da Web para obter o token de acesso do SharePoint Online:

    • URL: https://accounts.accesscontrol.windows.net/[Tenant-ID]/tokens/OAuth/2. Substitua a 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).

    Cuidado

    Defina a opção Saída segura como verdadeira na atividade da Web para impedir que o valor do token seja registrado em texto sem formatação. Qualquer outra atividade que consumir esse valor deve ter a opção de Entrada segura definida como verdadeira.

  3. Cadeia com uma Atividade de cópia com o 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 SharePoint site URL 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 origem da atividade de cópia posteriormente)
    • Conjunto de dados: escolha o formato desejado. Para copiar o arquivo como ele está, selecione o tipo “Binário”.
    • Origem da atividade de cópia:
      • Método de solicitação: GET
      • Cabeçalho adicional: use a expressão a seguir@{concat('Authorization: Bearer ', activity('<Web-activity-name>').output.access_token)}, que usa o token de Portador 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 com suporte.

Observação

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

Pesquisar propriedades de atividade

Para saber detalhes sobre as propriedades, verifique Pesquisar atividade.

Conteúdo relacionado

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