你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Set-FileLabel

模块:: PurviewInformationProtection Module

Sets the sensitivity label and protection for a file through manual labeling or autolabeling according to the label configuration or custom permissions.

语法

SetLabel

Set-FileLabel
    [-Path] <String[]>
    -LabelId <Guid>
    [-JustificationMessage <String>]
    [-Owner <String>]
    [-PreserveFileDetails]

SetLabelCustom

Set-FileLabel
    [-Path] <String[]>
    -LabelId <Guid>
    -CustomPermissions <AIPCustomPermissions>
    [-JustificationMessage <String>]
    [-Owner <String>]
    [-PreserveFileDetails]

Custom

Set-FileLabel
    [-Path] <String[]>
    -CustomPermissions <AIPCustomPermissions>
    [-Owner <String>]
    [-PreserveFileDetails]

SetAutoLabel

Set-FileLabel
    [-Path] <String[]>
    [-JustificationMessage <String>]
    [-Owner <String>]
    [-Force]
    [-PreserveFileDetails]
    [-AutoLabel]

WhatIf

Set-FileLabel
    [-Path] <String[]>
    [-PreserveFileDetails]
    [-WhatIf]
    [-DiscoveryInfoTypes <String[]>]

说明

For the Microsoft Purview Information Protection client, the Set-FileLabel cmdlet sets a sensitivity label for one or more files. This action can automatically apply protection when labels are configured to apply encryption.

Additionally, you can use this cmdlet to apply custom permissions when they are created as an ad-hoc protection policy object with the New-CustomPermissions cmdlet.

When the command runs successfully, any existing label or protection can be replaced.

You can run this cmdlet non-interactively. For more information, see the Unified labeling client admin guide.

示例

Example 1: Apply the "General" label to all files that do not currently have a label

Get-FileStatus -Path \\Finance\Projects\ |
    Where-Object {$_.IsLabeled -eq $False} |
    Set-FileLabel -LabelId d9f23ae3-4321-4321-4321-f515f824c57b

FileName                              Status Comment
--------                              ------ ------------
\\Finance\Projects\Image.jpg          Success
\\Finance\Projects\Pricelist.pdf      Success
\\Finance\Projects\Announcement.docx  Success
\\Finance\Projects\Analysis.xlsx      Success

This command first identifies all files that are not labeled by using the Get-FileStatus cmdlet. Then, these files are labeled by specifying the "General" label by its ID.

Example 2: Apply the "General" label to .docx files that are not labeled

Get-ChildItem C:\Projects\*.docx -File -Recurse |
    Get-FileStatus |
    Where-Object {$_.IsLabeled -eq $False} |
    Set-FileLabel -LabelId d9f23ae3-1234-1234-1234-f515f824c57b

FileName                   Status  Comment
--------                   ------  ------------
C:\Projects\Analysis.docx  Success
C:\Projects\Projects.docx  Success

This command first identifies all .docx files in the C:\Projects folder (and its subfolders) by using Get-Child-Item, then finds from these files the ones that are not labeled by using the Get-FileStatus cmdlet. The resulting files are then labeled by specifying the General label by its ID.

Note

This command makes use of the Path alias of FullName, so that Get-Child-Item can be used with Get-FileStatus.

Example 3: Apply the "General" label to all files in a folder and any of its subfolders

Set-FileLabel -Path C:\Projects\ -LabelId d9f23ae3-1324-1234-1234-f515f824c57b

FileName                    Status      Comment
--------                    ------      ------------
C:\Projects\Project1.docx   Success
C:\Projects\Datasheet.pdf   Success
C:\Projects\Image.jpg       Success
C:\Projects\Analysis.xlsx   Skipped    No label to apply
C:\Projects\Dashboard.xlsx  Success

This command sets a label named "General" on all files in the C:\Projects folder and any of its subfolders.

If the General label is configured to apply encryption, the files that were successfully labeled with this command will also be encrypted. In this case, the Rights Management owner (who has the Rights Management Full Control permission) of these files is the user who ran the PowerShell command.

