public/Get-TMdbTVSeason.ps1
|
Function Get-TMdbTVSeason { <# .DESCRIPTION Gets the details of a single TV Season, which includes the data for all episodes. .OUTPUTS A single [TVSeason] object with the following properties: - [String] Source - [String] ID - [String] ShowID - [int32] Number - [String] Name - [String] Description - [Credit[]] Cast - [Credit[]] Crew - [String] Network - [String] Year - [String] FirstAirDate - [String] LastAirDate - [int32] TotalEpisodes - [String] PosterPath - [String] BackdropPath - [String] PosterURL - [String] BackdropURL - [TVEpisode[]] Episodes - [Item[]] ExternalIDs - [Image[]] Images .PARAMETER SeriesID REQUIRED. String. Alias: -t, -ShowID. The TV Series/Show ID. Example: 615 .PARAMETER SeasonNumber REQUIRED. Int. Alias: -s. The Season Number of the Series/Show. Example: 1 .PARAMETER IncludeSeasonCastCredits OPTIONAL. Switch. Alias: -ccs. The TMDB Season details do not include the credits for cast or crew members, which is a separate TMDB query. Use this switch to include the cast and crew credits in the season details. .PARAMETER IncludeSeasonImages OPTIONAL. Switch. Alias: -imgs. TMDB includes a poster image representing the season in the season details. However, seasons may have multiple images available to select from. To include links to all of the images matching the language specified in the "Language" parameter, include this parameter. .PARAMETER IncludeSeasonExternalIDs OPTIONAL. Switch. Alias: -xids. TMDB includes the IDs used by other media databases (IMDB, Freebase, TVDB, TVRage and Wikidata) for many of the the entries in it's catalog. Use this switch to include the IDs of those entries (if they exist) in the season data. .PARAMETER IncludeEpisodeCastCredits OPTIONAL. Switch. Alias: -cce. The TMDB Episode details include the credits for crew members and guest stars but do not include the cast credits, which is a separate TMDB query. Use this switch to include the cast credits in the episode details. Please note that this parameter is mutually exclusive with the IncludeSeasonCastCreditsForEpisodes parameter. .PARAMETER IncludeEpisodeImages OPTIONAL. Switch. Alias: -imge. TMDB includes a single still image representing the episode in the episode details. However, episodes may have multiple images available to select from. To include links to all of the images matching the language specified in the "Language" parameter, include this parameter. .PARAMETER IncludeEpisodeExternalIDs OPTIONAL. Switch. Alias: -xide. TMDB includes the IDs used by other media databases (IMDB, Freebase, TVDB, TVRage and Wikidata) for many of the the entries in it's catalog. Use this switch to include the IDs of those entries (if they exist) in the episode data. .PARAMETER IncludeSeasonCastCreditsForEpisodes OPTIONAL. Switch. Alias: -ccse. The TMDB Season details include the episode data. The episode data includes crew and guest star credits, but does not include cast credits, which is a separate TMDB query. Use this switch if you want to apply the TV Series/Show season cast credits to each episode in that Season. Please note that this parameter is mutually exclusive with the IncludeEpisodeCastCreditsForEpisodes parameter. .PARAMETER Language OPTIONAL. String. Alias: -l. The desired target language of the query. The value defaults to the user's operating system settings. Example: en-US .EXAMPLE Get-TMdbTVSeason -ShowID 615 -SeasonNumber 1 .EXAMPLE Get-TMdbTVSeason -ShowID 615 -SeasonNumber 1 -IncludeSeasonCastCredits -IncludeSeasonImages .EXAMPLE Get-TMdbTVSeason -ShowID 615 -SeasonNumber 1 -IncludeEpisodeCastCredits -IncludeEpisodeImages .EXAMPLE Get-TMdbTVSeason -t 615 -s 1 -ccs -imgs -xids -ccse -imge -xide #> [OutputType([TVSeason])] [CmdletBinding()] param ( [Parameter(Mandatory)] [Alias('t','ShowID')] [String] $SeriesID, [Parameter(Mandatory)] [Alias('s')] [Int] $SeasonNumber, [Parameter()] [Alias('ccs')] [Switch] $IncludeSeasonCastCredits, [Parameter()] [Alias('imgs')] [Switch] $IncludeSeasonImages, [Parameter()] [Alias('xids')] [Switch] $IncludeSeasonExternalIDs, [Parameter()] [Alias('cce')] [Switch] $IncludeEpisodeCastCredits, [Parameter()] [Alias('imge')] [Switch] $IncludeEpisodeImages, [Parameter()] [Alias('xide')] [Switch] $IncludeEpisodeExternalIDs, [Parameter()] [Alias('ccse')] [Switch] $IncludeSeasonCastCreditsForEpisodes, [Parameter()] [Alias('l')] [String] $Language = $((Get-Culture).Name.ToString()) ) process { Write-Msg -FunctionCall -IncludeParameters if ( -not (Test-ApiTokenSet) ) { return @{ success = $false; message = $TOKEN_NOT_SET } } if ( $IncludeSeasonCastCreditsForEpisodes -and $IncludeEpisodeCastCredits ) { Throw $('The IncludeSeasonCastCreditsForEpisodes and IncludeEpisodeCastCredits parameters are mutually exclusive. Please use only one of these parameters at a time.') } $SearchURL = @( $( $API_BASE_URI ), $( '/tv/{0}' -f $SeriesID ), $( '/season/{0}' -f $SeasonNumber ), $( '?language={0}' -f $Language ) ) -Join '' Write-Msg -p -ps -m ( 'Querying TMDB for TV Season Details ...' ) Write-Msg -i -il 1 -m ( 'Series/Show ID: {0}' -f $SeriesID ) Write-Msg -i -il 1 -m ( 'Season Number: {0}' -f $SeasonNumber ) Write-Msg -d -il 1 -m ( 'Token: {0}...' -f $($env:TMDB_API_TOKEN).Substring(0,8) ) Write-Msg -d -il 1 -m ( 'Query: {0}' -f $SearchURL ) $r = Invoke-HttpRequest -u $SearchURL -t $env:TMDB_API_TOKEN -j -d if ( $r.success -and $r.statusCode -eq 200 ) { $s = ($r.value | ConvertFrom-Json) if ( Test-IsSomething($s) ) { $season = $( $s | Get-TVSeasonFromDetails ) if ( Test-IsNothing($season.ShowID) ) { $season.ShowID = $SeriesID } if ( $IncludeSeasonCastCredits -or $IncludeSeasonCastCreditsForEpisodes ) { $c = Get-TMdbCredits -t $SeriesID -s $SeasonNumber -l $Language if ( $c.success ) { if ( $IncludeSeasonCastCredits ) { $season.Cast = $c.value.cast $season.Crew = $c.value.crew } if ( $IncludeSeasonCastCreditsForEpisodes ) { if ( $null -ne $season.Episodes ) { $season.Episodes | ForEach-Object { if ( $c.success ) { $_.Cast = $c.value.cast } } } } } } if ( $IncludeSeasonImages ) { $i = Get-TMdbImages -t $SeriesID -s $SeasonNumber -l $($Language.Split('-')[0]) if ( $i.success ) { $season.Images = $i.value } } if ( $IncludeSeasonExternalIDs ) { $x = Get-TMdbExternalIDs -t $SeriesID -s $SeasonNumber if ( $x.success ) { $season.ExternalIDs = $x.value } } if ( $IncludeEpisodeCastCredits ) { if ( $null -ne $season.Episodes ) { $season.Episodes | ForEach-Object { $c = Get-TMdbCredits -t $_.ShowID -s $_.Season -e $_.Number -l $Language if ( $c.success ) { $_.Cast = $c.value.cast } } } } if ( $IncludeEpisodeImages ) { if ( $null -ne $season.Episodes ) { $season.Episodes | ForEach-Object { $i = Get-TMdbImages -t $_.ShowID -s $_.Season -e $_.Number -l $($Language.Split('-')[0]) if ( $i.success ) { $_.Images = $i.value } } } } if ( $IncludeEpisodeExternalIDs ) { if ( $null -ne $season.Episodes ) { $season.Episodes | ForEach-Object { $x = Get-TMdbExternalIDs -t $_.ShowID -s $_.Season -e $_.Number if ( $x.success ) { $_.ExternalIDs = $x.value } } } } $result = @{ success = $true; value = $season } } else { $result = @{ success = $true; value = $null } } } elseif ( -not $r.success -and $r.statusCode -eq 404 ) { $result = @{ success = $false; message = 'No results found for query.' } } else { $result = $r } Write-Msg -FunctionResult -Object $result -MaxRecursionDepth 5 return $result } } |