Chiamare l'API Microsoft 365 per trasferire i dati dell'organizzazione per l'importazione basata su API (passaggio 2 di 3) (anteprima)

Si applica a: amministratore globale di Microsoft 365 o amministratore dell'origine dati dell'organizzazione o amministratore del sistema informativo delle risorse umane

1. Preparare ed esportare i dati in base a una frequenza impostata

Importare i dati dell'organizzazione per tutti i dipendenti dell'azienda e aggiungere tutti i campi da importare in un modello di .csv. Informazioni su come strutturare questo file di dati.

Con la frequenza scelta, ad esempio una volta al mese o una volta alla settimana, fare in modo che l'app personalizzata esporti i dati dell'organizzazione dal sistema di origine.

2. Chiamare l'API per importare i dati

Per importare i dati in Microsoft 365, è possibile scegliere tra quattro opzioni:

• Usare l'API per creare un'app personalizzata che esporta e importa i dati alla frequenza scelta. Procedura

• Eseguire la soluzione C# nella console, basata sull'API. Procedura

• Eseguire lo script di PowerShell, basato anche sull'API. Procedura

• Usare un modello Azure Data Factory (ADF) per inviare dati all'importazione basata su API. Procedura

Prima di usare una delle opzioni seguenti, assicurarsi di avere queste informazioni:

• ID app (client). Trovare questo ID nelle informazioni sull'app registrata nel Interfaccia di amministrazione di Microsoft Entra in ID applicazione (client).

• Segreto client: stringa segreta usata dall'applicazione per dimostrare la propria identità durante la richiesta di un token. Viene anche definita password dell'applicazione. Questo segreto viene visualizzato solo per la prima volta quando viene creato il segreto client. Per creare un nuovo segreto client, seguire questa procedura.

• Nome certificato. Questo nome è configurato nell'applicazione registrata. Dopo aver caricato il certificato, il nome del certificato viene visualizzato in Descrizione nel portale di Azure. È possibile usare il nome del certificato come alternativa al segreto client.

• Microsoft Entra ID tenant. Questo ID è disponibile nella pagina di panoramica dell'app in ID directory (tenant).

• Unità di scalabilità: unità di scalabilità fornita per il tenant, ad esempio "novaprdwus2-01".

• Il file .csv e il percorso del file .csv.

Eseguire il push dei dati

App di sondaggio 1P/3P per chiamare l'API Microsoft 365 per eseguire il push del contenuto

[POST] https://api.orginsights.viva.office.com/v1.0/tenants/{tenantid}/modis/connectors/HR/ingestions/fileIngestion

Nel caso in cui il connettore non sia impostato:

403: Forbidden

Se il connettore è impostato ma l'inserimento precedente non è ancora stato completato:

400: Bad request: Previous ingestion is not complete.

Opzione 1: usare l'API Microsoft 365 per creare un'app di importazione/esportazione personalizzata

È possibile usare l'API Microsoft 365 per compilare un'app personalizzata che esporta automaticamente i dati dal sistema di origine e quindi li importa nel interfaccia di amministrazione di Microsoft 365.

L'app può assumere qualsiasi forma, ad esempio uno script di PowerShell, ma deve esportare i dati di origine come file .csv alla frequenza selezionata e importare tale file in app e servizi di Microsoft 365.

Opzione 2: Importare dati tramite la soluzione C# dopo l'esportazione dei dati tramite l'app personalizzata

Dopo aver esportato i dati di origine come file .csv alla frequenza selezionata, è possibile eseguire la soluzione C# DescriptiveDataUploadApp nella console. La soluzione C# DescriptiveDataUploadApp porta quindi i dati archiviati localmente in Microsoft 365. Altre informazioni su GitHub.

Per eseguire la soluzione:

1. Clonare questa app nel computer eseguendo il comando seguente nella riga di comando:

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

2. Includere i valori della console seguenti.

   • AppID/ClientID
   • Percorso assoluto del file .csv. Formattare il percorso in questo modo: C:\\Users\\JaneDoe\\OneDrive - Microsoft\\Desktop\\info.csv
   • MICROSOFT ENTRA ID tenant
   • Nome certificato

Opzione 3: Eseguire la soluzione DescriptiveDataUpload PowerShell dopo l'esportazione dei dati tramite l'app personalizzata

Analogamente all'opzione 2, dopo aver esportato i dati di origine come file .csv alla frequenza selezionata, è possibile eseguire la soluzione DescriptiveDataUpload PowerShell nella console. La soluzione DescriptiveDataUpload PowerShell porta quindi i dati archiviati localmente in Microsoft 365. Altre informazioni su GitHub.

1. Clonare il codice sorgente nel computer eseguendo questo comando nella riga di comando:

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

2. Aprire una nuova finestra di PowerShell come amministratore.

3. Nella finestra di PowerShell eseguire il comando seguente:

   Install-Module -Name MSAL.PS

   In alternativa, passare a questo collegamento alla raccolta di PowerShell per istruzioni sull'installazione.

4. Impostare i parametri.

   • ClientID
   • pathTocsvFile
   • TenantId
   • novaScaleUnit
   • ingressDataType: HR
   • ClientSecret o certificateName

Opzione 4: usare il modello Azure Data Factory (ADF) per inviare dati all'importazione basata su API

1. Creare nuove Azure Data Factory

1. Accedere a https://adf.azure.com/en/datafactories.

2. Creare una nuova data factory o usare una data factory esistente. Completare i campi, quindi selezionare Crea.

   