In this example, one file was not labeled (skipped) because it required justification. This might be the intended outcome to ensure that a file with a higher classification label or protection isn't accidentally overwritten with a lower classification label or has protection removed.

To enable this safeguard, the Office 365 classification label policy must be configured to require justification for removing a label or lowering the classification. When you then run this command without the JustificationMessage parameter and the label triggers justification, the file is skipped with the comment "No label to apply".

Example 4: Apply the "General" label to a single file, which requires justification

$setFileLabelSplat = @{
    Path = '\\Finance\Projects\Analysis.xlsx'
    LabelId = 'd9f23ae3-1324-1234-1234-f515f824c57b'
    JustificationMessage = 'The previous label no longer applies'
}
Set-FileLabel @setFileLabelSplat

FileName                          Status      Comment
--------                          ------      ------------
\\finance\projects\analysis.xlsx  Success

This command sets the "General" label for a file that is already labeled with a higher sensitivity label. The sensitivity label policy is configured to require justification for removing a label or lowering the classification. Because the command includes a justification message, the new label is successfully applied.

Example 5: Protect a file with custom permissions

$newCustomPermissionsSplat = @{
    Users = 'user1@contoso.com', 'user2@vanarsdel.com'
    Permissions = 'Reviewer'
    ExpirationDate = (Get-Date -Month 1 -Day 1 -Year 2020)
}
$permissions = New-CustomPermissions @newCustomPermissionsSplat
Set-FileLabel C:\Projects\Analysis.docx -CustomPermissions $permissions

FileName                   Status Comment
--------                   ------ ------------
C:\Projects\Analysis.docx  Success

The first command creates an ad-hoc protection policy object that grants users from different organizations usage rights from the Reviewer permissions, and also applies an expiration date.

The second command protects a single file named Analysis.docx by using the custom permissions in the stored ad-hoc protection policy object.

Example 6: Apply a label and custom permissions to file

$permissions = New-CustomPermissions -Users a@a.com, b@b.com -Permissions Reviewer
$setFileLabelSplat = @{
    LabelId = 'd9f23ae3-1324-1234-1234-f515f824c57b'
    CustomPermissions = $permissions
}
Set-FileLabel @setFileLabelSplat C:\Projects\Analysis.docx

FileName                   Status Comment
--------                   ------ ------------
C:\Projects\Analysis.docx  Success

The first command creates an ad-hoc protection policy object that grants users from different organizations usage rights from the Reviewer permissions, and also applies an expiration date.

The second command applies a label to a single file named Analysis.docx and also protects the file by using the custom permissions in the stored ad-hoc protection policy object. If the label is configured for protection settings, they are replaced by the custom permissions.

Example 7: Scan all files in a folder tree and apply labels according to the configured conditions

Set-FileLabel -AutoLabel -Path C:\Projects\ -PreserveFileDetails

FileName      : C:\Projects\Project1.docx
Status        : Success
Comment       :
MainLabelName : Confidential
MainLabelId   : 074e257c-1234-1234-1234-34a182080e71
SubLabelName  : Finance group
SubLabelId    : d9f23ae3-1234-1234-1234-f515f824c57b

FileName      : C:\Projects\Datasheet.pdf
Status        : Skipped
Comment       : No label to apply
MainLabelName :
MainLabelId   :
SubLabelName  :
SubLabelId    :

FileName      : C:\Projects\Analysis.xlsx
Status        : Skipped
Comment       : No label to apply
MainLabelName :
MainLabelId   :
SubLabelName  :
SubLabelId    :

FileName      : C:\Projects\Pricelist.xlsx
Status        : Skipped
Comment       : No label to apply
MainLabelName :
MainLabelId   :
SubLabelName  :
SubLabelId    :

FileName      : C:\Projects\Dashboard.xlsx
Status        : Success
Comment       :
MainLabelName : Public
MainLabelId   : f018e9e7-0cfc-4c69-b27a-ac3cb7df43cc
SubLabelName  :
SubLabelId    :

