API Exportation de migration SharePoint (lecture asynchrone des métadonnées)

Vue d’ensemble

L’objectif de la nouvelle API de lecture asynchrone de métadonnées de migration (AMR) consiste à réduire le nombre d’appels, de réduire la restriction et d’améliorer les performances de migration globales pour nos clients. Au lieu de procéder à des milliers d’appels pour demander des informations à SPO, la nouvelle lecture asynchrone de métadonnées de migration peut renvoyer la même quantité de données en une seule lecture.

Lorsque la nouvelle API Exportation de migration SharePoint (lecture asynchrone des métadonnées) lit une URL fournie, le logiciel back-end Microsoft regroupe toutes les informations dans un manifeste désigné. L’éditeur de logiciels indépendant peut relire le manifeste et analyser les métadonnées sans avoir à passer des milliers d’appels individuels. L’API AMR permet également d’équilibrer la charge du serveur et prend en charge une quantité illimitée de métadonnées devant être déplacées.

Ce document cible les éditeurs de logiciels indépendants et les développeurs/fournisseurs tiers qui développent et gèrent un outil de migration.

Arrière-plan

Actuellement, l’API de migration SharePoint Online permet à votre outil de migration de migrer efficacement de grandes quantités de données vers SharePoint Online. Toutefois, le manque d’API officielle permettant de lire le contenu à partir de SharePoint Online signifie que ces outils doivent compter sur des appels de fonction CSOM/Vroom afin d’effectuer des opérations individuelles de lecture des métadonnées.

Lorsque le nombre d’appels est élevé, la probabilité de limitation augmente, ce qui nuit aux performances de migration et détériore l’expérience client. L’utilisation inefficace d’un appel entraîne de nombreux allers-retours SQL par appel de fonction pouvant potentiellement réduire les performances et la fiabilité de la base de données.

Une étude sur les performances de migration a identifié quatre domaines dans lesquels un grand nombre d’appels sont très sollicités :

  • Migration incrémentielle : s’appuie sur des appels pour récupérer le contenu SharePoint Online (SPO). Elle le compare avec l’emplacement source pour déterminer si des modifications ont été apportées au contenu et si la migration doit se poursuivre.
  • Création de structure : exploite les appels pour la création de sites, de composants WebPart et de navigation.
  • Vérification après la migration : est effectuée lorsque la migration est terminée et permet d’assurer que les métadonnées de fichier source et de destination concordent.
  • Paramètres d’autorisation : appels de fonction sont effectués pour obtenir des informations relatives aux autorisations utilisateur.

API Exportation de migration SharePoint (lecture asynchrone des métadonnées)

L’API Exportation de migration SharePoint (lecture asynchrone des métadonnées) vise à réduire le nombre d’appels dans les domaines suivants : migration incrémentielle, vérification post-migration et paramètres d’autorisation.

Notes

La première version de l’API Exportation de migration SharePoint (lecture asynchrone des métadonnées) prend en charge les fichiers, les dossiers, les listes, les éléments de liste et la bibliothèque de documents. Les autorisations devraient être couvertes dans une version ultérieure.

Fonctionnalités prises en charge :

  • Possibilité d'agréger de petits appels de demandes de métadonnées (par exemple, CSOM) en un seul appel AMR à l'aide de la fonctionnalité d'URL multiples
  • Possibilité de lire des éléments illimités vec un seul appel d’API.
  • Prise en charge de la fonctionnalité de migration incrémentielle du retour des éléments modifiés depuis la dernière requête avec la fonctionnalité changeToken
  • Possibilité d’inclure un ensemble complet de métadonnées par élément
  • Possibilité de retourner uniquement la structure de niveau supérieur sans sous-dossiers ni enfants.

Des informations plus détaillées sur les fonctionnalités et la description de l’API sont traitées dans la section ci-dessous.

Les API de lecture asynchrone de migration sont les suivantes :

Unique

public SPAsyncReadJobInfo CreateSPAsyncReadJob(
        Uri url,
        SPAsyncReadOptions readOptions,
        EncryptionOption encryptionOption,
        string azureContainerManifestUri,
        string azureQueueReportUri)

Multiple

