en-US/about_VirtualMetric.help.txt
|
TOPIC about_VirtualMetric SHORT DESCRIPTION Manage VirtualMetric DataStream from PowerShell: sign in, read and change the fleet, run Bicep deployments and read the audit log. LONG DESCRIPTION The VirtualMetric module speaks the VirtualMetric public API (/api/v1) of the console you connect to, wherever that API is: give Connect-VMetric the console's address or the API's, and it finds the other through the API's metadata or the console's config.js. Its cmdlets follow the shape of Microsoft's Az module: Connect-VMetric, Get-VMetricContext, Get/New/Set/Remove-VMetric<Type>, New-VMetricDeployment and so on. It runs on PowerShell 7.2 and later, on Windows, Linux and macOS. SIGNING IN Connect-VMetric -Uri https://console.example.com Opens your browser. Sign in to the console, pick the tenant and approve; the browser returns to PowerShell. Cancel there stops the sign-in. Connect-VMetric -Uri https://console.example.com -UseDeviceAuthentication Prints a code to enter at <console>/cli/device from any device. This is the default where no browser can be shown (SSH, Linux without a display). Connect-VMetric -Uri https://console.example.com -ApiToken (Get-Secret VMetricToken) Uses an API token, for automation. A sign-in acts as you: your permissions in the tenant apply and the audit log names you. It lasts up to 30 days and refreshes itself while you work. Get-VMetricTenant lists the tenants you can use (an MSSP's subtenants included) and Set-VMetricContext -Tenant switches between them; a switch ends the session you leave. Disconnect-VMetric signs out. Sessions live in memory only, and no token ever appears in output, errors or $Error. READING AND CHANGING RESOURCES Get-VMetric<Type> lists resources or gets one by -Id; -Name keeps the one with exactly that name. New, Set, Enable and Disable write through the deployment engine, exactly as the console and Bicep templates do: every write is validated, permission-checked and audited. Remove deletes, and asks first. Objects flow through the pipeline: Get-VMetricDevice | Where-Object protocol -eq udp | Set-VMetricDevice -Port 1514 WHATIF AND CONFIRM -WhatIf on New, Set, Enable and Disable shows what the engine would actually change, property by property, and changes nothing: What if: Update device 'syslog-udp': properties.properties.port: 514 -> 1514 -Confirm shows the same and asks. DEPLOYMENTS New-VMetricDeployment -TemplateFile x.bicep -TemplateParameterObject @{...} runs a Bicep template. It validates it first, shows the what-if with -WhatIf, waits for the deployment with its progress (or returns a job with -AsJob), and writes the deployment. Test-VMetricDeployment checks a template; Get-VMetricDeployment and Stop-VMetricDeployment follow and stop deployments; Export-VMetricTemplate writes existing resources as a template. SECRETS Give secrets as SecureStrings (Read-Host -AsSecureString, Get-Secret). The module reads one only to send it in a request, and never writes one to any output stream. Values a write returns once, such as a new director's API key, are added to the object it writes, with a warning to copy them. ERRORS An API error is an ErrorRecord with the API's code as its error id, a category chosen from the HTTP status, and the trace id in the message and in $Error[0].Exception.TraceId: quote it to support. When another deployment is running in the organization, a write waits up to 30 seconds for it before it fails. EXAMPLES Connect-VMetric -Uri https://console.example.com Get-VMetricDevice -Name syslog-udp | Format-List * Get-VMetricDevice | Where-Object protocol -eq udp | Set-VMetricDevice -Port 1514 -WhatIf New-VMetricDeployment -TemplateFile ./fleet.bicep -AsJob | Receive-Job -Wait Get-VMetricAuditLog -From (Get-Date).AddDays(-1) -Action DeviceUpdated SEE ALSO Connect-VMetric Get-VMetricContext New-VMetricDeployment The PowerShell guide in the product documentation (docs/cli/powershell.md). |