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

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

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:

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

Introdução

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

• A ferramenta Copiar Dados
• O portal do Azure
• O SDK do .NET
• O SDK do Python
• PowerShell do Azure
• A API REST
• O modelo do Azure Resource Manager

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:

   • Azure Data Factory
   • Azure Synapse

   

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

   

3. 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:

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>
        

        

      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.

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:

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>"
            }
        }
    }
]

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.

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.

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.

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.