public SPAsyncReadJobInfo CreateSPAsyncReadJobWithMultiUrl(
        Uri[] urls,
        SPAsyncReadOptions readOptions,
        EncryptionOption encryptionOption,
        string azureContainerManifestUri,
        string azureQueueReportUri)

L’API est composée de cinq paramètres d’entrée et d’un champ de structure en sortie.

Paramètres d’entrée

URL

L’URL complète permet à votre outil de migration de spécifier le chemin de l’URL racine de la liste, la bibliothèque des documents des fichiers/dossiers SharePoint à lire. Par défaut, le code côté serveur lit et renvoie toutes les métadonnées des fichiers, dossiers et objets racine, y compris les sous-dossiers et leur contenu enfant.

Exemple : L’URL de la bibliothèque de documents, https://www.contoso.com/Shared%20Document, est relue à la recherche de métadonnées des fichiers ou dossiers qui résident sous l’URL racine. https://www.contoso.com/Shared%20Documents/FolderA/, est relu à la recherche de métadonnées enfants dans DossierA.

URL multiples

Avec la dernière mise à jour de l’API au T1 2020, AMR prendra désormais en charge plusieurs entrées d’URL. Cela signifie que l’utilisateur peut entrer plusieurs URL racines ou sous-dossiers et les agréger en un seul appel.

Dans la mesure où il existe une surcharge fixe, AMR est plus efficace lorsqu’il y a un grand nombre de lectures lors du traitement d’AMR. Dans certains cas, il est possible que le logiciel de migration ne puisse pas lire l’intégralité de l’URL du niveau racine. La fonctionnalité d’URL multiple permet au logiciel d’agréger plusieurs demandes dans une seule demande pour améliorer les performances tout en réduisant le nombre d’appels.

(Pour plus d’informations sur la recommandation de taille, voir la section performances)

Exemple : l’URL de la bibliothèque de documents, https://www.contoso.com/Shared%20Document, a des dossiers de A à J. Le client souhaite seulement migrer les dossiers A, B, C, D et E. Au lieu d’émettre une seule lecture au niveau racine et de renvoyer un contenu inutile de grande ampleur, ou d’émettre une entrée AMR par dossier, ce qui n’est pas efficace, le logiciel peut émettre un URI [A, B, C, D, E] dans les paramètres d’entrée renvoyant uniquement les métadonnées requises.

Il n’existe actuellement qu’un maximum de 5000 limites d’agrégation d’URL par appel.

Indicateur readOptions

La fonction de lecture asynchrone inclura la structure SPAsyncReadOptions qui couvre les indicateurs facultatifs pour autoriser l’utilisateur à spécifier la version et le paramètre de sécurité au niveau du site. Voir plus d’informations ci-dessous.

IncludeVersions{ get; set; }

Si elle est activée, cela indique que tous les fichiers et l’historique de version d’élément de liste doivent être inclus dans l’opération d’exportation. Si absente, seule la version la plus récente est alors fournie.

IncludeSecurity{ get; set; }

Cet élément indique si toutes les informations d’utilisateur ou de groupe d’un site doivent être incluses. Par défaut, les utilisateurs et les groupes qui font partie des métadonnées de l’objet sont renvoyés, par exemple l’auteur ou le modificateur.

Si vous utilisez cet indicateur, tous les utilisateurs dans la collection de sites seront inclus. Si vous émettez des appels AMR pour différentes bibliothèques de documents figurant sous la même collection de sites, le même ensemble d’utilisateurs est inclus à chaque fois, sauf si une modification a été apportée.

Important

L’utilisation de cette option peut entraîner une baisse importante des performances. Utilisez-la uniquement selon les étapes décrites ci-dessous.

Pour un grand nombre d’objets dans une bibliothèque de documents, il est plus rapide d’effectuer les deux appels suivants pour lire le paramètre de sécurité et ses dossiers enfants :

  1. Pour obtenir des informations sur les utilisateurs ou les groupes, appelez la tâche AMR sur le dossier racine supérieur avec la sécurité activée en utilisant ce paramètre : ("IncludeSecurity=true" & "IncludeDirectDescendantsOnly=true").
  2. Pour le reste de la structure, appelez la tâche AMR avec la sécurité désactivée : "IncludeSecurity=false"