This command scans all files in the Projects folder and any of its subfolders, and sets labels according to the configured conditions in the auto labeling policy. In this example, there are five files and two files are automatically labeled. The Datasheet.pdf file is not labeled because its contents does not match the configured conditions for automatic labeling Analysis.xlsx was already manually labeled, and Pricelist.xlsx has a higher label. Because the command is run without the Force parameter, the existing labels for Analysis.xlsx and Pricelist.xlsx are not overwritten.

If the applied labels are also configured to apply Rights Management protection, the files that are successfully labeled with this command are also protected. In this case, the Rights Management owner (who has the Rights Management Full Control permission) of these files is the user who ran the PowerShell command.

Because the PreserveFileDetails parameter is specified, the Date Modified of the labeled files remains unchanged.

Example 8: Scan all files in a folder tree and apply labels according to the configured conditions, overriding any existing labels

Set-FileLabel -Autolabel -Path C:\Projects\ -Force -PreserveFileDetails

FileName      : C:\Projects\Project1.docx
Status        : Success
Comment       :
MainLabelName : Confidential
MainLabelId   : 074e257c-1234-1234-1234-34a182080e71
SubLabelName  : Finance group
SubLabelId    : d9f23ae3-1234-1234-1234-f515f824c57b

FileName      : C:\Projects\Datasheet.pdf
Status        : Skipped
Comment       : No label to apply
MainLabelName :
MainLabelId   :
SubLabelName  :
SubLabelId    :

FileName      : C:\Projects\Analysis.xlsx
Status        : Success
Comment       :
MainLabelName : Public
MainLabelId   : f018e9e7-0cfc-4c69-b27a-ac3cb7df43cc
SubLabelName  :
SubLabelId    :

FileName      : C:\Projects\Pricelist.xlsx
Status        : Success
Comment       :
MainLabelName : Public
MainLabelId   : f018e9e7-0cfc-4c69-b27a-ac3cb7df43cc
SubLabelName  :
SubLabelId    :

FileName      : C:\Projects\Dashboard.xlsx
Status        : Success
Comment       :
MainLabelName : Public
MainLabelId   : f018e9e7-0cfc-4c69-b27a-ac3cb7df43cc
SubLabelName  :
SubLabelId    :

This command is similar to the previous example in that it also scans all files in the Projects folder and any of its subfolders, and sets labels according to the configured conditions for auto labeling. However, this time, because the command includes the Force parameter, it also replaces the existing label for Dashboard.xlsx, and Pricelist.xlsx.

The contents of Datasheet.pdf did not match any configured conditions and this file remains without a label.

Example 9: Scan a file for all known sensitive information types

Set-FileLabel -AutoLabel -Path C:\Projects\Project1.docx -DiscoveryInfoTypes All

MainLabelName           : General
MainLabelId             : 89a453df-5df4-4976-8191-jdn2fsf9560a
SubLabelName            :
SubLabelId              :
WhatIf                  : True
MatchedInformationTypes : {Credit Card Number, U.S. Social Security Number (SSN), International Classification of
                          Diseases (ICD-10-CM), International Classification of Diseases (ICD-9-CM)}
LastModifiedBy          :
LastModifiedTime        : 8/19/2014 5:11:26 AM
FileName                : C:\Projects\Project1.docx
Status                  : Success
Comment                 :

This command discovers all known information types in Project1.docx file without applying protection or a label.

Example 10: Scan a file for specific sensitive information types

$setFileLabelSplat = @{
    AutoLabel = -AutoLabel
    Path = 'C:\Projects\Project1.docx'
    DiscoveryInfoTypes = "50842eb7-edc8-4019-85dd-5a5c1f2bb085", "a44669fe-0d48-453d-a9b1-2cc83f2cba77"
}
Set-FileLabel @setFileLabelSplat

MainLabelName           : General
MainLabelId             : 89a453df-5df4-4976-8191-jdn2fsf9560a
SubLabelName            :
SubLabelId              :
WhatIf                  : True
MatchedInformationTypes : {Credit Card Number, U.S. Social Security Number (SSN)}
LastModifiedBy          :
LastModifiedTime        : 8/19/2014 5:11:26 AM
FileName                : Project1.docx
Status                  : Success
Comment                 :

