| title | description | ms.date | ms.author | author | manager | audience | ms.subservice | ms.topic | ms.localizationpriority | ms.collection | ||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
SharePoint Asynchronous Metadata Read (AMR) API Reference Guide |
This article provides in depth information on how to use the SharePoint AMR API. |
04/18/2024 |
ranren |
underreview |
dapodean |
ITPro |
migration-tool |
article |
high |
|
Use this document as the guide when using SharePoint Asynchronous Metadata Read (AMR) API.
AMR API aggregates SharePoint metadata into a manifest package. Use the package for incremental migration, structure creation, post-migration validation, or permission management.
AMR API supports both SharePoint Client Side Object Model (CSOM) and REST.
CSOM consumes more resources than REST. Use REST whenever possible for best performance. Reduce resource consumption and ensure that your migration jobs run efficiently with REST.
To reference the SharePoint Client Side Object Model (CSOM) in your solution, use NuGet packages.
Manage dependencies easily and ensure your solution is using the latest version of the CSOM library with NuGet packages.
Get the latest version of the CSOM package at the SharePoint Client-side Object Model Libraries with the ID Microsoft.SharePointOnline.CSOM.
Check Get to know SharePoint REST service for instructions on REST API.
Creates an AMR job to read all the metadata of the specified SharePoint URL and its children into the specified manifest container.
public SPAsyncReadJobInfo CreateSPAsyncReadJob(String url,
SPAsyncReadOptions readOptions,
EncryptionOption encryptionOption,
string azureContainerManifestUri,
string azureQueueReportUri)Required.
A String value containing the full path URL of the root path of the SharePoint List, files/folders, or Document Library to read. AMR API returns all the metadata of files, folders, and root objects, including subfolders and any children content.
This example url returns all metadata of Shared Document, and its children:
https://www.contoso.com/Shared%20DocumentRequired.
A SPAsyncReadOptions structure, with readOption values specifying the types of metadata to read.
Optional.
A Bool value to indicate if AMR API reads multiple versions of files and List Items.
Default value is false. When absent or set to false, AMR API only reads the latest version of items.
Optional.
A Bool value to indicate if AMR API reads Users and Groups information related to a Site.
Default value is false.
AMR API reads Users and Groups as Authors or Modifiers as part of the metadata of the objects.
If set to true, AMR API reads all Users in Site Collections. When reading multiple Document Libraries under the same Site Collection, the same Users and Group may appear in the read package multiple times.
Optional.
A Bool value to indicate if AMR API reads only the metadata of the direct descendants.
Default value is false.
If set to true, AMR API reads only the metadata of the direct descendants.
Use this readOption along with IncludeSecurity readOption together to improve performance when reading metadata from a Document Library containing large number of items, as described in Best practice to avoid slow performance.
Optional.
Default value is false.
When set to false, AMR API reads basic metadata:
- List
- Folder
- File
- List Item
- Roles
- Role Assignments
When set to true, AMR API reads all metadata available:
For Files:
- Web Part
- Web Part personalization
- Links
- Version events
- Event receivers
- Attachment metadata
For Lists:
- Custom actions
- List shortcuts
For List Items:
- Comments
- Documents set links
- Activities
- List Item shortcuts
Including extended metadata slows down the read significantly. For file share migrations, keep the default value false. Set to true only when necessary, for complex migration projects.
Optional.
A Bool value to indicate if permissions read is needed. Default value is false.
When set to true, AMR API reads permission metadata in RoleAssignments tags in Manifest.xml files. The file includes all distinguished permission metadata for each read SharePoint object, along with property ScopeId.
IncludeSecurity reads the full list of all Users and Groups on the target Site. Optionally use IncludePermission to read permission metadata, if needed. There are four possible combinations for using both readOption:
IncludeSecurity=true,IncludePermission=false: reads the full list of all Users and Groups information of the target Site, without permissions.IncludeSecurity=false,IncludePermission=true: reads permissions with a list of corresponding User and Group information, related to the permissions read.IncludeSecurity=true,IncludePermission=true: reads permissions with the full list of all User and Group information of the target Site.IncludeSecurity=false,IncludePermission=false: reads no permissions, Users or Groups information.
Optional.
A Integer value containing the changeToken item.
By default, when no StartChangeToken is provided, CreateSPAsyncReadJob method returns all items available, based on the parameters. A CurrentChangeToken value is returned every time.
To read only the items that changed since last read, set a StartChangeToken in subsequent calls to CreateSPAsyncReadJob. Use CurrentChangeToken returned from last call as the value of StartChangeToken.
AMR API returns an error and stops the read, if it receives an invalid StartChangeToken value.
Be careful when using this feature with large number of items. The read job could run for extended duration. AMR API cancels jobs that run over 10 minutes to protect the SharePoint infrastructure.
Optional.
A EncryptionOption object, containing the AES256CBCKey used to decrypt the output.
By default, AMR API doesn't encrypt the output and event queue. If set with AES256CBCKey, AMR API encrypts the output with the key supplied.
See [EncryptionOption](/dotnet/api/microsoft.sharepoint.client.encryptionoption) class for details.
Required.
A String value, which is the destination URL of the Azure Blob Storage Container containing the output manifest package.
See Azure for instructions of using Azure Blob Storage Container in migration.
Required.
A String value, which is the URL of the Azure Queue to receive read status messages.
Share azureQueueReportUri among different jobs if necessary. AMR API returns JobID to identify individual jobs created.
See Azure for instructions of using Azure Queue in migration. Check Migration events in Azure Queue for types of events.
A Guid value, which contains Job ID, the unique identifier of the migration job. The method returns a null value, if it fails to create the job.
AMR API generates a JobEnd event when it estimates item count for each url. Check Events for details.
A Uri value that contains the URL to access the Azure Blob Storage Container, which contains the metadata read.
A Uri value that contains the URL of the Azure Queue used for read status.
A Byte Array value that contains the AES-CBC Key for decrypting the manifest files and messages in the Azure Queue.
Creates an AMR job to read all the metadata of all SharePoint URLs specified, and their children into the specified manifest container.
public SPAsyncReadJobInfo CreateSPAsyncReadJobWithMultiUrl(
String[] urls,
SPAsyncReadOptions readOptions,
EncryptionOption encryptionOption,
String azureContainerManifestUri,
String azureQueueReportUri)See CreateSPAsyncReadJob method for details of readOptions, encryptionOption, azureContainerManifestUri, and azureQueueReportUri.
Required.
A Uri Array containing the full path URLs of the root paths of the SharePoint Lists, files/folders, or Document Libraries to read. AMR API returns all the metadata of files, folders, and root objects, including subfolders and any children content.
Specify multiple URLs when needed. Aggravated call with multiple URLs may improve the performance. See Performance for details.
The changeToken refers to a time before the start of the current change log.
The change log is limited to 60 days immediately before the current date. AMR API returns this error code when the specified changeToken refers to a time outside the 60 day window.
Operation canceled.
AMR API received a cancellation request from the client and cancels the read operation.