public bool IncludeDirectDescendantsOnly { get; set;}

S’il est spécifié, seul l’élément de métadonnées de niveau supérieur est relu. Exemple : l’URL racine contient fichier A et dossier B. Si cet indicateur est spécifié, le manifeste renvoie uniquement les métadonnées fichier A et dossier B. Elle ne renverra aucune métadonnée incluse dans le dossier B.

Le cas d’utilisation de cette fonction est qu’un éditeur de logiciels indépendant peut émettre une lecture par défaut pour récupérer les éléments de niveau supérieur, puis émet plusieurs CreateSPAsyncReadJob pour relire tout le contenu du sous-dossier en parallèle pour améliorer le débit.

public bool IncludeExtendedMetadata { get; set; }

Cet indicateur indique s’il faut renvoyer le groupe étendu de contenu de métadonnées d’une requête d’objet. Par défaut, cette option est désactivée et seul le contenu de base est fourni (par exemple, les noms, l’URL, l’auteur, le modificateur, les dates). L’activation de cet indicateur permet de fournir tout le contenu des métadonnées. Toutefois, elle aura également un impact sur les performances, car l’exécution de la requête prendra plus de temps.

Nous vous conseillons de conserver les paramètres par défaut pour la migration de partage de fichiers, mais envisagez d’activer cet indicateur pour SharePoint local ou une autre migration plus complexe.

public string StartChangeToken { get; set; }

Cette option s’applique uniquement à l’URL d’entrée de la liste ou de la bibliothèque de documents.

L’un des principaux contributeur d’appels est la migration incrémentielle. L’idée ChangeToken est proposée pour réduire les appels superflus. Si StartChangeToken n’est pas spécifié, CreateSPAsyncReadJob interroge et relit tous les éléments spécifiés par la fonction API. Une fois spécifié avec la valeur ChangeToken, seul l’élément modifié depuis la dernière requête est renvoyé.

Au cours d’une migration incrémentielle, plutôt que de relancer la requête, en remplissant StartChangeToken avec le jeton de modification reçu de la sortie CurrentChangeToken pour renvoyer des informations sur la tâche, createSPAsyncReadJob renvoie uniquement les éléments modifiés depuis la tâche StartChangeToken spécifiée, réduisant de manière générale les appels.

Voici un exemple de la manière dont lestartChangeToken peut fonctionner. Cet exemple utilise le paramètre de fonctionnalité facultatif pour l’appel initial et le paramètre de passes incrémentielles.

Exporter le processus API

Valeur non valide

Si un format non valide différent de NULL est détecté, une erreur est générée et l’opération est interrompue.

encryptionOption

Ce paramètre est facultatif. S’il est spécifié, AES256CBCKey est utilisé pour chiffrer les fichiers de sortie et les messages de la file d’attente. Autrement, il n’y a aucun chiffrement.

Pour plus d’informations, voirclasse EncryptionOption.

azureContainerManifestUri

L’URL valide, y compris les jetons SAS pour accéder au conteneur de stockage Azure Blob qui contient les objets blob de bloc pour le manifeste et un autre pack décrivant les fichiers XML. Cet emplacement est également utilisé pour la réponse de la sortie du journal. Les jetons SAS doivent avoir été créés uniquement avec les permissions Lecture, et Écriture ou la tâche de lecture asynchrone des métadonnées échouera. Les jetons SAS doivent au moins disposer d’une durée de vie qui commence à partir du moment où la tâche a été envoyée, avec un délai raisonnable pour une importation réussie.

azureQueueReportUri

L’URL valide, y compris les jetons SAS pour accéder à la file d’attente Azure fournie à l’utilisateur utilisée pour renvoyer les notifications de l’avancement de tâche de lecture asynchrone des métadonnées. Si cette valeur n’est pas null et les droits d’accès sont donnés dans le jeton SAS dans cette URL, elle sera utilisée pour mettre à jour le statut en temps réel. Les jetons SAS doivent avoir été créés avec uniquement des permissions Ajout ou la tâche de migration ne pourra pas ajouter d’événements à la file d'attente.

