Public/Get-GhostTag.ps1
|
function Get-GhostTag { <# .SYNOPSIS Gets tags from the Ghost site. .DESCRIPTION Without parameters every tag is returned, internal tags included. Ghost returns tags in pages; all pages are retrieved unless -Limit or -Page is used, in which case exactly that page is returned. Use -Id or -Slug to get a single tag. An internal tag is a tag whose name starts with #. It is not shown on the site and its slug starts with hash-. .EXAMPLE Get-GhostTag Returns every tag of the site. .EXAMPLE Get-GhostTag -Include 'count.posts' -Order 'count.posts desc' -Limit 10 Returns the ten tags with the most posts. The number of posts is in the property count. .EXAMPLE Get-GhostTag -Slug 'news' Returns the tag with the slug news. .EXAMPLE Get-GhostTag -Filter 'visibility:internal' -Fields id, name, slug Returns the id, the name and the slug of every internal tag. .LINK https://docs.ghost.org/admin-api .LINK https://docs.ghost.org/content-api/tags #> [CmdletBinding(DefaultParameterSetName = 'Browse')] [OutputType('Ghost.Tag')] param( # Id of the tag to get. [Parameter(Mandatory, ParameterSetName = 'Id', Position = 0, ValueFromPipelineByPropertyName)] [ValidateNotNullOrEmpty()] [string] $Id, # Slug of the tag to get. [Parameter(Mandatory, ParameterSetName = 'Slug')] [ValidateNotNullOrEmpty()] [string] $Slug, # Filter in the Ghost query language (NQL), such as visibility:public or name:~'news'. [Parameter(ParameterSetName = 'Browse')] [string] $Filter, # Sort order, such as 'name asc' or 'count.posts desc'. [Parameter(ParameterSetName = 'Browse')] [string] $Order, # Number of tags in a page, 100 at most. Returns a single page instead of every tag. [Parameter(ParameterSetName = 'Browse')] [ValidateRange(1, 100)] [int] $Limit, # Number of the page to return. Returns a single page instead of every tag. [Parameter(ParameterSetName = 'Browse')] [ValidateRange(1, [int]::MaxValue)] [int] $Page, # Related data to include: count.posts adds the number of posts that have the tag. [string[]] $Include, # Names of the properties to return, to limit the size of the response. [string[]] $Fields ) begin { Test-GhostConnection $resources = Get-GhostAPIData -Endpoint $MyInvocation.MyCommand.Name } process { try { # Every page is retrieved unless the caller asked for a specific one. $singlePage = $PSBoundParameters.ContainsKey('Limit') -or $PSBoundParameters.ContainsKey('Page') $paginate = $PSCmdlet.ParameterSetName -eq 'Browse' -and -not $singlePage $uri = New-URIString -Endpoint $resources.URI[$PSCmdlet.ParameterSetName] -Parameters $PSBoundParameters $uri = New-QueryString -Uri $uri -QueryKeys $resources.Query -Parameters $PSBoundParameters $result = Submit-Request -Uri $uri -Method $resources.Method -Success $resources.Success -Paginate:$paginate $result = Test-ReturnFormat -Result $result -Location $resources.Result Set-ObjectTypeName -InputObject $result -TypeName $resources.TypeName } catch { $PSCmdlet.ThrowTerminatingError($_) } } } |