Get-AIPFileStatus

Relevant for: AIP unified labeling and classic clients

Gets the Azure Information Protection label and protection information for a specified file or files.

Note

If your files are stored in SharePoint Online, use the Get-FileSensitivityLabelInfo cmdlet from the SharePointOnlinePowerShell module instead.

Syntax

Get-AIPFileStatus
   [-Path] <String[]>
   [<CommonParameters>]

Description

The Get-AIPFileStatus cmdlet returns the Azure Information Protection status of a specified file or all files in a specified path. This status includes whether the file has a label, and if it does, the label name, who applied it, how it was applied, and when.

The status also includes whether the file is protected by Rights Management, and if it is, what Rights Management template was used to apply this protection. If the file was protected with custom permissions (an ad-hoc rights policy) instead of a template, "Restricted Access" is displayed instead of the template name. In addition, the Rights Management owner and Rights Management issuer is displayed, and when the file was protected.

Note that password-protected files always return the protection status of False.

You can run this cmdlet non-interactively. For more information, see the following client admin guides:

Note

To provide a unified and streamlined customer experience, the Azure Information Protection classic client and Label Management in the Azure Portal are deprecated as of March 31, 2021. While the classic client continues to work as configured, no further support is provided, and maintenance versions will no longer be released for the classic client.

We recommend that you migrate to unified labeling and upgrade to the unified labeling client. Learn more in our recent deprecation blog.

Differences in support between clients

If you have the AIP unified labeling client, functionality differs from the classic client as follows.

In the unified labeling client:

  • This cmdlet returns label information from your own tenant only and the LabelingSiteId parameter is not displayed in the output.

  • The Owner and RMSIssuedTime parameters are not supported and are not displayed in the output.

  • The LabelingMethod parameter displays the values of Privileged or Standard instead of Manual or Automatic:

    • Privileged: A label was applied by a user, either manually or a result of a labeling recommendation, and is the equivalent of Manual for the AIP classic client.

    • Standard: A label was applied automatically, and is the equivalent of Automatic for the AIP classic client.

Examples

Example 1a: (Classic client) Get the label and protection status of a single file

PS C:\> Get-AIPFileStatus -Path \\Finance\Projects\Project.docx

FileName        : \\Finance\Projects\Project.docx
IsLabeled       : True
MainLabelId     : 074e257c-1234-1234-1234-34a182080e71
MainLabelName   : Confidential
SubLabelId      : d9f23ae3-1234-1234-1234-f515f824c57b
SubLabelName    : Finance group
LabelingSiteId  : 72f988bf-1234-1234-1234-2d7cd011db47
Owner           : John@Contoso.com
LabelingMethod  : Manual
LabelDate       : 12/12/2016 12:24:36 PM
IsRMSProtected  : True
RMSTemplateId   : e6ee2481-1234-1234-1234-f744eacd53b0
RMSTemplateName : Contoso - Confidential Finance
RMSIssuedTime   : 5/6/2018 9:15:03 AM
RMSOwner        : John@Contoso.com
RMSIssuer       : John@Contoso.com

This command provides information about a file that is labeled as "Confidential \ Finance group". This file was labeled manually by John and it is also protected by using the Rights Management template, "Contoso - Confidential Finance".

Example 1b: (Unified labeling client) Get the label and protection status of a single file

PS C:\> Get-AIPFileStatus -Path \\Finance\Projects\Project.docx

FileName        : \\Finance\Projects\Project.docx
IsLabeled       : True
MainLabelId     : 074e257c-1234-1234-1234-34a182080e71
MainLabelName   : Confidential
SubLabelId      : d9f23ae3-1234-1234-1234-f515f824c57b
SubLabelName    : Finance group
LabelingMethod  : Privileged
LabelDate       : 12/12/2016 12:24:36 PM
IsRMSProtected  : True
RMSTemplateId   : e6ee2481-1234-1234-1234-f744eacd53b0
RMSTemplateName : Contoso - Confidential Finance
RMSOwner        : John@Contoso.com
RMSIssuer       : John@Contoso.com
ContentId       : 4ca757d2-83bf-4ec3-b93b-c7fe9433bf33

This command provides information about a file that is labeled as "Confidential \ Finance group", which is a label that is configured for your tenant. This file was labeled manually by John and it is also protected by using the Rights Management template, "Contoso - Confidential Finance".

Example 2: Get the label and protection status for all files in a folder and export the results to a CSV file

PS C:\> Get-AIPFileStatus -Path \\Finance\Projects\ | Export-Csv C:\Reports\AIP-status.csv

This command gets the label and protection information of all files on the Finance server, in the Projects folder and any of its subfolders. The results are exported to the file named AIP-status.csv so that they can be more easily searched and sorted. If a previous report exists in C:\Reports\Report.csv, it will be overwritten.

Example 3: List the files labeled "Confidential" and export the results to a CSV file

PS C:\> Get-AIPFileStatus -Path \\Finance\Projects\ | Where-Object {$_.MainLabelName -eq 'Confidential'} | Export-Csv C:\Reports\AIP-status.csv

This command gets the label and protection information for just the files that are labeled "Confidential" (regardless of their sublabel) on the Finance server, in the Projects folder and any of its subfolders. The results are exported to the file named AIP-status.csv so that they can be more easily searched and sorted. If a previous report exists in C:\Reports\Report.csv, it will be overwritten.

Example 4: Count of files with a "Confidential" label

PS C:\> (Get-AIPFileStatus -Path C:\Projects\ | Where-Object {$_.MainLabelName -eq 'Confidential'}).Count

5

This command provides the number of files with the "Confidential" label that are in the C:\Projects folder and any of its subfolders. In this example, 5 files are found.

Parameters

-Path

Specifies a local path, network path, or SharePoint Server URL to the files for which you want to get the label and protection information. Wildcards are not supported.

For SharePoint paths, the following are supported:

  • SharePoint Server 2019
  • SharePoint Server 2016
  • SharePoint Server 2013

For example:

Paths can include spaces when you enclose the path value with quotes.

Type:String[]
Aliases:FullName, FileName
Position:0
Default value:None
Accept pipeline input:True
Accept wildcard characters:False

Inputs

System.String[]

Outputs

Microsoft.InformationProtection.Powershell.AIP.Results.GetAIPFileStatusResult