| title | description | ms.date | ms.author | author | manager | audience | ms.subservice | ms.topic | ms.localizationpriority | ms.collection | ||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
SharePoint Migration API Reference Guide |
This article provides in-depth information on how to use the SharePoint Migration API. |
04/28/2024 |
ranren |
underreview |
dapodean |
ITPro |
migration-tool |
article |
high |
|
This guide describes the usage of SharePoint Migration API, which imports content into SharePoint, based on manifest files.
Migration API supports both SharePoint Client Side Object Model (CSOM) and 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 a new migration import job with the import package specified in azureContainerSourceUri parameter.
public Guid CreateMigrationJobEncrypted(
Guid gWebId,
string azureContainerSourceUri,
string azureContainerManifestUri,
string azureQueueReportUri,
EncryptionOption AES256CBCKey
)POST https://{site_url}/_api/site/CreateMigrationJobEncrypted
{
"options": {
"AES256CBCKey": "000000000000000000000000000000000000000000000000000000="
},
"gWebId": "00000000-0000-0000-0000-000000000000",
"azureContainerSourceUri": "https://tenant.blob.core.windows.net:443/00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000=rw",
"azureContainerManifestUri": "https://tenant.blob.core.windows.net:443/00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000=rw"
}Required.
A String value that contains the unique identifier of the destination web targeted for the package import. The import package itself specifies additional information and identifiers for the import. You can programmatically find this identifier by querying the target web using CSOM calls.
Required.
A String value that contains the valid URI, including the SAS token, to access the Azure Blob Storage Container that contains the binary files of type block.
See Use Azure Blob Storage Containers and Azure Queues with SharePoint Migration API for instructions on using Azure Blob Storage Containers in migration.
When using content containers not provided by this method, Migration API requires Read, and List permissions only. Ensure that the start time of the SAS token is set at or before the job submission. Also, when setting the expiration time, allow a reasonable duration for the import process to complete.
Migration API doesn't require List permission from containers provisioned with ProvisionMigrationContainers method.
Required.
A String value that contains the valid URI, including the SAS token, to access the Azure Blob Storage Container, which contains the block blobs for the manifest and other packages describing XML files. Migration API writes log to this container. This container can't be the same as the one used for the azureContainerSourceUri.
See Use Azure Blob Storage Containers and Azure Queues with SharePoint Migration API for instructions on using Azure Blob Storage Containers in migration.
When using content containers not provided by this method, Migration API requires Read, List, and Write permissions only. Ensure that the start time of the SAS token is set at or before the job submission. Also, when setting the expiration time, allow a reasonable duration for the import process to complete.
Optional.
A String value that contains the valid URL, including the SAS token, to access the user-provided Azure Queue for migration job progress. Use null if receiving import status updates isn't necessary.
If this value isn't null, and the SAS token contains the correct permissions, Migration API writes import status updates to the queue at the URL provided.
Share the notification queue among multiple migration jobs. Migration API identifies each job with unique Job ID values in the notification queue.
See Azure for instructions on using Azure Queue in migration. Check Migration events in Azure Queue for types of events.
Requires Add, Read, and Update permissions only. If the SAS token has other permissions, the migration job will be unable to add events to the queue.
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. Use Job ID to query the status of migration jobs with GetMigrationJobStatus method.
Guid MigrationJobId = TargetSite.CreateMigrationJob(
TargetWebId,
azureContainerSourceUri,
azureContainerManifestUri,
azureQueueReportUri);Creates a new migration import job with an encrypted PRIME package.
Check the encryption instructions in Azure for Azure Blob Storage Container and Azure Queue encryption used.
public Guid CreateMigrationJobEncrypted(
Guid gWebId,
string azureContainerSourceUri,
string azureContainerManifestUri,
string azureQueueReportUri,
EncryptionOption AES256CBCKey
)POST https://{site_url}/_api/site/CreateMigrationJobEncrypted
{
"options": {
"AES256CBCKey": "000000000000000000000000000000000000000000000000000000="
},
"gWebId": "00000000-0000-0000-0000-000000000000",
"azureContainerSourceUri": "https://tenant.blob.core.windows.net:443/00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000=rw",
"azureContainerManifestUri": "https://tenant.blob.core.windows.net:443/00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000=rw"
}gWebID, azureContainerSourceUri, azureContainerManifestUri, and azureQueueReportUri parameters have the same requirements as in CreateMigrationJob method.
Provide EncryptionOption parameter as instructed below.
Required.
A EncryptionOption object, containing the AES256CBCKey used to decrypt the output.
Migration API encrypts the output with the AES256CBCKey key supplied.
See [EncryptionOption](https://learn.microsoft.com/en-us/dotnet/api/microsoft.sharepoint.client.encryptionoption) class for details.
See Return value in CreateMigrationJob method.
Retrieves the processing status for a designated migration job.
Migration API removes completed migration jobs from the timer job queue. Check the notification queue and/or log outputs for import results.
[ClientNS.ClientCallableMethod]
public SPMigrationJobState GetMigrationJobStatus(Guid MigrationJobId)Required.
A Guid value, which contains the migration Job ID, is returned from CreateMigrationJob.
A SPMigrationJobState object, which contains the status of the migration job.
SPMigrationJobState CurrentJobState = TargetSite.GetMigrationJobStatus(MigrationJobId);Contains members representing the status of migration jobs in the import queue.
Value: 0
The queue doesn't contain the migration job with the Job ID. The possible reasons are:
- Migration API has completed the job and removed it from the queue.
- The Job ID is invalid.
Value: 2
The queue contains the migration job. Migration API isn't processing the job.
Value: 4
The queue contains the migration job. Migration API is processing the job.