Merge pull request #384 from PlagueHO/Issue-376

Added IfMatch to Set-CosmosDbDocument Function - Fixes #376

CHANGELOG.md

@@ -10,6 +10,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Added `Get-CosmosDbDocumentJson` function - Fixes [Issue #370](https://github.com/PlagueHO/CosmosDB/issues/370).
+- Added `IfMatch` alias for `Etag` parameter on `Set-CosmosDbDocument`
+  function - Fixes [Issue #376](https://github.com/PlagueHO/CosmosDB/issues/376).
+- Added `Get-CosmosDbCosmosDbResponseHeader` function and refactored
+  `Get-CmosmosDbContinuationToken` to use it.
+- Added documentation and examples showing how to get the progress of an
+  index transformation - Fixes [Issue #369](https://github.com/PlagueHO/CosmosDB/issues/369).
 
 ### Changed
 

README.md

@@ -447,6 +447,17 @@ $indexingPolicy = New-CosmosDbCollectionIndexingPolicy -Automatic $true -Indexin
 Set-CosmosDbCollection -Context $cosmosDbContext -Id 'MyExistingCollection' -IndexingPolicy $indexingPolicy
 ```
 
+After updating a collection with an indexing policy it will take some
+time to transform the index. To retrieve the progress of the index
+transformation, call the `Get-CosmosDbCollection` function and then
+evaluate the value of the
+
+```powershell
+PS C:\> $ResponseHeader = $null
+PS C:\> $collections = Get-CosmosDbCollection -Context $cosmosDbContext -Id 'MyExistingCollection' -ResponseHeader ([ref] $ResponseHeader)
+PS C:\> $indexUpdateProgress = Get-CosmosDbResponseHeaderAttribute -ResponseHeader $ResponseHeader -HeaderName 'x-ms-documentdb-collection-index-transformation-progress'
+```
+
 #### Creating a Collection with a custom Indexing Policy using JSON
 
 If the `New-CosmosDbCollection*` functions don't enable you to build

docs/CosmosDB.md

@@ -91,6 +91,10 @@ Return the resource path for a permission object.
 
 Return the stored procedures for a Cosmos DB database collection.
 
+### [Get-CosmosDbResponseHeaderAttribute](Get-CosmosDbResponseHeaderAttribute.md)
+
+Return an attribute from a response header object.
+
 ### [Get-CosmosDbStoredProcedureResourcePath](Get-CosmosDbStoredProcedureResourcePath.md)
 
 Execute a new stored procedure for a collection in a Cosmos DB

docs/Get-CosmosDbCollection.md

@@ -65,7 +65,7 @@ PS C:\> $collections = Get-CosmosDbCollection -Context $cosmosDbContext -MaxItem
 PS C:\> $continuationToken = Get-CosmosDbContinuationToken -ResponseHeader $ResponseHeader
 ```
 
-Get the first 5 collection from the the database storing a continuation
+Get the first 5 collections from the the database storing a continuation
 token that can be used to retrieve further blocks of collections.
 
 ### Example 4
@@ -77,6 +77,22 @@ PS C:\> $collections = Get-CosmosDbCollection -Context $cosmosDbContext -MaxItem
 Get the next 5 collections in the database using the continuation token found
 in the headers from the previous example.
 
+### Example 5
+
+```powershell
+PS C:\> $ResponseHeader = $null
+PS C:\> $indexStringRange = New-CosmosDbCollectionIncludedPathIndex -Kind Range -DataType String -Precision -1
+PS C:\> $indexNumberRange = New-CosmosDbCollectionIncludedPathIndex -Kind Range -DataType Number -Precision -1
+PS C:\> $indexIncludedPath = New-CosmosDbCollectionIncludedPath -Path '/*' -Index $indexStringRange, $indexNumberRange
+PS C:\> $newIndexingPolicy = New-CosmosDbCollectionIndexingPolicy -Automatic $true -IndexingMode Consistent -IncludedPath $indexIncludedPath
+PS C:\> Set-CosmosDbCollection -Context $cosmosDbContext -Id 'MyExistingCollection' -IndexingPolicy $newIndexingPolicy
+PS C:\> $collections = Get-CosmosDbCollection -Context $cosmosDbContext -Id 'MyExistingCollection' -ResponseHeader ([ref] $ResponseHeader)
+PS C:\> $indexUpdateProgress = Get-CosmosDbContinuationToken -ResponseHeader $ResponseHeader -HeaderName 'x-ms-documentdb-collection-index-transformation-progress'
+```
+
+Update a collection with a new indexing policy and retrieve the index transformation
+progress.
+
 ## PARAMETERS
 
 ### -Account
@@ -222,7 +238,7 @@ hashtable that contains any headers returned by the request.
 ```yaml
 Type: PSReference
 Parameter Sets: (All)
-Aliases:
+Aliases: ResultHeaders
 
 Required: False
 Position: Named

docs/Get-CosmosDbContinuationToken.md

@@ -39,7 +39,7 @@ PS C:\> $documents = Get-CosmosDbDocument -Context $cosmosDbContext -CollectionI
 PS C:\> $continuationToken = Get-CosmosDbContinuationToken -ResponseHeader $ResponseHeader
 ```
 
-Return the continuation token from the Get-CosmosDbDocument reponse headers.
+Return the continuation token from the Get-CosmosDbDocument response headers.
 
 ## PARAMETERS
 

docs/Get-CosmosDbResponseHeaderAttribute.md

@@ -0,0 +1,100 @@
+---
+external help file: CosmosDB-help.xml
+Module Name: CosmosDB
+online version:
+schema: 2.0.0
+---
+
+# Get-CosmosDbContinuationToken
+
+## SYNOPSIS
+
+Return an attribute from a response header object.
+
+## SYNTAX
+
+```powershell
+Get-CosmosDbResponseHeaderAttribute [-HeaderName] <String> [-ResponseHeader] <Object> [<CommonParameters>]
+```
+
+## DESCRIPTION
+
+This function takes a response header object that is generated by the ResponseHeader
+reference parameter in the Get-CosmosDbCollection or Get-CosmosDbDocument functions
+and returns an attribute matching the HeaderName.
+
+If the header is missing or empty in the ResponseHeader then an empty string will
+be returned.
+
+## EXAMPLES
+
+### Example 1
+
+### Example 5
+
+```powershell
+PS C:\> $ResponseHeader = $null
+PS C:\> $indexStringRange = New-CosmosDbCollectionIncludedPathIndex -Kind Range -DataType String -Precision -1
+PS C:\> $indexNumberRange = New-CosmosDbCollectionIncludedPathIndex -Kind Range -DataType Number -Precision -1
+PS C:\> $indexIncludedPath = New-CosmosDbCollectionIncludedPath -Path '/*' -Index $indexStringRange, $indexNumberRange
+PS C:\> $newIndexingPolicy = New-CosmosDbCollectionIndexingPolicy -Automatic $true -IndexingMode Consistent -IncludedPath $indexIncludedPath
+PS C:\> Set-CosmosDbCollection -Context $cosmosDbContext -Id 'MyExistingCollection' -IndexingPolicy $newIndexingPolicy
+PS C:\> $collections = Get-CosmosDbCollection -Context $cosmosDbContext -Id 'MyExistingCollection' -ResponseHeader ([ref] $ResponseHeader)
+PS C:\> $indexUpdateProgress = Get-CosmosDbResponseHeaderAttribute -ResponseHeader $ResponseHeader -HeaderName 'x-ms-documentdb-collection-index-transformation-progress'
+```
+
+Update a collection with a new indexing policy and retrieve the index transformation
+progress.
+
+## PARAMETERS
+
+### -HeaderName
+
+The name of the Header to return from the Response Headers.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Aliases:
+
+Required: True
+Position: 0
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -ResponseHeader
+
+The Response Header object generated by Get-CosmosDbCollection or Get-CosmosDbDocument
+functions.
+
+```yaml
+Type: Object
+Parameter Sets: (All)
+Aliases:
+
+Required: True
+Position: 0
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### CommonParameters
+
+This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable,
+-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable,
+-Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
+
+## INPUTS
+
+### None
+
+## OUTPUTS
+
+### System.String
+
+## NOTES
+
+## RELATED LINKS

docs/Set-CosmosDbDocument.md

@@ -197,7 +197,7 @@ this parameter use the *_etag* field from the received document.
 ```yaml
 Type: String
 Parameter Sets: (All)
-Aliases:
+Aliases: IfMatch
 
 Required: False
 Position: Named

source/Public/collections/Get-CosmosDbCollection.ps1

@@ -47,6 +47,7 @@ function Get-CosmosDbCollection
         [System.String]
         $ContinuationToken,
 
+        [Alias("ResultHeaders")]
         [Parameter()]
         [ref]
         $ResponseHeader

source/Public/documents/Get-CosmosDbDocument.ps1

@@ -94,7 +94,6 @@ function Get-CosmosDbDocument
 
     $documentJson = Get-CosmosDbDocumentJson @PSBoundParameters
 
-    Write-Verbose -Message ($documentJson | Out-String) -Verbose
     $documents = ConvertFrom-Json -InputObject $documentJson
 
     if ([System.String]::IsNullOrEmpty($Id))

source/Public/documents/Set-CosmosDbDocument.ps1

@@ -56,6 +56,7 @@ function Set-CosmosDbDocument
         [System.Object[]]
         $PartitionKey,
 
+        [Alias('IfMatch')]
         [Parameter()]
         [ValidateNotNullOrEmpty()]
         [System.String]

source/Public/utils/Get-CosmosDbContinuationToken.ps1

@@ -11,7 +11,9 @@ function Get-CosmosDbContinuationToken
         $ResponseHeader
     )
 
-    $continuationToken = [System.String] $ResponseHeader.'x-ms-continuation'
+    $continuationToken = Get-CosmosDbResponseHeaderAttribute `
+        -ResponseHeader $ResponseHeader `
+        -HeaderName 'x-ms-continuation'
 
     if ([System.String]::IsNullOrEmpty($continuationToken))
     {

source/Public/utils/Get-CosmosDbResponseHeaderAttribute.ps1

@@ -0,0 +1,20 @@
+function Get-CosmosDbResponseHeaderAttribute
+{
+
+    [CmdletBinding()]
+    [OutputType([System.String])]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [System.Object]
+        $ResponseHeader,
+
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [System.Object]
+        $HeaderName
+    )
+
+    return ([System.String] $ResponseHeader.$HeaderName)
+}

tests/Unit/CosmosDB.utils.Tests.ps1

@@ -1358,6 +1358,66 @@ console.log("done");
         }
     }
 
