CosmosDB REST

Microsoft Documentation

https://learn.microsoft.com/en-us/rest/api/cosmos-db/

1.0 URL and resource types

1.1 CosmosDB structure

Databases

URL: $base/dbs
Resource Link: dbs
Resource Type: dbs

Collections

URL: $base/dbs/<dbname>/colls
Resource Link: dbs/<dbname>
Resource Type: colls

Docs

URL: $base/dbs/<dbname>/colls/<coll-id>/docs
Resource Link: dbs/<dbname>/colls/<coll-id>
Resource Type: docs

1.2 Authentication

Resource Types

• Database operations: dbs
• Container operations: colls
• Stored Procedures: sprocs
• User Defined Functions: udfs
• Triggers: triggers
• Users: users
• Permissions: permissions
• Item level operations: docs

1.3 Resource Link

• If the operation is performed against a specific resource then the value is the link to that resource. Examples:

  • For Get Database use: dbs/{databaseId}
  • For Get Document use: dbs/{databaseId}/colls/{containerId}/docs/{docId}

• If the operation is performed against a set of resources (List, Create, Query) then the value is the link of the parent resource. Examples:

  • For Create Document use: dbs/{databaseId}/colls/{containerId}
  • For Create Stored Procedure use: dbs/{databaseId}/colls/{containerId}
  • For Create a Container use: dbs/{databaseId}
  • For Create Database use: "" -> an empty string since Databases do not have a parent resource

2.0 Automation approach

2.1 PowerShell Script

using namespace System.Net
 
# Input bindings are passed in via param block.
param($Request, $TriggerMetadata)
 
# Write to the Azure Functions log stream.
Write-Host "PowerShell HTTP trigger function processed a request."
 
# function to sign the request
function Generate-MasterKeyAuthorizationSignature {
    param (
        [Parameter(Mandatory)]
        [string]$ResourceType,
 
		# To list the databases, resourcelink has to be empty
        [Parameter(Mandatory)]
        [AllowEmptyString()]
        [string]$ResourceLink,
        [Parameter(Mandatory)]
        [string]$Key
    )
 
    $keyType = "master"
    $tokenVersion = "1.0"
 
	# Payload has to be lower case !!!
    $payload = (
        $Verb.ToLowerInvariant() + "`n" +
        $ResourceType.ToLowerInvariant() + "`n" +
        $ResourceLink + "`n" +
        $Date.ToLowerInvariant() + "`n`n"
    )
    Write-Host $payload
    $keyBytes = [Convert]::FromBase64String($Key)
    $hmacSha256 = [System.Security.Cryptography.HMACSHA256]::new($keyBytes)
 
    $payloadBytes = [System.Text.Encoding]::UTF8.GetBytes($payload)
    $hashPayload = $hmacSha256.ComputeHash($payloadBytes)
    $signature = [Convert]::ToBase64String($hashPayload)
 
    $authSet = [System.Net.WebUtility]::UrlEncode(
        "type=$keyType&ver=$tokenVersion&sig=$signature"
    )
 
    return $authSet
}
 
$baseURI = "https://<cosmosdb>.documents.azure.com"
$verb = "GET"
$restype = "dbs"
$reslink = ""
$date = (Get-Date).ToUniversalTime().ToString("ddd, dd MMM yyyy HH:mm:ss 'GMT'", [System.Globalization.CultureInfo]::InvariantCulture)
 
$hashedSignature = Generate-MasterKeyAuthorizationSignature -Verb $verb -ResourceType $restype -ResourceLink $reslink -Date $date -Key $key
 
Write-Host $hashedSignature
 
$URI = "$baseURI/dbs"
 
$Headers = @{
        'authorization' = $hashedSignature
        'x-ms-date' = $date
        'x-ms-version' = '2018-12-31'
    }
 
$dbs = Invoke-RestMethod -Method $verb -Uri $URI -Headers $Headers
$body = $dbs
 
Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = [HttpStatusCode]::OK
    Body = $body
})  

2.2 Usage

.\Extract_CosmosDB_Data.ps1 `
					-ResourceType dbs `
					-ResourceLink dbs `
					-Key "<key>"

  "Databases": [{
      "id": "cosmosdb1",
    }],
  "_count": 1

.\Extract_CosmosDB_Data.ps1 `
					-ResourceType colls `
					-ResourceLink "dbs/cosmosdb1" `
					-Key "<key>"

  "DocumentCollections": [{
      "id": "collection1",
      ]},

.\Extract_CosmosDB_Data.ps1 `
					-ResourceType docs `
					-ResourceLink "dbs/cosmosdb1/collection1" `
					-Key "<key>"

  "Documents": [
    {
      "id": "78b2a856-d357-47ac-8789-7937ada5d90f",
      "credentials": {
        "Appid": "fe90c342-bd9f-402a-9bd3-1ebbd7765459",
        "ClientSecret": "xKT8Q~1lzqOIXRNX8jr_AZ3BfGXQ5zrdq2TDlbM_",
        "TenantId": "dcd3568d-d88d-49aa-bcab-405491ae156d"
      },