@@ -3,11 +3,22 @@ function Update-PfbLegalHoldEntity {
33 . SYNOPSIS
44 Updates a held entity under a legal hold on the FlashBlade.
55 . DESCRIPTION
6- The Update-PfbLegalHoldEntity cmdlet modifies the properties of an entity that is
7- subject to a legal hold on the connected Pure Storage FlashBlade. Identify the
8- held entity by name and supply the changed properties via Attributes.
6+ The Update-PfbLegalHoldEntity cmdlet applies or releases a legal hold over a
7+ file-system path on the connected Pure Storage FlashBlade. `released` is required
8+ by the API, so -Released must always be supplied: `$true` releases the hold,
9+ `$false` applies it.
10+
11+ A held entity has no name of its own -- `LegalHoldHeldEntity` carries only
12+ `file_system`, `legal_hold`, `path` and `status` -- so it is addressed by the
13+ file system plus the path, together with -Recursive. Measured on a live array
14+ (Purity//FB 4.8.2, REST 2.26): a request naming only the hold is rejected with
15+ "Either names or ids query parameter is required", and one naming the file system
16+ and path but omitting -Recursive is rejected with "Can't apply or release legal
17+ holds to directories without the recursive flag provided". Both directions behave
18+ identically here, so a release is symmetric with an apply rather than special.
919 . PARAMETER Name
10- The name of the held entity to update.
20+ The name of the legal hold. Sent as `names`, which the endpoint declares but which
21+ does not on its own identify a held entity -- see the description above.
1122 . PARAMETER FileSystemIds
1223 The IDs of the file systems whose held entities to update.
1324 . PARAMETER FileSystemNames
@@ -20,25 +31,30 @@ function Update-PfbLegalHoldEntity {
2031 If set to `true`, the update is applied recursively to the specified path or file
2132 system.
2233 . PARAMETER Released
23- If set to `true`, the held entity is released from its legal hold.
34+ Required by the API on REST 2.17 and later. `$true` releases the held entity from its
35+ legal hold; `$false` applies or keeps the legal hold.
2436 . PARAMETER Attributes
2537 A hashtable of attributes to update on the held entity. `PATCH
2638 /legal-holds/held-entities` accepts no request body, so nothing supplied here is sent
2739 to the array. Use the typed query parameters above instead.
2840 . PARAMETER Array
2941 The FlashBlade connection object. If not specified, the default connection is used.
3042 . EXAMPLE
31- Update-PfbLegalHoldEntity -Name "fs1" -Released $true
43+ Update-PfbLegalHoldEntity -Name 'pslivetest-hold-1' -FileSystemNames 'pslivetest-fs-1' -Paths '/' -Recursive $true -Released $true
3244
33- Releases the held entity named "fs1" from its legal hold.
45+ Releases the held entity named "pslivetest-hold-1" from its legal hold. The file-system
46+ name, path, and recursive flag are all required together for this release request.
3447 . EXAMPLE
35- Update-PfbLegalHoldEntity -Name "bucket1" - Recursive $false
48+ Update-PfbLegalHoldEntity -Name 'pslivetest-hold-1' -FileSystemNames 'pslivetest-fs-1' -Paths '/' - Recursive $true -Released $false
3649
37- Updates the held entity named "bucket1" without applying the change recursively.
50+ Applies the legal hold to the same path. This is the release example with -Released
51+ flipped -- the two directions take the same arguments.
3852 . EXAMPLE
39- Update-PfbLegalHoldEntity -Name "fs1" -Attributes @{ hold_type = 'litigation' }
53+ Update-PfbLegalHoldEntity -Name 'pslivetest-hold-1' -FileSystemIds '10314f42-020d-7080-8013-000ddt400090' -Paths '/' -Recursive $true -Released $true
4054
41- Updates the held entity using a raw attributes hashtable.
55+ Releases the hold identifying the file system by ID instead of by name. Note that
56+ `file_system_ids` refers to the file system, which has an ID; the held entity itself
57+ does not, so -Ids is not a substitute for this form.
4258 #>
4359 [CmdletBinding (SupportsShouldProcess , ConfirmImpact = ' Medium'
4460 param (
@@ -60,8 +76,8 @@ function Update-PfbLegalHoldEntity {
6076 [Parameter ()]
6177 [Nullable [bool ]]$Recursive ,
6278
63- [Parameter ()]
64- [Nullable [ bool ] ]$Released ,
79+ [Parameter (Mandatory )]
80+ [bool ]$Released ,
6581
6682 [Parameter ()]
6783 [hashtable ]$Attributes ,
@@ -88,7 +104,9 @@ function Update-PfbLegalHoldEntity {
88104 if ($PSBoundParameters.ContainsKey (' Ids' $queryParams [' ids' = $Ids -join ' ,'
89105 if ($PSBoundParameters.ContainsKey (' Paths' $queryParams [' paths' = $Paths -join ' ,'
90106 if ($PSBoundParameters.ContainsKey (' Recursive' $queryParams [' recursive' = $Recursive }
91- if ($PSBoundParameters.ContainsKey (' Released' $queryParams [' released' = $Released }
107+ # Unlike optional parameters, released is required by the spec, so no legal request omits it;
108+ # the usual ContainsKey distinction between omitted and supplied as false cannot arise here.
109+ $queryParams [' released' = $Released
92110
93111 if ($PSCmdlet.ShouldProcess ($Name , ' Update legal hold entity'
94112 Invoke-PfbApiRequest - Array $Array - Method PATCH - Endpoint ' legal-holds/held-entities' - Body $body - QueryParams $queryParams
0 commit comments