From f471ea1b6086563788c2788d65654c33181c8a22 Mon Sep 17 00:00:00 2001 From: Daniel Scott-Raynsford Date: Sun, 31 May 2020 18:55:02 +1200 Subject: [PATCH 1/2] Added IfMatch alias --- CHANGELOG.md | 2 ++ docs/Set-CosmosDbDocument.md | 2 +- source/Public/documents/Set-CosmosDbDocument.ps1 | 1 + 3 files changed, 4 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 66fb6f1c..aba98aa4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,8 @@ 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). ### Changed diff --git a/docs/Set-CosmosDbDocument.md b/docs/Set-CosmosDbDocument.md index 72a63b70..4c7d0f97 100644 --- a/docs/Set-CosmosDbDocument.md +++ b/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 diff --git a/source/Public/documents/Set-CosmosDbDocument.ps1 b/source/Public/documents/Set-CosmosDbDocument.ps1 index ac70a22f..c710beb2 100644 --- a/source/Public/documents/Set-CosmosDbDocument.ps1 +++ b/source/Public/documents/Set-CosmosDbDocument.ps1 @@ -56,6 +56,7 @@ function Set-CosmosDbDocument [System.Object[]] $PartitionKey, + [Alias('IfMatch')] [Parameter()] [ValidateNotNullOrEmpty()] [System.String] From 078a4fe4dc29d2b214a880089983b1fa4ecdb51e Mon Sep 17 00:00:00 2001 From: Daniel Scott-Raynsford Date: Sun, 31 May 2020 20:18:42 +1200 Subject: [PATCH 2/2] Added documentation and examples showing how to get the progress of an index transformation --- CHANGELOG.md | 4 + README.md | 11 ++ docs/CosmosDB.md | 4 + docs/Get-CosmosDbCollection.md | 20 +++- docs/Get-CosmosDbContinuationToken.md | 2 +- docs/Get-CosmosDbResponseHeaderAttribute.md | 100 ++++++++++++++++++ .../collections/Get-CosmosDbCollection.ps1 | 1 + .../Public/documents/Get-CosmosDbDocument.ps1 | 1 - .../utils/Get-CosmosDbContinuationToken.ps1 | 4 +- .../Get-CosmosDbResponseHeaderAttribute.ps1 | 20 ++++ tests/Unit/CosmosDB.utils.Tests.ps1 | 60 +++++++++++ 11 files changed, 222 insertions(+), 5 deletions(-) create mode 100644 docs/Get-CosmosDbResponseHeaderAttribute.md create mode 100644 source/Public/utils/Get-CosmosDbResponseHeaderAttribute.ps1 diff --git a/CHANGELOG.md b/CHANGELOG.md index aba98aa4..55f3faad 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - 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 diff --git a/README.md b/README.md index 1135d4e0..cf9c1b4d 100644 --- a/README.md +++ b/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 diff --git a/docs/CosmosDB.md b/docs/CosmosDB.md index bab9a5aa..cdea2b5b 100644 --- a/docs/CosmosDB.md +++ b/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 diff --git a/docs/Get-CosmosDbCollection.md b/docs/Get-CosmosDbCollection.md index 4a649a28..8eed53a4 100644 --- a/docs/Get-CosmosDbCollection.md +++ b/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 diff --git a/docs/Get-CosmosDbContinuationToken.md b/docs/Get-CosmosDbContinuationToken.md index 80a38567..9627ffa4 100644 --- a/docs/Get-CosmosDbContinuationToken.md +++ b/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 diff --git a/docs/Get-CosmosDbResponseHeaderAttribute.md b/docs/Get-CosmosDbResponseHeaderAttribute.md new file mode 100644 index 00000000..480a59ce --- /dev/null +++ b/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] [-ResponseHeader] [] +``` + +## 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 diff --git a/source/Public/collections/Get-CosmosDbCollection.ps1 b/source/Public/collections/Get-CosmosDbCollection.ps1 index fef1d3ab..9cbc1d49 100644 --- a/source/Public/collections/Get-CosmosDbCollection.ps1 +++ b/source/Public/collections/Get-CosmosDbCollection.ps1 @@ -47,6 +47,7 @@ function Get-CosmosDbCollection [System.String] $ContinuationToken, + [Alias("ResultHeaders")] [Parameter()] [ref] $ResponseHeader diff --git a/source/Public/documents/Get-CosmosDbDocument.ps1 b/source/Public/documents/Get-CosmosDbDocument.ps1 index 2d60d320..315783ca 100644 --- a/source/Public/documents/Get-CosmosDbDocument.ps1 +++ b/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)) diff --git a/source/Public/utils/Get-CosmosDbContinuationToken.ps1 b/source/Public/utils/Get-CosmosDbContinuationToken.ps1 index 832ef89e..1edeb4df 100644 --- a/source/Public/utils/Get-CosmosDbContinuationToken.ps1 +++ b/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)) { diff --git a/source/Public/utils/Get-CosmosDbResponseHeaderAttribute.ps1 b/source/Public/utils/Get-CosmosDbResponseHeaderAttribute.ps1 new file mode 100644 index 00000000..f52d65a6 --- /dev/null +++ b/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) +} diff --git a/tests/Unit/CosmosDB.utils.Tests.ps1 b/tests/Unit/CosmosDB.utils.Tests.ps1 index 0b15b2a1..66b168e0 100644 --- a/tests/Unit/CosmosDB.utils.Tests.ps1 +++ b/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