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

Artigo
01/05/2024

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/-)	6/6
Atividade de pesquisa	6/6

① 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.

Pré-requisitos

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:

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
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, https://[your_site_url]/_layouts/15/appinv.aspx (substitua a URL do 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>
```
  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.

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.

Navegue até a guia Gerenciar no workspace do Azure Data Factory ou do Synapse, selecione Serviços Vinculados e clique em Novo:
- Azure Data Factory
- Azure Synapse
Procure SharePoint e selecione o conector Lista do SharePoint Online.
Configure os detalhes do serviço, teste a conexão e crie o novo serviço vinculado.

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. Veja Pré-requisitos para obter mais detalhes, incluindo as configurações de permissão.	Sim
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.	Sim
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

Exemplo:

{
    "name": "SharePointOnlineList",
    "properties": {
        "type": "SharePointOnlineList",
        "typeProperties": {
            "siteUrl": "<site URL>",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalKey": {
                "type": "SecureString",
                "value": "<service principal key>"
            },
            "tenantId": "<tenant ID>"
        }
    }
}

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.

sharepoint copy file flow

Siga a seção de Pré-requisitos para criar o aplicativo do Microsoft Entra e conceder permissão ao SharePoint Online.
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.
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 atividades de cópia como de costume.