Set-NBObjectTag
Since
v4.7.0.1
SYNOPSIS
Adds and/or removes tags on any Netbox object without replacing its whole tag list.
SYNTAX
ByObject (Default)
Set-NBObjectTag -InputObject <PSObject> [-Add <Object[]>] [-Remove <Object[]>] [-Raw]
[-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm] [<CommonParameters>]
ByUrl
Set-NBObjectTag -Url <String> [-Add <Object[]>] [-Remove <Object[]>] [-Raw]
[-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm] [<CommonParameters>]
DESCRIPTION
Netbox 4.6+ accepts 'add_tags' and 'remove_tags' in a PATCH request (partial tag assignment), so a tag can be added or removed without first reading and resending the complete 'tags' array - which is both faster and safe against a concurrent edit of the other tags.
Pass the object itself (any Get-NB* result; its 'url' property identifies it) or the object's API path. The request is always sent to the configured Netbox host - only the path of the object URL is used - so a proxied or renamed host in the object URL cannot redirect the request.
Tags may be given as IDs or names. Older Netbox versions silently ignore add_tags/remove_tags, so on a server below 4.6 this cmdlet throws instead of pretending to succeed.
EXAMPLES
EXAMPLE 1
Get-NBDCIMDevice -Name 'core-01' | Set-NBObjectTag -Add 'maintenance'
Adds the 'maintenance' tag to the device, keeping its other tags.
EXAMPLE 2
Get-NBDCIMDevice -Tag 'maintenance' | Set-NBObjectTag -Remove 'maintenance' -Add 12
Swaps the 'maintenance' tag for tag ID 12 on every matching device.
EXAMPLE 3
Set-NBObjectTag -Url '/api/ipam/prefixes/7/' -Add 'audited'
PARAMETERS
-InputObject
The Netbox object (from any Get-NB* cmdlet, pipeline supported). Must carry a 'url' property.
Type: PSObject
Parameter Sets: ByObject
Aliases:
Required: True
Position: Named
Default value: None
Accept pipeline input: True (ByValue)
Accept wildcard characters: False
-Url
The object's API URL or path instead of an object, e.g. '/api/dcim/devices/42/'.
Type: String
Parameter Sets: ByUrl
Aliases:
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Add
Tags to add (IDs or names). Tags the object already carries are left untouched.
Type: Object[]
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Remove
Tags to remove (IDs or names). Tags the object does not carry are ignored.
Type: Object[]
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Raw
Return the raw API response.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-WhatIf
Shows what would happen if the cmdlet runs. The cmdlet is not run.
Type: SwitchParameter
Parameter Sets: (All)
Aliases: wi
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Confirm
Prompts you for confirmation before running the cmdlet.
Type: SwitchParameter
Parameter Sets: (All)
Aliases: cf
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-ProgressAction
{{ Fill ProgressAction Description }}
Type: ActionPreference
Parameter Sets: (All)
Aliases: proga
Required: False
Position: Named
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.
INPUTS
OUTPUTS
System.Management.Automation.PSObject
NOTES
AddedInVersion: v4.7.0.1 Requires Netbox 4.6+ (netbox-community/netbox#21771).