+    Describe 'Get-CosmosDbResponseHeaderAttribute' -Tag 'Unit' {
+        It 'Should exist' {
+            { Get-Command -Name Get-CosmosDbResponseHeaderAttribute -ErrorAction Stop } | Should -Not -Throw
+        }
+
+        Context 'When called with a response header that contains a header-value attribute with value result' {
+            It 'Should not throw exception' {
+                $getCosmosDbResponseHeaderAttirbuteParameters = @{
+                    ResponseHeader = @{
+                        'header-value' = 'result'
+                    }
+                    HeaderName = 'header-value'
+                    Verbose        = $true
+                }
+
+                { $script:result = Get-CosmosDbResponseHeaderAttribute @getCosmosDbResponseHeaderAttirbuteParameters } | Should -Not -Throw
+            }
+
+            It 'Should return result' {
+                $script:result | Should -Be 'result'
+            }
+        }
+
+        Context 'When called with a response header that contains a header-value attribute with a blank value' {
+            It 'Should not throw exception' {
+                $getCosmosDbResponseHeaderAttirbuteParameters = @{
+                    ResponseHeader = @{
+                        'header-value' = ''
+                    }
+                    HeaderName = 'header-value'
+                    Verbose        = $true
+                }
+
+                { $script:result = Get-CosmosDbResponseHeaderAttribute @getCosmosDbResponseHeaderAttirbuteParameters } | Should -Not -Throw
+            }
+
+            It 'Should return null' {
+                $script:result | Should -BeNullOrEmpty
+            }
+        }
+
+        Context 'When called with a response header that does not contain a header-value attribute' {
+            It 'Should not throw exception' {
+                $getCosmosDbResponseHeaderAttirbuteParameters = @{
+                    ResponseHeader = @{
+                        'not-value' = 'value does not matter'
+                    }
+                    HeaderName = 'header-value'
+                    Verbose      = $true
+                }
+
+                { $script:result = Get-CosmosDbResponseHeaderAttribute @getCosmosDbResponseHeaderAttirbuteParameters } | Should -Not -Throw
+            }
+
+            It 'Should return null' {
+                $script:result | Should -BeNullOrEmpty
+            }
+        }
+    }
+
     Describe 'Get-CosmosDbContinuationToken' -Tag 'Unit' {
         It 'Should exist' {
             { Get-Command -Name Get-CosmosDbContinuationToken -ErrorAction Stop } | Should -Not -Throw