Importar dados organizacionais com a importação baseada em API (primeira importação) (pré-visualização)

Os dados organizacionais podem aparecer na aplicação Web Viva Insights de uma de três formas: através de Microsoft Entra ID, que é a origem predefinida; através de ficheiros individuais .csv que o utilizador, enquanto Administrador de Informações, carrega diretamente para o Viva Insights; ou através de uma importação de dados baseada em API que o utilizador, o administrador do sistema de origem e a configuração do administrador de TI do Microsoft 365.

Este artigo aborda a terceira opção de importação de dados.

Com uma importação, pode transferir dados do seu sistema de origem para a API de entrada de dados de RH do Viva Insights através de um ficheiro zip. Você pode:

• Crie uma aplicação personalizada para exportar dados do sistema de origem para um ficheiro zip. Em seguida, com a mesma aplicação, importe esses dados com as informações da API abaixo.
• Crie uma aplicação personalizada para exportar dados do sistema de origem para um ficheiro zip. Em seguida, execute uma aplicação de consola C# que criámos para importar dados para o Viva Insights.
• Crie uma aplicação personalizada para exportar dados do sistema de origem para um ficheiro zip. Em seguida, execute um script do PowerShell que criámos para importar dados para o Viva Insights.
• Utilize o nosso modelo de Azure Data Factory (ADF) para enviar dados para a nossa importação baseada em API.

No entanto, antes de poder executar a sua aplicação e começar a transferir dados para o Viva Insights, tem de coordenar algumas tarefas entre o administrador do Microsoft 365 e o Administrador de Informações (administrador do Insights). Veja Fluxo de trabalho para obter uma descrição geral dos passos necessários.

Fluxo de trabalho

1. Configuração:

   1. O administrador da origem de dados gera um certificado de segurança e fornece-o ao administrador do Microsoft 365.
   2. Com o certificado de segurança, o administrador do Microsoft 365 regista uma nova aplicação no Azure.
   3. Com os IDs do registo de aplicações, o administrador do Insights configura a importação.
   4. O administrador da origem de dados prepara os respetivos dados e:
      1. Exporta-o do sistema de origem através de uma aplicação personalizada com base na nossa API e, em seguida, através da mesma aplicação, importa os dados para o Viva Insights.
      2. Exporta-o do sistema de origem deles com uma aplicação personalizada com base na nossa API e, em seguida, através da nossa solução C# ou do script do PowerShell, importa os dados para o Viva Insights.

   

2. Validação: o Viva Insights valida os seus dados. (Se a validação não for bem-sucedida, pode escolher entre algumas opções descritas em Falha de validação.)

3. Processamento: o Viva Insights processa os seus dados. (Se o processamento não for bem-sucedido, pode escolher entre algumas opções descritas em Falha no processamento.)

Depois de os dados validarem e processarem com êxito, a tarefa global de importação de dados é concluída.

Configurar

Gerar o certificado de segurança

Aplica-se a: administrador da origem de dados

Para começar a obter dados do seu ficheiro de origem no Viva Insights, o administrador do Microsoft 365 tem de criar e registar uma aplicação no Azure. Enquanto administrador da origem de dados, tem de ajudar o administrador do Microsoft 365 a registar a aplicação ao fornecer-lhe um certificado de segurança.

Eis o que fazer:

1. Crie um certificado ao seguir as instruções neste artigo: Criar um certificado público autoassinado para autenticar a sua aplicação
2. Envie o certificado gerado para o administrador do Microsoft 365.

É tudo por agora. Se quiser começar os passos seguintes, siga os passos em Exportar os dados com uma frequência definida.

Registar uma nova aplicação no Azure

Aplica-se a: Administrador do Microsoft 365

1. No painel esquerdo do centro de administração da Microsoft, selecione Todos os centros de administração. Esta opção é apresentada como a última na lista.

   

2. Selecione Microsoft Entra ID.