This command discovers the specific information types of Credit Card Number, and Social Security Number (SSN) in Project1.docx file without applying protection or a label.

Example 11: Scan a file for specific sensitive information types and display the values found

$setFileLabelSplat = @{
    AutoLabel = -AutoLabel
    Path = 'C:\Projects\Project1.docx'
    DiscoveryInfoTypes = '50842eb7-edc8-4019-85dd-5a5c1f2bb085',
        'a44669fe-0d48-453d-a9b1-2cc83f2cba77'
}
$x = Set-FileLabel @setFileLabelSplat
$x.MatchedInformationTypes

RulePackageSetId  : 00000000-0000-0000-0000-000000000000
RulePackageId     : 00000000-0000-0000-0000-000000000000
RuleId            : 50842eb7-edc8-4019-85dd-5a5c1f2bb085
Name              : Credit Card Number
Count             : 1
UniqueCount       : 1
Confidence        : 85
SensitiveContents : {Offset: 2089, Length: 19}

RulePackageSetId  : 00000000-0000-0000-0000-000000000000
RulePackageId     : 00000000-0000-0000-0000-000000000000
RuleId            : a44669fe-0d48-453d-a9b1-2cc83f2cba77
Name              : U.S. Social Security Number (SSN)
Count             : 1
UniqueCount       : 1
Confidence        : 85
SensitiveContents : {Offset: 7063, Length: 11}

$x.MatchedInformationTypes[0].SensitiveContents | Format-List

Offset  : 2089
Length  : 19
Value   : 4539-9572-7949-2212
Context : OLOGICAL SCIENCES     Credit Card #
          Expiration Date:      4539-9572-7949-2212
          8/2009                Department:     BIOLOGICAL SCIENCES     Anticipa

Similar to the previous example, the first command discovers the specific information types of Credit Card Number, and Social Security Number (SSN) in Project1.docx file without applying protection or a label. However, in this example, the results are stored in a variable for further processing.

The second command is then used to display the contents of the matched information types, which includes the SensitiveContents parameter.

The final command displays and formats for easier reading the data that's identified by the first sensitive information type, which in this example, is the credit card details.

参数

-AutoLabel

When -AutoLabel is used, cmdlet runs in auto-labeling mode. When -AutoLabel cmdlet is not used, runs in manual labeling mode.

参数属性

类型:	SwitchParameter
默认值:	None
支持通配符:	False
不显示:	False

参数集

SetAutoLabel

Position:	Named
必需:	True
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-CustomPermissions

Specifies the variable name that stores an ad-hoc protection policy, which was created by using the New-CustomPermissions cmdlet. The ad-hoc protection policy is used to protect the file or files with custom permissions.

参数属性

类型:	AIPCustomPermissions
默认值:	None
支持通配符:	False
不显示:	False

参数集

SetLabelCustom

Position:	Named
必需:	True
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

Custom

Position:	Named
必需:	True
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-DiscoveryInfoTypes

Specify the sensitive information types to be discovered when you use the WhatIf parameter.

If you want to search for specific sensitive information types, specify the Entity id number for that information type, which you can find listed in Sensitive information types in Exchange Server.

For example, "50842eb7-edc8-4019-85dd-5a5c1f2bb085" is the number to specify for the Credit Card Number sensitive information type.

参数属性

类型:	String[]
默认值:	None
支持通配符:	False
不显示:	False

参数集

WhatIf

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-Force

Replaces an existing label when the configured conditions apply.

参数属性

类型:	SwitchParameter
默认值:	None
支持通配符:	False
不显示:	False

参数集

SetAutoLabel

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-JustificationMessage

The justification reason for lowering the classification label, removing a label, or removing protection, if the sensitivity policy requires users to supply this information. If setting a label triggers the justification and this reason is not supplied, the label is not applied. In this case, the status returned is "Skipped" with the comment "Justification required".

参数属性