2. Creare una nuova pipeline e una nuova attività

1. Creare una nuova pipeline e immettere un nome per la pipeline.

   

2. In Attività aggiungere Copia dati.

   

3. Impostazioni dell'attività di copia dei dati: Generale

Selezionare l'attività Copia dati , quindi selezionare Generale per completare ogni campo usando le indicazioni riportate di seguito.

• Nome: immettere un nome per l'attività.
• Descrizione: immettere una descrizione per l'attività.
• Stato attività: selezionare Attivato. In alternativa, selezionare Disattivato per escludere l'attività dall'esecuzione e dalla convalida della pipeline.
• Timeout: si tratta della quantità massima di tempo in cui un'attività può essere eseguita. Il valore predefinito è 12 ore, il minimo è 10 minuti e la quantità massima di tempo consentita è di sette giorni. Il formato è in D.HH:MM:SS.
• Riprova: numero massimo di tentativi. Questo può essere lasciato come 0.
• Intervallo di tentativi (sec): numero massimo di tentativi di ripetizione. Questo valore può essere lasciato 30 se il tentativo di ripetizione dei tentativi è impostato su 0.
• Output sicuro: se selezionato, l'output dell'attività non viene acquisito nella registrazione. È possibile lasciare questo cancellato.
• Input sicuro: se selezionato, l'input dell'attività non viene acquisito nella registrazione. È possibile lasciare questo cancellato.

4. Impostazioni dell'attività di copia dei dati: origine

1. Selezionare Origine.

2. Selezionare un set di dati di origine esistente o selezionare +Nuovo per creare un nuovo set di dati di origine. Ad esempio, in Nuovo set di dati selezionare Archiviazione BLOB di Azure e quindi selezionare il tipo di formato dei dati.

   

3. Impostare le proprietà per il file .csv. Immettere un nome e in Servizio collegato selezionare un percorso esistente o selezionare +Nuovo.

   

4. Se è stato selezionato +Nuovo, immettere i dettagli per il nuovo servizio collegato usando le indicazioni seguenti.

   

5. Accanto a Set di dati di origine selezionare Apri.

   

6. Selezionare Prima riga come intestazione.

   

5. Impostazioni dell'attività di copia dei dati: Sink

1. Selezionare Sink.

2. Selezionare +Nuovo per configurare una nuova risorsa rest per connettersi all'API di importazione viva insights. Cercare "Rest" e selezionare Continua.

   

3. Assegnare al servizio il nome . In Servizio collegato selezionare +Nuovo.

   

4. Cercare "Rest" e selezionarlo.

   

5. Immettere i campi usando le indicazioni riportate di seguito.

   

• Nome: immettere un nome per il nuovo servizio collegato.
• Descrizione: immettere una descrizione per il nuovo servizio collegato.
• Connettersi tramite il runtime di integrazione: immettere il metodo preferito.
• URL di base: usare l'URL seguente e sostituire <TENANT_ID> con l'ID tenant: https://api.orginsights.viva.office.com/v1.0/scopes/<TENANT_ID>/ingress/connectors/HR/ingestions/fileIngestion
• Tipo di autenticazione: selezionare il tipo di autenticazione come entità servizio, quindi selezionare Segreto o Certificato. Esempio di entità servizio:

  • Inline: selezionarlo.

  • ID entità servizio: immettere l'ID app autorizzato per il connettore API.

  • Chiave dell'entità servizio: immettere la chiave.

    

  • Tenant: immettere l'ID tenant.

  • Microsoft Entra ID risorsa:https://api.orginsights.viva.office.com

  • Azure tipo di cloud: selezionare il tipo di cloud Azure.

  • Convalida del certificato del server: selezionare Abilitato.

6. Immettere le impostazioni sink usando le indicazioni riportate di seguito.

   

• Set di dati sink: selezionare il set di dati esistente o appena creato.
• Metodo di richiesta: selezionare POST.
• Timeout della richiesta: cinque minuti è l'impostazione predefinita.
• Intervallo richiesta (ms):10 è l'impostazione predefinita.
• Dimensioni batch di scrittura: le dimensioni del batch devono essere superiori al numero massimo di righe nel file.
• Tipo di compressione HTTP: nessuna è l'impostazione predefinita. In alternativa, è possibile usare GZip.
• Intestazioni aggiuntive: selezionare +Nuovo.
  • Riquadro 1: x-nova-scaleunit
  • Valore: il valore può essere recuperato da Workplace Analytics passando alla scheda ->Dati dell'organizzazione -> Selezionare Gestisci origini dati -> Selezionare importazione basata su API.

6. Impostazioni dell'attività di copia dei dati: mapping

1. Selezionare Mapping.

2. Per il caricamento del bootstrap, assicurarsi di includere PersonId, ManagerId e Organization nel mapping (nome di destinazione). Per il caricamento incrementale, verificare che i nomi di destinazione siano coerenti con quelli del caricamento precedente, insieme a PersonId. Non è possibile eseguire caricamenti incrementali con nuove colonne e PersonId è obbligatorio in tutti i caricamenti.

   

7. Impostazioni dell'attività di copia dei dati: impostazioni e proprietà utente

Non sono necessarie altre personalizzazioni per Impostazioni o Proprietà utente. Se necessario, è possibile modificare queste impostazioni caso per caso.

8. Attività di copia dei dati: Attivare l'installazione (automazione)

Per aggiungere un trigger all'installazione di automazione, selezionare Aggiungi trigger. L'automazione consigliata è settimanale. È anche possibile personalizzare la frequenza.