3. Criar um novo registo de aplicação:

   1. Na barra de ferramentas superior, selecione Adicionar > Registo de aplicações.

      

   2. No ecrã resultante:

      1. Dê um nome à sua aplicação.
      2. Em Tipos de conta suportados, deixe a primeira opção , Contas apenas neste diretório organizacional ([A sua organização] apenas - Inquilino único), selecionada.
      3. Selecione o botão Registar na parte inferior do ecrã.

      

   3. Quando regressar ao ecrã Descrição geral, copie o ID da Aplicação (cliente) e o ID do Diretório (inquilino).

      

      Importante

      Mantenha estes IDs à mão. Terá de os fornecer mais tarde.

4. Adicionar um certificado:

   1. Selecione Adicionar um certificado ou segredo.

      

   2. Selecione Carregar certificado.

      

   3. Carregue o certificado que o administrador da origem de dados lhe deu e adicione uma Descrição. Selecione o botão Adicionar.

      

5. Remover permissões de API:

   1. Selecione Permissões de API no trilho esquerdo.

   2. Para cada nome de API/Permissões listado, selecione as reticências (...) à direita da API, por exemplo, Microsoft Graph.

   3. Selecione Remover permissão.

      

   4. Confirme a remoção.

   Quando remove permissões para estes itens, está a certificar-se de que a aplicação só tem permissões para o que precisa.

6. Partilhe os IDs que anotou no passo 3c:

   1. Dê ao administrador do Insights o ID da aplicação.
   2. Dê ao administrador da origem de dados o ID da aplicação e o ID do inquilino.

Configurar a importação no Viva Insights

Aplica-se a: Administrador de informações

1. Inicie a importação a partir de um de dois locais: a página Hub de dados ou a página Dados organizacionais , em Ligações de dados.

   1. A partir do Data Hub:

      1. Na secção Origem de dados , localize a opção de importação baseada em API . Selecione o botão Iniciar.

   2. A partir de Ligações de dados:

      1. Junto a Origem atual, selecione o botão origens de dados .

      2. É apresentada uma janela Mudar para: importação baseada em API . Selecione Iniciar.

2. Na página de importação de dados organizacionais baseados em API :

   1. Atribua um nome à sua ligação.

   2. Introduza o ID da aplicação que o seu administrador do Microsoft 365 lhe forneceu.

   3. Salvar.

3. Selecione a ligação que nomeou no passo 3a como a nova origem de dados.

4. Contacte o administrador da origem de dados e peça que envie dados da organização para o Viva Insights.

Preparar, exportar e importar dados organizacionais

Sugestões para preparar os seus dados

• Para novos dados, inclua dados históricos completos para todos os funcionários.
• Importar dados organizacionais para todos os funcionários da empresa, incluindo funcionários licenciados e não licenciados.
• Veja o modelo de .csv de exemplo para obter diretrizes e estrutura de dados para evitar problemas comuns, como demasiados ou poucos valores exclusivos, campos redundantes, formatos de dados inválidos e muito mais.

Exportar os seus dados numa frequência definida

Com a frequência que decide (uma vez por mês, uma vez por semana, etc.) peça à sua aplicação personalizada para exportar dados organizacionais do seu sistema de origem como uma pasta zip e armazená-los nos seus ficheiros. Baseie esta pasta zip na pasta aqui. A pasta zip tem de conter um ficheiro data.csv e um ficheiro de metadata.json.

Seguem-se mais alguns detalhes sobre estes ficheiros e o que precisam de conter:

data.csv

Adicione todos os campos que pretende importar neste ficheiro. Certifique-se de que o formatar de acordo com as nossas diretrizes em Preparar dados organizacionais.

metadata.json

Indique o tipo de atualização que está a executar e como o Viva Insights deve mapear os campos:

• "DatasetType": "HR" (linha 2). Deixe isto como está.
• "IsBootstrap": (linha 3). Utilize "true" para indicar uma atualização completa e "false" para indicar uma atualização incremental.
• "ColumnMap":. Se utilizar nomes que não o que o Viva Insights utiliza, altere o nome do cabeçalho de cada coluna para corresponder ao que utiliza no seu sistema de origem.

Exemplo de mapeamento

O exemplo seguinte representa um campo no ficheiro metadata.json:

"PersonId": {
    "name": "PersonId",
    "type": "EmailType"

• "PersonId": { corresponde ao nome da coluna de origem.
• “name” : “PersonId”, corresponde ao nome do campo Informações Viva.
• "type": "EmailType" corresponde ao tipo de dados do campo.

Digamos que, em vez de , o sistema de PersonIdorigem utiliza Employee para este cabeçalho de campo. Para se certificar de que os campos estão mapeados corretamente, edite a primeira linha abaixo, para que tenha o seguinte aspeto:

      "Employee": {
        "name": "PersonId",
        "type": "EmailType"

Quando carrega os seus dados, o seu Employee campo torna-se PersonId no Viva Insights.

Importar os seus dados

Para importar os seus dados para o Viva Insights, pode escolher entre quatro opções:

• Utilize a nossa API para criar uma aplicação personalizada que exporta e importa os seus dados com a frequência que escolher. Saiba mais.
• Execute a nossa solução C# na consola, que se baseia na nossa API. Saiba mais.
• Execute o nosso script do PowerShell, que também se baseia na nossa API. Saiba mais.
• Utilize o nosso modelo de Azure Data Factory (ADF) para enviar dados para a nossa importação baseada em API. Saiba mais.

Antes de trabalhar com qualquer uma das opções abaixo, certifique-se de que tem estas informações:

• ID da aplicação (cliente). Localize este ID nas informações da aplicação registada no portal do Azure em ID da Aplicação (cliente).
• Segredo do cliente: esta é uma cadeia secreta que a aplicação utiliza para provar a sua identidade ao pedir um token. Também é conhecida como palavra-passe de aplicação. Este segredo só é apresentado pela primeira vez quando o segredo do cliente é criado. Para criar um novo segredo do cliente, veja Criar uma aplicação Microsoft Entra e um principal de serviço no portal.
• Nome do certificado. Este nome está configurado na sua aplicação registada. Depois de carregar o certificado, o nome do certificado é apresentado em Descrição no Portal do Azure. Pode utilizar o nome do certificado como alternativa ao segredo do cliente.
• O ficheiro zip e o caminho para o ficheiro zip. Não altere os nomes de ficheiro data.csv e metadata.json.
• Microsoft Entra ID do inquilino. Encontre também este ID na página de descrição geral da aplicação em ID de diretório (inquilino).
• Unidade de escala: a unidade de escala fornecida para o seu inquilino, por exemplo, novaprdwus2-01.

Acerca da API de entrada de dados de RH do Viva Insights

Veja os seguintes comandos:

[Cabeçalhos de pedido]

Estes dois cabeçalhos de pedido são necessários para todas as APIs mencionadas abaixo

x-nova-scaleunit: <ScaleUnit obtained from Insights setup connection page>

Authentication: Bearer <Oauth token from AAD>

Obter conector/ping para marcar se o conector estiver definido para um inquilino

[GET] https://api.orginsights.viva.office.com/v1.0/scopes/<tenantId>/ingress/connectors/HR

[ResponseBody]

Se o conector estiver definido e a aplicação do autor da chamada (ID) receber autorização:

200:  

{ 
       “ConnectorId”: “Connector-id-guid” 

}

Se o Administrador de Informações tiver removido o conector ou o conector ainda não tiver sido definido pelo Administrador de Informações:

403: Forbidden.

Enviar dados por push

Aplicação de inquérito 1P/3P para chamar a API de Informações Viva para emitir conteúdo

[POST] https://api.orginsights.viva.office.com/v1.0/scopes/<tenantId>/ingress/connectors/HR/ingestions/fileIngestion

[Corpo] conteúdo do ficheiro como multipart/form-data

Tipo: Arquivo zip

Conteúdo a arquivar:

Metadata.json

Data.csv

[Corpo do Pedido]

Body: 

{ 

   "$content-type": "multipart/form-data", 

   "$multipart":  

    [ 

        { 

            "headers":  

                { 

                    "Content-Disposition": "form-data; name=\"file\"; filename=info" 

                   }, 

            "body": @{body('Get_blob_content_(V2)')} 

         } 

    ] 

} 

[Corpo da Resposta]

200:  
{ 

  "FriendlyName": "Data ingress", 

  "Id": "<ingestion Id>", 

  "ConnectorId": "<connector Id>", 

  "Submitter": "System", 

  "StartDate": "2023-05-08T19:07:07.4994043Z", 

  "Status": "NotStarted", 

  "ErrorDetail": null, 

  "EndDate": null, 

  "Type": "FileIngestion" 

} 

Caso o conector não esteja definido:

403: Forbidden

Se o conector estiver definido, mas a ingestão anterior ainda não estiver concluída:

400: Bad request: Previous ingestion is not complete.

Status de inquéritos

API para consultar status para a ingestão, uma vez que a ingestão de dados é uma operação de execução prolongada.

[GET] https://api.orginsights.viva.office.com/v1.0/scopes/<tenantId>/ingress/connectors/Hr/ingestions/fileIngestion/{ingestionId:guid}

[Resposta]

200: 
{ 

            "FriendlyName": "Data ingress", 

            "Id": "<ingestion Id>", 

            "ConnectorId": "<connector Id>", 

            "Submitter": "System", 

            "StartDate": "2023-05-08T19:05:44.2171692Z", 

            		  "Status": "NotStarted/ExtractionComplete/ValidationFailed 

/Completed/", 

            "ErrorDetail": null, 

            "EndDate": "2023-05-08T20:09:18.7301504Z", 

            "Type": "FileIngestion" 

}, 

Transferir o fluxo de erros se a validação falhar (problema nos dados)

[GET] https://api.orginsights.viva.office.com/v1.0/scopes/<tenantId>//Hr/ingestions/{ingestionId}/errors

[Resposta]

200: File stream with errors, if any.

Opção 1: Utilizar a API de entrada de dados de RH do Viva Insights para criar uma aplicação de importação/exportação personalizada

Pode utilizar a API de entrada de dados de RH do Viva Insights para criar uma aplicação personalizada que exporta automaticamente dados do seu sistema de origem e, em seguida, importá-los para o Viva Insights.

A sua aplicação pode assumir qualquer formulário (por exemplo, um script do PowerShell), mas tem de exportar os seus dados de origem como uma pasta zip na frequência que escolher, armazenar a pasta nos seus ficheiros e importar essa pasta para o Viva Insights.

Opção 2: importar dados através da nossa solução C# depois de exportar dados através da sua aplicação personalizada

Depois de exportar os dados de origem como uma pasta zip na frequência que escolher e armazenar essa pasta nos seus ficheiros, pode executar a solução DescriptiveDataUploadApp C# na consola do . A solução DescriptiveDataUploadApp C# traz os seus dados armazenados localmente para o Viva Insights. Saiba mais no GitHub.

Para executar a solução:

1. Clone esta aplicação para o seu computador ao executar o seguinte comando na linha de comandos:

   git clone https://github.com/microsoft/vivainsights_ingressupload.git.

2. Inclua os seguintes valores da consola. Veja Preparar, exportar e importar dados organizacionais para descrições.

   • AppID/ClientID
   • Caminho absoluto para o ficheiro zipado. Formate o caminho da seguinte forma: C:\\Users\\JaneDoe\\OneDrive - Microsoft\\Desktop\\info.zip
   • ID do inquilino do Microsoft Entra
   • Nome do certificado

Opção 3: executar a solução DescriptiveDataUpload do PowerShell depois de exportar dados através da sua aplicação personalizada

Semelhante à opção 2, depois de exportar os dados de origem como uma pasta zip na frequência que escolher e armazenar essa pasta nos seus ficheiros, pode executar a solução DescriptiveDataUpload do PowerShell na consola do . A solução DescriptiveDataUpload do PowerShell traz os seus dados armazenados localmente para o Viva Insights. Saiba mais no GitHub.

1. Clone o código fonte para o computador ao executar este comando na linha de comandos:

   git clone https://github.com/microsoft/vivainsights_ingressupload.git

2. Abra uma nova janela do PowerShell como administrador.

3. Na janela do PowerShell, execute o seguinte comando:

   Install-Module -Name MSAL.PS

   Em alternativa, aceda a esta ligação da galeria do PowerShell para obter instruções sobre a instalação.

4. Definir parâmetros. Veja Preparar, exportar e importar dados organizacionais para descrições.

   • ClientID
   • pathToZippedFile
   • TenantId
   • novaScaleUnit
   • ingressDataType: HR
   • ClientSecret ou certificateName

Opção 4: Utilizar o nosso modelo de Azure Data Factory (ADF) para enviar dados para a nossa importação baseada em API

1. Criar novos Azure Data Factory

1. Inicie sessão em https://adf.azure.com/en/datafactories.

2. Crie uma nova fábrica de dados ou utilize uma fábrica de dados existente. Preencha os campos e, em seguida, selecione Criar.

   

2. Criar um novo pipeline e atividade

1. Crie um novo pipeline e introduza um nome para o pipeline.

   

2. Em Atividades, adicione Copiar dados.

   

3. Copiar definições de atividade de dados: Geral

Selecione a atividade Copiar dados e, em seguida, selecione Geral para concluir cada campo com a documentação de orientação abaixo.

• Nome: introduza um nome para a sua atividade.
• Descrição: introduza uma descrição para a sua atividade.
• Estado da atividade: selecione Ativado. Em alternativa, selecione Desativado para excluir a atividade da execução e validação do pipeline.
• Tempo limite: esta é a quantidade máxima de tempo que uma atividade pode ser executada. A predefinição é 12 horas, o mínimo é 10 minutos e o tempo máximo permitido é de sete dias. O formato está em D.HH:MM:SS.
• Repetir: o número máximo de tentativas de repetição. Isto pode ser deixado como 0.
• Intervalo de repetição (seg.): o número máximo de tentativas de repetição. Isto pode ser deixado como 30 se as tentativas de repetição estiverem definidas como 0.
• Saída segura: quando selecionada, o resultado da atividade não é capturado no registo. Pode deixar esta opção desmarcada.
• Entrada segura: quando selecionada, a entrada da atividade não é capturada no registo. Pode deixar esta opção desmarcada.

4. Copiar definições de atividade de dados: Origem

1. Selecione Origem.

2. Selecione um conjunto de dados de origem existente ou selecione +Novo para criar um novo conjunto de dados de origem. Por exemplo, em Novo conjunto de dados, selecione Armazenamento de Blobs do Azure e, em seguida, selecione o tipo de formato dos seus dados.

   

3. Defina as propriedades do ficheiro .csv. Introduza um Nome e, em Serviço ligado, selecione uma localização existente ou selecione +Novo.

   

4. Se tiver selecionado +Novo, introduza os detalhes do novo serviço ligado com a documentação de orientação abaixo.

   

5. Junto a Conjunto de dados de origem, selecione Abrir.

   

6. Selecione Primeira linha como cabeçalho.

   

5. Copiar definições de atividade de dados: Sink

1. Selecione Sink.

2. Selecione +Novo para configurar um novo recurso rest para ligar à API de Importação do Viva Insights. Procure "Descansar" e selecione Continuar.

   

3. Dê um nome ao serviço. Em Serviço ligado, selecione +Novo.

   

4. Procure "Descansar" e selecione-o.

   

5. Introduza os campos com a documentação de orientação abaixo.

   

• Nome: introduza um nome para o novo serviço ligado.
• Descrição: introduza uma descrição para o novo serviço ligado.
• Ligar através do runtime de integração: introduza o método preferencial.
• URL base: utilize o URL abaixo e substitua <TENANT_ID> pelo seu ID de inquilino: https://api.orginsights.viva.office.com/v1.0/scopes/<TENANT_ID>/entrada/conectores/HR/ingestões/fileIngestion
• Tipo de autenticação: selecione o tipo de autenticação como Principal de serviço ou Certificado. Exemplo do principal de serviço:
  • Inline: selecione-o.
  • ID do principal de serviço: introduza o ID.
  • Chave do principal de serviço: introduza a chave.
  • Inquilino: introduza o ID do inquilino.
  • Microsoft Entra ID recurso:https://api.orginsights.viva.office.com
  • Azure tipo de cloud: selecione o tipo de cloud Azure.
  • Validação do certificado de servidor: selecione Ativado.

6. Introduza as definições de Sink com a documentação de orientação abaixo.

   

• Conjunto de dados sink: selecione o conjunto de dados existente ou criado recentemente.
• Método do pedido: selecione POST.
• Tempo limite do pedido: cinco minutos é a predefinição.
• Intervalo do pedido (ms): 10 é a predefinição.
• Tamanho do lote de escrita: o tamanho do lote deve ser superior ao número máximo de linhas no ficheiro.
• Tipo de compressão Http: Nenhum é a predefinição. Em alternativa, pode utilizar gZip.
• Cabeçalhos adicionais: selecione +Novo.
  • Caixa 1: x-nova-scaleunit
  • Valor: o valor pode ser obtido a partir da Análise da Área de Trabalho ao navegar para o separador ->Dados da organização –> Selecione Gerir origens de dados –> Selecione Importação baseada em API.

6. Copiar definições de atividade de dados: Mapeamento

1. Selecione Mapeamento.

2. Para o carregamento do bootstrap, certifique-se de que inclui PersonId, ManagerId e Organização no mapeamento (nome de destino). Para o carregamento incremental, verifique se os nomes de destino são consistentes com os do carregamento anterior, juntamente com PersonId. Não pode efetuar carregamentos incrementais com novas colunas e o PersonId é necessário em todos os carregamentos.

   

7. Copiar definições de atividade de dados: Definições e Propriedades do Utilizador

Não são necessárias outras personalizações para Definições ou Propriedades do Utilizador. Se for necessário, pode editar estas definições caso a caso.

8. Atividade de cópia de dados: Configuração do Acionador (Automatização)

Para adicionar um acionador à configuração da automatização, selecione Adicionar acionador. A automatização recomendada é semanal. Também pode personalizar a frequência.

Validação

Depois de o administrador da origem de dados enviar dados, a aplicação começa a validar.

Após a conclusão desta fase, a validação teve êxito ou falhou. Dependendo do resultado, receberá uma notificação de êxito ou uma notificação de falha no canto superior direito do ecrã Ligações de dados .

Para obter informações sobre o que acontece a seguir, aceda à secção adequada:

A validação é bem-sucedida

Falha na validação

A validação é bem-sucedida

Após a validação bem-sucedida, o Viva Insights começa a processar os seus novos dados. O processamento pode demorar entre algumas horas e um dia ou mais. Durante o processamento, é apresentada uma status "Processamento" na tabela Histórico de importações.

Após o processamento estar concluído, significa que foi bem-sucedido ou falhou. Consoante o resultado, encontrará uma status "Êxito" ou "Com Falhas" na tabela Histórico de importações.

O processamento é bem-sucedido

Quando encontrar a status "Êxito" na tabela Histórico de importações, o processo de carregamento é concluído.

Depois de receber a status "Êxito", pode:

• Selecione o ícone de vista (olho) para ver um resumo dos resultados da validação.
• Selecione o ícone de mapeamento para ver as definições de mapeamento do fluxo de trabalho.

O processamento falha

Se o processamento falhar, é apresentada uma status "A processar falhou" na tabela Histórico de importações. Para que o processamento seja bem-sucedido, o administrador da origem de dados tem de corrigir erros e enviar os dados novamente para o Viva Insights.

Falha na validação

Se a validação de dados falhar, será apresentada uma status "Validação falhada" na tabela Histórico de importações. Para que a validação seja bem-sucedida, o administrador da origem de dados tem de corrigir erros e enviar os dados novamente para o Viva Insights. Em Ações, selecione o ícone de transferência para transferir um registo de erros. Envie este registo para o administrador da origem de dados para que saiba o que deve corrigir antes de enviar os dados novamente.

O administrador da origem de dados pode considerar a secção seguinte útil para corrigir erros de dados no respetivo ficheiro de exportação.

Acerca dos erros nos dados

Aplica-se a: administrador da origem de dados

Quando qualquer linha ou coluna de dados tem um valor inválido para qualquer atributo, toda a importação falha até que o administrador da origem de dados corrija os dados de origem.

Veja Preparar dados organizacionais para regras de formatação específicas que possam ajudar a resolve erros que encontrar.

Saiba mais sobre erros e avisos de validação.

Tópicos relacionados

Prepare os dados organizacionais

Importar dados organizacionais (importação subsequente)