类型:	String
默认值:	None
支持通配符:	False
不显示:	False

参数集

SetLabel

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

SetLabelCustom

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

SetAutoLabel

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-LabelId

Specifies the identity (ID) of the label to apply. When a label has sublabels, always specify the ID of just a sublabel and not the parent label.

To find the label ID:

The label ID value is not displayed in the Microsoft Purview compliance portal. However, you can use the following Office 365 Security & Compliance Center PowerShell command to find this value: Get-Label | Format-Table -Property DisplayName, Name, Guid

For files that have labels applied, you can also run the Get-FileStatus cmdlet to identify the label ID (MainLabelId or SubLabelId).

参数属性

类型:	Guid
默认值:	None
支持通配符:	False
不显示:	False

参数集

SetLabel

Position:	Named
必需:	True
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

SetLabelCustom

Position:	Named
必需:	True
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-Owner

Specifies owner for applying label or protection to the file.

参数属性

类型:	String
默认值:	None
支持通配符:	False
不显示:	False

参数集

SetLabel

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

SetLabelCustom

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

Custom

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

SetAutoLabel

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-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 and WebDav locations are not supported.

For SharePoint paths, the following are supported:

SharePoint Server 2022
SharePoint Server 2019
SharePoint Server 2016
SharePoint Server 2013

For example:

C:\Folder\
C:\Folder\Filename
\\Server\Folder
http://sharepoint.contoso.com/Shared%20Documents/Folder

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

参数属性

类型:	String[]
默认值:	None
支持通配符:	False
不显示:	False
别名:	FullName, FileName

参数集

(All)

Position:	0
必需:	True
来自管道的值:	True
来自管道的值（按属性名称）:	True
来自剩余参数的值:	False

-PreserveFileDetails

Specify this parameter to leave the modified date (Windows and SharePoint) and modified by (SharePoint) values unchanged for documents that you label:

For local or network files, the Date modified value remains unchanged.
For SharePoint files, the Modified date and Modified by values remain unchanged.

参数属性

类型:	SwitchParameter
默认值:	None
支持通配符:	False
不显示:	False

参数集

(All)

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.

参数属性

类型:	SwitchParameter
默认值:	None
支持通配符:	False
不显示:	False

参数集

WhatIf

Position:	Named
必需:	True
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

输入

System.String

输出

Microsoft.InformationProtection.Powershell.AIP.Results.SetAIPFileResult

备注

When running the Set-FileLabel cmdlet in a loop, add the following command after the cmdlet:

[GC]::Collect()
[GC]::WaitForPendingFinalizers()

These commands ensure that the garbage collector runs and releases memory that is no longer needed.

通过

Set-FileLabel

语法

SetLabel

SetLabelCustom

Custom

SetAutoLabel

WhatIf

说明

示例

Example 1: Apply the "General" label to all files that do not currently have a label

Example 2: Apply the "General" label to .docx files that are not labeled

Example 3: Apply the "General" label to all files in a folder and any of its subfolders

Example 4: Apply the "General" label to a single file, which requires justification

Example 5: Protect a file with custom permissions

Example 6: Apply a label and custom permissions to file

Example 7: Scan all files in a folder tree and apply labels according to the configured conditions

Example 8: Scan all files in a folder tree and apply labels according to the configured conditions, overriding any existing labels

Example 9: Scan a file for all known sensitive information types

Example 10: Scan a file for specific sensitive information types

Example 11: Scan a file for specific sensitive information types and display the values found

参数

-AutoLabel

参数属性

参数集

-CustomPermissions

参数属性

参数集

-DiscoveryInfoTypes

参数属性

参数集

-Force

参数属性

参数集

-JustificationMessage

参数属性

参数集

-LabelId

参数属性

参数集

-Owner

参数属性

参数集

-Path

参数属性

参数集

-PreserveFileDetails

参数属性

参数集

-WhatIf

参数属性

参数集

输入

System.String

输出

Microsoft.InformationProtection.Powershell.AIP.Results.SetAIPFileResult

备注

相关链接