Une fois accepté, l’ID de travail est inscrit dans la file d’attente notification s’il a été fourni et l’accès est valide. La file d’attente notification peut être utilisée pour plusieurs tâches de migration en même temps, car chaque tâche identifie elle-même les valeurs envoyées à la file d’attente de notification.

Paramètres de sortie

CurrentChangeToken

public string CurrentChangeToken { get; set; }

Cette fonction renvoie les éléments changeToken associés à cette requête. En spécifiant cette tâche changeToken dans le champ d’entrée lors de la lecture suivante, l’API renvoie uniquement les éléments modifiés depuis la dernière requête.

Sortie de manifeste

Une fois que la fonction asyncMigrationRead prépare l’exécution, le manifeste final est placé dans le conteneur spécifié dans un dossier nommé JobId. La structure du package d’exportation de fichier manifeste sera semblable à la structure du package d’importation createMigration. La structure de sortie générale est synthétisée dans le tableau ci-dessous.

Notes

Une fois que le package manifeste AMR atteint 25 Mo, il est fractionné en plusieurs packages par requête.

Voici un exemple d’interrogation du dossier :

CloudBlobDirectory folder = blobContainerObj.GetDirectoryReference(jobid);
CloudBlockBlob blob = folder.GetBlockBlobReference(manifestFileName);
Fichier XML Fichier de schéma Description
ExportSettings.xml Schéma DeploymentExportSettings ExportSettings.XML effectue les opérations suivantes :

-Contient les paramètres d’exportation spécifiés à l’aide de la classe SPExportSettings et autres classes qui font partie du modèle objet migration de contenu.

- Garantit que le processus d’exportation suivant (sur le site cible de migration) applique les directives spécifiées dans les paramètres d’exportation.

-Tient à jour un catalogue de tous les objets exportés vers le pack de migration.
LookupListMap.XML Schéma DeploymentLookupListMap Fournit la validation du fichier LookupListMap.XML exporté dans le pack de migration de contenu. LookupListMap.XML gère une liste de recherche simple qui enregistre références des éléments de liste SharePoint (élément de liste à élément de liste).
Manifest.XML Schéma DeploymentManifest Fournit la validation pour le fichier Manifest.xml exporté dans le pack de migration de contenu. Fournit un manifeste complet contenant des listes du contenu et de la structure du site de destination (par exemple, SPO).
Requirements.xml Schéma DeploymentRequirements « Fournit la validation du fichier Requirements.xml exporté dans le pack de migration du contenu. Requirements.xml gère la liste des conditions de déploiement sous la forme de configuration requise pour l’installation du côté de la destination de la migration, comme les définitions de fonctionnalité, les versions des modèles, les assemblys de composants WebPart et les modules linguistiques ».
RootObjectMap.XML Schéma DeploymentRootObjectMap « Fournit la validation du fichier RootObjectMap.xml exporté dans le package de migration de contenu. RootObjectMap.xml gère la liste des mappages des objets (dépendants) secondaires, ce qui permet à la phase d’importation de l’opération de migration de placer correctement les objets dépendants par rapport aux emplacements des mappages objet racine. »
SystemData.xml Schéma DeploymentSystemData Fournit la validation du fichier SystemData.xml exporté dans le pack de migration de contenu. SystemData.xml effectue les opérations suivantes : collecte un large éventail de données du système de bas niveau. Enregistre le nombre et le nom des fichiers Manifest.xml (dans les cas où la migration utilise plusieurs manifestes).
UserGroupMap.XML Schéma DeploymentUserGroupMap Fournit la validation du fichier UserGroup.xml exporté dans le pack de migration de contenu. UserGroup.xml gère une liste d’utilisateurs et de groupes de sécurité utilisateur qui concerne la sécurité d’accès et les autorisations.
ViewformsList.xml Schéma DeploymentViewFormsList Fournit la validation du fichier ViewFormsList.xml exporté dans le pack de migration de contenu. ViewFormsList.xml gère une liste de composants WebPart et effectue le suivi si chacun d’eux a un affichage ou un formulaire.

Récupérer le manifeste à partir de l’objet blob Azure

L'exemple de code suivant montre comment obtenir le blob Azure d'un fichier manifeste et le déchiffrer :

// Get Azure blob of a manifest file
CloudBlockBlob blob = folder.GetBlockBlobReference(blobName);
blob.FetchAttributes();

