Public/Set-GhostPost.ps1
|
function Set-GhostPost { <# .SYNOPSIS Updates a post on the Ghost site. .DESCRIPTION Changes the properties that are passed and leaves every other property of the post as it is. Pass an empty string to clear a text property. Tags and authors are replaced, not merged: pass the complete list. Ghost refuses an update when the post was changed by somebody else in the meantime. It detects that with the updated_at value of the post. A post from Get-GhostPost carries that value through the pipeline, so such an update fails when the post has changed since it was read. Without -UpdatedAt the current value is read first and the update always applies. .EXAMPLE Set-GhostPost -Id '5b7ada404f87d200b5b1f9c8' -Title 'A better title' Changes the title of the post. .EXAMPLE Get-GhostPost -Filter 'tag:news' | Set-GhostPost -Featured Marks every post with the tag news as featured. .EXAMPLE Set-GhostPost -Id '5b7ada404f87d200b5b1f9c8' -Html (Get-Content -Path ./post.html -Raw) -SaveRevision Replaces the content of the post and saves the previous content as a revision. .EXAMPLE Set-GhostPost -Id '5b7ada404f87d200b5b1f9c8' -Markdown (Get-Content -Path ./post.md -Raw -Encoding UTF8) Replaces the content of the post with the Markdown of a file. Sync-GhostPost does this for files that carry their own title and other fields. .EXAMPLE Set-GhostPost -Id '5b7ada404f87d200b5b1f9c8' -CustomExcerpt '' Clears the custom excerpt of the post. .LINK https://docs.ghost.org/admin-api/posts/updating-a-post #> [CmdletBinding(DefaultParameterSetName = 'Lexical', SupportsShouldProcess)] [OutputType('Ghost.Post')] param( # Id of the post to update. [Parameter(Mandatory, Position = 0, ValueFromPipelineByPropertyName)] [ValidateNotNullOrEmpty()] [string] $Id, # The updated_at value of the post as it was read. Defaults to the current value of the post. [Parameter(ValueFromPipelineByPropertyName)] [Alias('updated_at')] [datetime] $UpdatedAt, # Title of the post. [ValidateNotNullOrEmpty()] [string] $Title, # Content of the post as a Lexical document: the JSON of the Ghost editor, as a string. [Parameter(ParameterSetName = 'Lexical')] [string] $Lexical, # Content of the post as HTML. Ghost converts it to Lexical. [Parameter(Mandatory, ParameterSetName = 'Html')] [string] $Html, # Content of the post as Markdown. It is stored as it is and rendered by Ghost. [Parameter(Mandatory, ParameterSetName = 'Markdown')] [AllowEmptyString()] [string] $Markdown, # Slug of the post, the last part of its address. [string] $Slug, # Status of the post. Publish-GhostPost and Unpublish-GhostPost are the usual way to change it. [ValidateSet('draft', 'published', 'scheduled')] [string] $Status, # Who can read the post. [ValidateSet('public', 'members', 'paid', 'tiers')] [string] $Visibility, # Mark the post as featured. Use -Featured:$false to remove the mark. [switch] $Featured, # Tags of the post: names, or objects such as @{ name = 'News' }. Replaces the current tags. [AllowEmptyCollection()] [object[]] $Tags, # Authors of the post: email addresses, or objects such as @{ id = '...' }. Replaces the current authors. [object[]] $Authors, # Address of the feature image. [string] $FeatureImage, # Alternative text of the feature image. [string] $FeatureImageAlt, # Caption of the feature image. [string] $FeatureImageCaption, # Excerpt shown in lists and previews instead of the first words of the post. [string] $CustomExcerpt, # Publication date. [datetime] $PublishedAt, # Canonical address of the post, when the original lives somewhere else. [string] $CanonicalUrl, # Title for search engines. [string] $MetaTitle, # Description for search engines. [string] $MetaDescription, # Open Graph image, used when the post is shared. [string] $OgImage, # Open Graph title. [string] $OgTitle, # Open Graph description. [string] $OgDescription, # Image for the X (Twitter) card. [string] $TwitterImage, # Title for the X (Twitter) card. [string] $TwitterTitle, # Description for the X (Twitter) card. [string] $TwitterDescription, # Code injected in the head of the post. [string] $CodeInjectionHead, # Code injected before the end of the body of the post. [string] $CodeInjectionFoot, # Name of the custom template of the theme to render the post with. [string] $CustomTemplate, # Save the content before the update as a revision of the post. [switch] $SaveRevision ) begin { Test-GhostConnection $resources = Get-GhostAPIData -Endpoint $MyInvocation.MyCommand.Name } process { try { # A copy, so that values can be added without leaking into the next object from the pipeline. $parameters = [hashtable]::new($PSBoundParameters, [System.StringComparer]::OrdinalIgnoreCase) if ($parameters.ContainsKey('Html')) { # Ghost ignores the html field unless it is told that HTML is the source. $parameters['Source'] = 'html' } if ($parameters.ContainsKey('Markdown')) { # Markdown travels as a Lexical document that holds one Markdown card. $parameters['Lexical'] = ConvertTo-GhostLexical -Markdown $Markdown } if (-not $parameters.ContainsKey('UpdatedAt')) { $current = @{ Endpoint = $resources.URI Parameters = $parameters Location = $resources.Result } $parameters['UpdatedAt'] = Get-GhostUpdatedAt @current } $uri = New-URIString -Endpoint $resources.URI -Parameters $parameters $uri = New-QueryString -Uri $uri -QueryKeys $resources.Query -Parameters $parameters $body = New-BodyString -BodyKeys $resources.Body -Parameters $parameters -Wrapper $resources.Result if ($PSCmdlet.ShouldProcess($Id, $resources.Description)) { $result = Submit-Request -Uri $uri -Method $resources.Method -Body $body -Success $resources.Success $result = Test-ReturnFormat -Result $result -Location $resources.Result Set-ObjectTypeName -InputObject $result -TypeName $resources.TypeName } } catch { $PSCmdlet.ThrowTerminatingError($_) } } } |