From 3f9ca3d9f5f9782e0a2f312bf22ef20388d23e6b Mon Sep 17 00:00:00 2001 From: Jihong Zuo <198350521+shiongzuo@users.noreply.github.com> Date: Sun, 15 Jun 2025 19:12:27 +0800 Subject: [PATCH 1/4] Create migration-job-progress-api-reference.md --- .../migration-job-progress-api-reference.md | 154 ++++++++++++++++++ 1 file changed, 154 insertions(+) create mode 100644 docs/apis/migration-job-progress-api-reference.md diff --git a/docs/apis/migration-job-progress-api-reference.md b/docs/apis/migration-job-progress-api-reference.md new file mode 100644 index 000000000..d383c401c --- /dev/null +++ b/docs/apis/migration-job-progress-api-reference.md @@ -0,0 +1,154 @@ +--- +title: "SharePoint Migration Job Progress API" +description: "This article explains how to retrieve migration job status with GetMigrationJobProgress API." +ms.date: 06/15/2025 +ms.author: jihongzuo +author: shiongzuo +manager: dapodean +audience: ISV +ms.subservice: migration-tool +ms.topic: article +ms.localizationpriority: high +ms.collection: + - SPMigration + - m365-collaboration +--- +# SharePoint GetMigrationJobProgress API + +After submitting a migration job—whether an import job or an Asynchronous Metadata Read (AMR) job—you can use the GetMigrationJobProgress API to track its progress. The API is available via both SDK and REST interfaces. + +It returns a sequence of job status events, including: JobQueued, JobStart, JobProgress, JobError, and JobEnd. + +# Permissions +Use application-based authentication when submitting a migration job. Ensure the application is granted with Sites.Read.All permission or higher. + +# GetMigrationJobProgress Method (SDK) +## Syntax +```csharp +public ClientResult Site.GetMigrationJobProgress( +Guid jobId, +String nextToken +) +``` + +## Parameters +| Name | Type | Required | Description | +| :--------- | :------- | :------- | :----------------------------------------------------- | +| jobId | Guid | Yes | Unique identifier of the migration job | +| nextToken | String | Yes | Token for paging position. Use "0" for initial request | + +For a completed job, requests using nextToken are idempotent—repeating the same request will consistently return the same result. + +## Return Values +| Name | Type | Description | +| :--------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------ | +| Logs | IList | Returns a collection of job status events when new progress is available, or an empty collection if there are no updates. | +| NextToken | String | Returns an updated string value when new progress is available, or the same value as the nextToken parameter if there are no updates. | + +## Example +```csharp +ClientResult result = context.Site.GetMigrationJobProgress(jobId, nextToken ?? "0"); +context.ExecuteQuery(); +IList logs = result.Value.Logs; +string newNextToken = result.Value.NextToken; +``` + +# GetMigrationJobProgress REST API +## HTTP Request +```rest +GET https://{site_url}/_api/site/GetMigrationJobProgress(jobId='{jobId}',nextToken=0) +``` + +## URI Parameters +| Name | Type | Required | Description | +| :--------- | :------- | :------- | :----------------------------------------------------- | +| jobId | Guid | Yes | Unique identifier of the migration job | +| nextToken | String | Yes | Token for paging position. Use "0" for initial request | + +## Request Headers +| Header | Required | +| :------------------------------------- | :------- | +| Authorization: Bearer {token} | Yes | +| Accept: application/json;odata=verbose | Yes | + +## Response +A JSON object when HTTP status code is 200. + +An empty JSON object when HTTP status code is other than 200. + +## Error Handling +| Status Code | Meaning | Action | +| :---------- | :------------- | :---------------------------------------------------------------------- | +| 403 | Unauthorized | Ensure the app/user has at least Sites.Read.All permission. | +| 429 | Too Many Requests | Parse Retry-After header and retry after the specified delay. | +| 500 | Internal Server Error | Parse error responses to identify internal errors. Do Not Retry. | +| 503 | Service Unavailable | Parse Retry-After header and retry after the specified delay. | + +| Internal Error Code | Meaning | +| :------------------ | :---------------------------------------------- | +| -2147213145 | Job not found | +| -2147213146 | Job status expired (valid for less than 5 days) | + +## Example +### Request Sample +```rest +GET https://contoso.sharepoint.com/_api/site/GetMigrationJobProgress(jobId=' 3e280efa-78a3-4ba1-bac6-e447aa538ca5', nextToken=0) +``` + +### Successful Response Sample +Status code: 200 +Response body: +```rest +{ + "d": { + "GetMigrationJobProgress": { + "Logs": { + "__metadata": { + "type": "Collection(Edm.String)" + }, + "results": [ + "{\"MigrationType\":\"None\",\"MigrationDirection\":\"Import\",\"SiteId\":\"48f1898f-77d9-4a1b-bddc-1f49bb6dc134\",\"DbId\":\"de6b85cd-726e-4b13-ae04-629798fddbf3\",\"TotalRetryCount\":\"0\",\"JobId\":\"3e280efa-78a3-4ba1-bac6-e447aa538ca5\",\"Time\":\"05/20/2025 09:18:48.132\",\"CorrelationId\":\"91884a0c-5ee8-4e1f-a23f-e4f7ec170182\",\"Event\":\"JobQueued\"}", + "{\"MigrationType\":\"None\",\"MigrationDirection\":\"Import\",\"SiteId\":\"48f1898f-77d9-4a1b-bddc-1f49bb6dc134\",\"WebId\":\"7206fc09-e4af-48b3-8730-ed7321396d7a\",\"DbId\":\"de6b85cd-726e-4b13-ae04-629798fddbf3\",\"FarmId\":\"f77d7b6c-ef43-4609-8fce-0e93142ce8a0\",\"ServerId\":\"44af885c-393b-4236-9417-bae7a9edc44e\",\"SubscriptionId\":\"82abb045-250e-4186-ba83-b9295930f272\",\"TotalRetryCount\":\"0\",\"JobId\":\"3e280efa-78a3-4ba1-bac6-e447aa538ca5\",\"Time\":\"05/20/2025 09:20:51.129\",\"CorrelationId\":\"7d3e7a8e-4445-4ce0-adb1-078e78cbf686\",\"Event\":\"JobStart\"}", + "{\"MigrationType\":\"None\",\"MigrationDirection\":\"Import\",\"TotalRetryCount\":\"0\",\"ObjectType\":\"ListItem\",\"Url\":\"\",\"Id\":\"cb471d5f-593f-4a63-b59e-8eae3e35b08a\",\"SourceListItemIntId\":\"3\",\"TargetListItemIntId\":\"3\",\"ErrorCode\":\"-2147286782\",\"ErrorType\":\"Microsoft.SharePoint.SPException\",\"Message\":\"Attempted to use an object that has ceased to exist. (Exception from HRESULT: 0x80030102 (STG_E_REVERTED)) \",\"JobId\":\"3e280efa-78a3-4ba1-bac6-e447aa538ca5\",\"Time\":\"05/20/2025 09:20:55.490\",\"CorrelationId\":\"7d3e7a8e-4445-4ce0-adb1-078e78cbf686\",\"Event\":\"JobError\"}", + "{\"MigrationType\":\"None\",\"MigrationDirection\":\"Import\",\"TotalRetryCount\":\"0\",\"FilesCreated\":\"0\",\"BytesProcessed\":\"0\",\"ObjectsProcessed\":\"4\",\"TotalExpectedSPObjects\":\"15\",\"TotalErrors\":\"3\",\"TotalWarnings\":\"0\",\"WaitTimeOnSqlThrottlingMilliseconds\":\"0\",\"TotalDurationInMs\":\"0\",\"CpuDurationInMs\":\"0\",\"SqlDurationInMs\":\"0\",\"SqlQueryCount\":\"0\",\"IsShallowCopy\":\"False\",\"CreatedOrUpdatedFileStatsBySize\":\"{}\",\"ObjectsStatsByType\":\"{\\\"SPUser\\\":{\\\"Count\\\":1,\\\"TotalTime\\\":124,\\\"AccumulatedVersions\\\":0,\\\"ObjectsWithVersions\\\":0},\\\"SPFolder\\\":{\\\"Count\\\":1,\\\"TotalTime\\\":153,\\\"AccumulatedVersions\\\":0,\\\"ObjectsWithVersions\\\":0},\\\"SPDocumentLibrary\\\":{\\\"Count\\\":1,\\\"TotalTime\\\":404,\\\"AccumulatedVersions\\\":0,\\\"ObjectsWithVersions\\\":0},\\\"SPFile\\\":{\\\"Count\\\":1,\\\"TotalTime\\\":0,\\\"AccumulatedVersions\\\":0,\\\"ObjectsWithVersions\\\":0},\\\"SPListItem\\\":{\\\"Count\\\":1,\\\"TotalTime\\\":1880,\\\"AccumulatedVersions\\\":0,\\\"ObjectsWithVersions\\\":0}}\",\"TotalExpectedBytes\":\"0\",\"FilesCreatedIrrespectiveOfVersions\":\"0\",\"BytesProcessedOnlyCurrentVersion\":\"0\",\"JobId\":\"3e280efa-78a3-4ba1-bac6-e447aa538ca5\",\"Time\":\"05/20/2025 09:20:57.380\",\"CorrelationId\":\"7d3e7a8e-4445-4ce0-adb1-078e78cbf686\",\"Event\":\"JobEnd\"}" + ] + }, + "NextToken": "1764", + "__metadata": { + "type": "SP.MigrationJobProgress" + } + } + } +} +``` + +### Error Response Sample +Status code: 500 +Response body: +```rest +{ + "error": { + "code": "-2147213145, Microsoft.SharePoint.SPException", + "innererror": { + "message": "Job not found", + "stacktrace": "STACK_TRACE" + }, + "message": { + "lang": "en-US", + "value": "Job not found" + } + } +} +``` + +# Best Practice +Begin with nextToken=0, store the returned token, and poll at certain intervals. This method is well-suited for long-running jobs and helps ensure no updates are missed. + +Since migration jobs typically take several minutes or more, polling every minute is advised—while adhering to the [guideline](/docs/general-development/how-to-avoid-getting-throttled-or-blocked-in-sharepoint-online.md) to avoid throttling. + +# See Also +[SharePoint Import Migration API](/docs/apis/migration-api-overview.md) + +[Migration events](/docs/apis/migration-events.md) + +[Avoid getting throttled or blocked in SharePoint Online](/docs/general-development/how-to-avoid-getting-throttled-or-blocked-in-sharepoint-online.md) From 0519ed88aa71f8ebe4ec8037237afe0578cd0d26 Mon Sep 17 00:00:00 2001 From: Jihong Zuo <198350521+shiongzuo@users.noreply.github.com> Date: Mon, 23 Jun 2025 16:27:10 +0800 Subject: [PATCH 2/4] Update migration-job-progress-api-reference.md --- .../migration-job-progress-api-reference.md | 41 ++++++++----------- 1 file changed, 17 insertions(+), 24 deletions(-) diff --git a/docs/apis/migration-job-progress-api-reference.md b/docs/apis/migration-job-progress-api-reference.md index d383c401c..be88037f0 100644 --- a/docs/apis/migration-job-progress-api-reference.md +++ b/docs/apis/migration-job-progress-api-reference.md @@ -19,11 +19,11 @@ After submitting a migration job—whether an import job or an Asynchronous Meta It returns a sequence of job status events, including: JobQueued, JobStart, JobProgress, JobError, and JobEnd. -# Permissions +## Permissions Use application-based authentication when submitting a migration job. Ensure the application is granted with Sites.Read.All permission or higher. -# GetMigrationJobProgress Method (SDK) -## Syntax +## GetMigrationJobProgress Method (SDK) +### Syntax ```csharp public ClientResult Site.GetMigrationJobProgress( Guid jobId, @@ -31,7 +31,7 @@ String nextToken ) ``` -## Parameters +### Method Parameters | Name | Type | Required | Description | | :--------- | :------- | :------- | :----------------------------------------------------- | | jobId | Guid | Yes | Unique identifier of the migration job | @@ -39,13 +39,13 @@ String nextToken For a completed job, requests using nextToken are idempotent—repeating the same request will consistently return the same result. -## Return Values +### Return Values | Name | Type | Description | | :--------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------ | | Logs | IList | Returns a collection of job status events when new progress is available, or an empty collection if there are no updates. | | NextToken | String | Returns an updated string value when new progress is available, or the same value as the nextToken parameter if there are no updates. | -## Example +### Method Usage Example ```csharp ClientResult result = context.Site.GetMigrationJobProgress(jobId, nextToken ?? "0"); context.ExecuteQuery(); @@ -53,30 +53,30 @@ IList logs = result.Value.Logs; string newNextToken = result.Value.NextToken; ``` -# GetMigrationJobProgress REST API -## HTTP Request +## GetMigrationJobProgress REST API +### HTTP Request ```rest GET https://{site_url}/_api/site/GetMigrationJobProgress(jobId='{jobId}',nextToken=0) ``` -## URI Parameters +### URI Parameters | Name | Type | Required | Description | | :--------- | :------- | :------- | :----------------------------------------------------- | | jobId | Guid | Yes | Unique identifier of the migration job | | nextToken | String | Yes | Token for paging position. Use "0" for initial request | -## Request Headers +### Request Headers | Header | Required | | :------------------------------------- | :------- | | Authorization: Bearer {token} | Yes | | Accept: application/json;odata=verbose | Yes | -## Response +### Response A JSON object when HTTP status code is 200. An empty JSON object when HTTP status code is other than 200. -## Error Handling +### Error Handling | Status Code | Meaning | Action | | :---------- | :------------- | :---------------------------------------------------------------------- | | 403 | Unauthorized | Ensure the app/user has at least Sites.Read.All permission. | @@ -89,13 +89,13 @@ An empty JSON object when HTTP status code is other than 200. | -2147213145 | Job not found | | -2147213146 | Job status expired (valid for less than 5 days) | -## Example -### Request Sample +### API Usage Example +#### Request Sample ```rest GET https://contoso.sharepoint.com/_api/site/GetMigrationJobProgress(jobId=' 3e280efa-78a3-4ba1-bac6-e447aa538ca5', nextToken=0) ``` -### Successful Response Sample +#### Successful Response Sample Status code: 200 Response body: ```rest @@ -122,7 +122,7 @@ Response body: } ``` -### Error Response Sample +#### Error Response Sample Status code: 500 Response body: ```rest @@ -141,14 +141,7 @@ Response body: } ``` -# Best Practice +## Best Practice Begin with nextToken=0, store the returned token, and poll at certain intervals. This method is well-suited for long-running jobs and helps ensure no updates are missed. Since migration jobs typically take several minutes or more, polling every minute is advised—while adhering to the [guideline](/docs/general-development/how-to-avoid-getting-throttled-or-blocked-in-sharepoint-online.md) to avoid throttling. - -# See Also -[SharePoint Import Migration API](/docs/apis/migration-api-overview.md) - -[Migration events](/docs/apis/migration-events.md) - -[Avoid getting throttled or blocked in SharePoint Online](/docs/general-development/how-to-avoid-getting-throttled-or-blocked-in-sharepoint-online.md) From 5b2d4d3caf80f4ec79820c23140bf1f10ba99aa8 Mon Sep 17 00:00:00 2001 From: Jihong Zuo <198350521+shiongzuo@users.noreply.github.com> Date: Mon, 23 Jun 2025 17:54:26 +0800 Subject: [PATCH 3/4] Update migration-job-progress-api-reference.md Revised broken links --- docs/apis/migration-job-progress-api-reference.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/apis/migration-job-progress-api-reference.md b/docs/apis/migration-job-progress-api-reference.md index be88037f0..edf953a69 100644 --- a/docs/apis/migration-job-progress-api-reference.md +++ b/docs/apis/migration-job-progress-api-reference.md @@ -144,4 +144,9 @@ Response body: ## Best Practice Begin with nextToken=0, store the returned token, and poll at certain intervals. This method is well-suited for long-running jobs and helps ensure no updates are missed. -Since migration jobs typically take several minutes or more, polling every minute is advised—while adhering to the [guideline](/docs/general-development/how-to-avoid-getting-throttled-or-blocked-in-sharepoint-online.md) to avoid throttling. +Since migration jobs typically take several minutes or more, polling every minute is advised—while adhering to the [guideline](https://learn.microsoft.com/en-us/sharepoint/dev/general-development/how-to-avoid-getting-throttled-or-blocked-in-sharepoint-online) to avoid throttling. + +## See Also +[SharePoint Migration API](https://learn.microsoft.com/en-us/sharepoint/dev/apis/migration-api-overview) + +[Migration Events](https://learn.microsoft.com/en-us/sharepoint/dev/apis/migration-events) From 043845b79a5710e92747ecf8444a02936c477558 Mon Sep 17 00:00:00 2001 From: Jihong Zuo <198350521+shiongzuo@users.noreply.github.com> Date: Mon, 23 Jun 2025 18:10:14 +0800 Subject: [PATCH 4/4] Update migration-job-progress-api-reference.md Replace with relative links --- docs/apis/migration-job-progress-api-reference.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/apis/migration-job-progress-api-reference.md b/docs/apis/migration-job-progress-api-reference.md index edf953a69..e4f7a5d1c 100644 --- a/docs/apis/migration-job-progress-api-reference.md +++ b/docs/apis/migration-job-progress-api-reference.md @@ -144,9 +144,9 @@ Response body: ## Best Practice Begin with nextToken=0, store the returned token, and poll at certain intervals. This method is well-suited for long-running jobs and helps ensure no updates are missed. -Since migration jobs typically take several minutes or more, polling every minute is advised—while adhering to the [guideline](https://learn.microsoft.com/en-us/sharepoint/dev/general-development/how-to-avoid-getting-throttled-or-blocked-in-sharepoint-online) to avoid throttling. +Since migration jobs typically take several minutes or more, polling every minute is advised—while adhering to the [guideline](https://aka.ms/spo429) to avoid throttling. ## See Also -[SharePoint Migration API](https://learn.microsoft.com/en-us/sharepoint/dev/apis/migration-api-overview) +[SharePoint Migration API](migration-api-overview.md) -[Migration Events](https://learn.microsoft.com/en-us/sharepoint/dev/apis/migration-events) +[Migration Events](migration-events.md)