using (Stream stmTemp = new MemoryStream())
{
    // Download current manifest file
    blob.DownloadToStream(stmTemp);

    // Get IV and decrypt the content into output dir
    byte[] IV = Convert.FromBase64String(blob.Metadata[“IV”]);

    using (Stream targetStream = System.IO.File.Open(outputFileFullPath, FileMode.Append))
    {
            using (Aes alg = new AesCryptoServiceProvider())
            {
                stmTemp.Seek(0, SeekOrigin.Begin);
                using (CryptoStream csDecrypt = new CryptoStream(
                    stmTemp,
                    alg.CreateDecryptor(key, IV),
                    CryptoStreamMode.Read))
                {
                    csDecrypt.CopyTo(targetStream);
                }
            }
        }
}

JobQueueUri

public Uri JobQueueUri { get; set; }

Les fonctionnalités de création de rapports sont identiques à CreateMigrationJob. La journalisation est fournie pour suivre le statut de la lecture asynchrone des métadonnées. Après une analyse de la base de données et une estimation de vos outils, le journal fournit une estimation du nombre d’éléments à lire par URL. Par défaut, les paramètres et les autorisations de file d’attente d’objet blob sont définis sur «tous les accès» et identiques au moment où l’éditeur de logiciels indépendant appelle ProvisionMigrationContainer lors de l’exécution de CreateMigrationJob.

Outre les événements pris en charge par l’API d’importation (CreationMigrationJob), un nouvel événement de tâche appelé FinishManifestFileUpload est ajouté à la file d’attente d’états en temps réel. Cet élément est ajouté une fois le fichier manifeste généré et téléchargé en amont.

Comme il s’agit d’un événement en temps réel, les éditeurs de logiciels indépendants et les développeurs peuvent également télécharger et analyser immédiatement les fichiers manifestes une fois FinishManifestFileUpload généré. Utilisez le champ ManifestFileName pour analyser cet événement afin d’obtenir le nom de chaque fichier manifeste, y compris systemdata.xml, usergroup.xml, etc.

Le nouvel événement se présente comme suit :

{"Event", "FinishManifestFileUpload"},
{"JobId", “f8d7d577-676e-47ce-ab69-ae7803979883”},
{"Time", “2019-09-03T19:11:33.903”},
{"ManifestFileName", “f8d7d577-676e-47ce-ab69-ae7803979883/ExportSettings.xml”}

EncryptionKey

public byte[] EncryptionKey { get; set; }

Il renvoie la clé de chiffrement AES256CBC utilisée pour déchiffrer le message dans le conteneur azureManifest et dans la file d’attente azureReport.

Paramètre de sortie Description
JobID/GUID Renvoyer un ID de travail unique associé à cette lecture asynchrone
AzureContainerManifest Renvoyer l’URL pour accéder au manifeste de lecture asynchrone
JobQueueUri URL permettant d’accéder à la file d’attente Azure utilisée pour renvoyer une notification du processus de travail de migration
EncryptionKey Clé de chiffrement AES256CBC utilisée pour déchiffrer les messages de file d’attente de manifeste/travail

Instructions de configuration

Vous trouverez ci-dessous des instructions complètes relatives à l’implémentation de la fonction de migration des métadonnées asynchrone. Cette documentation n’explique pas en détail la façon d’interagir avec le service RESTful SharePoint. L’éditeur de logiciels indépendant est censé avoir des connaissances préalables et peut accéder au site Web cible avec l’autorisation appropriée.

Pour plus d’informations sur la façon d’accéder au site web SharePoint, voir Connaître le service SharePoint REST.

  1. Installez et mettez à jour la dernière version de Microsoft.SharePointOnline.CSOM. Condition requise minimale en matière de version : V16.1.9119.1200 ou version ultérieure.
  2. Les éditeurs de logiciels indépendants déterminent le dossier, la bibliothèque de documents ou les fichiers à interroger et à émettre avec la fonction CreateSPAsyncReadJob.
  3. Une fois le travail créé, interrogez le statut du travail en utilisant jobQueueUri. Il indique le statut du processus de travail et les éventuelles erreurs enregistrées. Une fois le travail terminé, analysez le fichier de manifeste pour récupérer les métadonnées.

