Initially, the CSOM API was the only method available to upload documents to SharePoint Online. CSOM is a comprehensive API that is used for application development and administration. It is a great tool for a myriad scenarios, but it is not specialized for content migrations. When used for this purpose, we can go over the API throttling limits (Microsoft has purposely not put a specific number to this as it depends on multiple factors). Your scripts might get temporarily blocked (requests will get a 429 Too Many Requests HTTP error), and if the misuse continues for an extended period of time, your tenant might get blocked altogether (503 Service Unavailable). The tenant administrator would have to take action in this case.

Moreover, the bandwidth allocated for the CSOM API will allow you to upload approximately 1 GB/hour only (depending on multiple factors such as the file size, the number of files, networking, and concurrent API usage), which makes it impractical for large content migrations.

In the next sections, you will explore faster and easier approaches to bulk migrations, yet the CSOM API remains relevant in this scenario. This is because at the time of writing, it is the only method that allows metadata modification. It is also worth mentioning that CSOM changes are reflected immediately, whereas updates through the other methods will take some time to be effective due to the architecture of the process.

The following sample shows how to upload a file and set its metadata. Refer to Chapter 4, Managing SharePoint Online Using PowerShell for additional information on CSOM scripting. This method will be used for small migrations or to set the file metadata:

$siteUrl = "https://mytest321.sharepoint.com/personal/admin1";

$clientContext = New-Object Microsoft.SharePoint.Client.ClientContext($siteUrl) 
$credentials = New-Object Microsoft.SharePoint.Client.SharePointOnlineCredentials($spoCreds.UserName, $spoCreds.Password) 
$clientContext.Credentials = $credentials 

$stream = [System.IO.File]::OpenRead('c:tempfileToMigrate.xml')
$overwrite = $true

$fileUrl = '/personal/admin1/Documents/file.xml'

[Microsoft.SharePoint.Client.File]::SaveBinaryDirect($clientContext, $fileUrl, $stream, $overwrite) 

$listItem = $clientContext.Web.GetFileByServerRelativeUrl($fileUrl).ListItemAllFields
$listItem["Title"] = 'Updated via script'
$listItem.Update()

$clientContext.ExecuteQuery()