Exemple d’API Exportation de migration SharePoint (lecture asynchrone des métadonnées)

Scénario : grand partage de fichiers (> 1 million) avec des fichiers/dossiers imbriqués

Suggestion :

  1. Issue CreateSPAsyncReadJob

    • URL = URL racine (par exemple, www.contoso.com/my-resource-document)
    • Indicateur facultatif : IncludeDirectDescendantsOnly(true)

    Pour chaque sous-dossier, problème createSPAsyncReadJob si le dossier a > 10 000

    Exemple de code source

    $site = get-spsite https://test.sharepoint.com  # get site
    $web = get-spweb https://test.sharepoint.com  # get web
    $list = $web.GetList("Shared Documents") # get the document library under this web
    
    # Get the Doclib root folder
    $rootFolder = $web.GetFolder($list.Rootfolder.ServerRelativeUrl)
    
    # You can call 1 AMR job here, to get metadata of the direct children of the root folder  only
    CreateAMRJob($rootFolder)
    
    # Create parallel AMR jobs for the direct level subfolders
    Foreach ($folder in $rootFolder.SubFolders)
    {
      // Create 1 AMR job per folder tree
      CreateAMRJob($folder)
    }
    

    L'ISV peut optimiser la partie récursive des mises en surbrillance en tirant parti du fichier $ folder.item [« SMTotalFileCount »] qui renvoie le nombre cumulé de fichiers dans l'arborescence des dossiers pour un élément de dossier donné. Suivez les recommandations de la section performances sur les types de tâches AMR à émettre

  2. objet, émis dans plusieurs URL si < 10 000 objets

Important

Ce scénario est uniquement recommandé pour les dossiers de niveau supérieur ou si le sous-dossier contient plus d’un million d’objets. Les performances de l’API AMR sont ne sont pas aussi efficaces lors de la lecture d’un petit groupe d’éléments.

Scénario : Migration incrémentielle de FileShare pour un sous-dossier

  1. Problème CreateSPAsyncReadJob :

    1. URL = URL racine (par exemple, www.contoso.com/my-resource-document/a)
    2. Souvenez-vous du CurrentChangeToken
  2. Après un certain temps, le logiciel souhaite effectuer une migration incrémentielle. Problème CreateSPAsyncReadJob avec le terme suivant :

    1. URL = URL racine (par exemple, www.contoso.com/my-resource-document/a)
    2. Indicateur facultatif : StartChangeToken(CurrentChangeToken)

Limites

La lecture asynchrone des métadonnées (API d’exportation) prend désormais en charge la liste illimitée, la bibliothèque de documents, le fichier et l’exportation de métadonnées de dossier.

Attentes en matière de performances

Le test de performances préliminaire fournit une estimation approximative d’un débit de plus de 400 éléments par seconde pour chaque 250 000 objets lus. Nous avons observé plus de 700 éléments par seconde dans un environnement de test. Cependant, cela dépend fortement du nombre d’éléments lus et de l’implémentation de l’API AMR. Cette estimation ne prend pas en compte les éventuelles limites de bande passante sur le réseau. Si la fonction de lecture asynchrone ne parvient pas à accéder au serveur en raison d’une limitation de bande passante, cela nuit aux performances.

Cette mesure de débit part du principe que le package logiciel possède d’éléments suffisant par lecture. Microsoft recommande ce qui suit :

Taille du dossier Recommandation
Moins de 10 000 éléments Combiner les URL de plusieurs dossiers en un seul appel
Supérieure à 10 000 éléments et inférieure à 1 million Exécuter AMR au niveau du dossier racine
Supérieur à 1 000 000 Utilisez la logique d’appel récursive pour explorer les enfants de niveau direct de ce dossier jusqu’à ce qu’il n’y ait plus de dossiers.

Pour une seule requête lecture, il est plus rapide d’utiliser l’API Graph ou une requête RESTful/CSOM.

L’un des principaux avantages en matière de performances de l’utilisation de la lecture asynchrone des métadonnées est la possibilité d’équilibrer la charge côté serveur et la requête principale est beaucoup plus efficace que l’utilisation de la charge individuelle CSOM ce qui réduit voire atténue le risque de limitation.