Set-FileLabel

Referencia

Módulo:: PurviewInformationProtection

Establece la etiqueta de confidencialidad y la protección de un archivo mediante el etiquetado manual o la etiqueta automática según la configuración de la etiqueta o los permisos personalizados.

Syntax

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

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

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

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

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

Description

Para el cliente Microsoft Purview Information Protection, el cmdlet Set-FileLabel establece una etiqueta de confidencialidad para uno o varios archivos. Esta acción puede aplicar automáticamente la protección cuando las etiquetas están configuradas para aplicar el cifrado.

Además, puede usar este cmdlet para aplicar permisos personalizados cuando se crean como un objeto de directiva de protección ad hoc con el cmdlet New-CustomPermissions .

Cuando el comando se ejecuta correctamente, se puede reemplazar cualquier etiqueta o protección existente.

Puede ejecutar este cmdlet de forma no interactiva. Para obtener más información, consulte la guía de administración del cliente de etiquetado unificado.

Nota

Al ejecutar el cmdlet Set-FileLabel en un bucle, agregue estas dos líneas después del cmdlet : [GC]::Collect()
[GC]::WaitForPendingFinalizers()

Ejemplos

Ejemplo 1: Aplicar la etiqueta "General" a todos los archivos que no tienen actualmente una etiqueta

PS C:\> Get-FileStatus -Path \\Finance\Projects\ | where {$_.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

Este comando identifica primero todos los archivos que no están etiquetados mediante el cmdlet Get-FileStatus . A continuación, estos archivos se etiquetan especificando la etiqueta "General" por su identificador.

Ejemplo 2: Aplicar la etiqueta "General" a .docx archivos que no están etiquetados

PS C:\> Get-ChildItem C:\Projects\*.docx -File -Recurse | Get-FileStatus | where {$_.IsLabeled -eq $False} | Set-FileLabel -LabelId d9f23ae3-1234-1234-1234-f515f824c57b
FileName                   Status  Comment
--------                   ------  ------------
C:\Projects\Analysis.docx  Success
C:\Projects\Projects.docx  Success

Este comando identifica primero todos los archivos .docx de la carpeta C:\Projects (y sus subcarpetas) mediante Get-Child-Item y, a continuación, busca en estos archivos los que no están etiquetados mediante el cmdlet Get-FileStatus . A continuación, los archivos resultantes se etiquetan especificando la etiqueta "General" por su identificador.

Nota

Este comando usa el alias path de FullName para que Get-Child-Item se pueda usar con Get-FileStatus.

Ejemplo 3: Aplicar la etiqueta "General" a todos los archivos de una carpeta y cualquiera de sus subcarpetas

PS C:\> 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

Este comando establece una etiqueta denominada "General" en todos los archivos de la carpeta Projects y cualquiera de sus subcarpetas.

Si la etiqueta General está configurada para aplicar el cifrado, los archivos que se etiquetaron correctamente con este comando también se cifrarán. En este caso, el propietario de Rights Management (que tiene el permiso de control total de Rights Management) de estos archivos es el usuario que ejecutó el comando de PowerShell.

En este ejemplo, no se etiquetó un archivo (omitido) porque requería justificación. Este podría ser el resultado previsto para asegurarse de que un archivo con una etiqueta o protección de clasificación superior no se sobrescribe accidentalmente con una etiqueta de clasificación inferior o se ha quitado la protección.

Para habilitar esta protección, la directiva de etiqueta de clasificación Office 365 debe configurarse para requerir justificación para quitar una etiqueta o reducir la clasificación. Al ejecutar este comando sin el parámetro JustificationMessage y la etiqueta desencadena la justificación, el archivo se omite con el comentario "No label to apply".

Ejemplo 4: Aplicar la etiqueta "General" a un único archivo, que requiere justificación

PS C:\> Set-FileLabel -Path \\Finance\Projects\Analysis.xlsx -LabelId d9f23ae3-1324-1234-1234-f515f824c57b -JustificationMessage 'The previous label no longer applies'
FileName                          Status      Comment
--------                          ------      ------------
\\finance\projects\analysis.xlsx  Success

Este comando establece la etiqueta "General" para un archivo que ya está etiquetado con una etiqueta de confidencialidad superior. La directiva de etiqueta de confidencialidad está configurada para requerir justificación para quitar una etiqueta o reducir la clasificación. Dado que el comando incluye un mensaje de justificación, la nueva etiqueta se aplica correctamente.

Ejemplo 5: Protección de un archivo con permisos personalizados

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

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

El primer comando crea un objeto de directiva de protección ad hoc que concede a los usuarios de diferentes organizaciones derechos de uso de los permisos revisores y también aplica una fecha de expiración.

El segundo comando protege un único archivo denominado Analysis.docx mediante los permisos personalizados del objeto de directiva de protección ad hoc almacenado.

Ejemplo 6: Aplicar una etiqueta y permisos personalizados al archivo

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

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

El segundo comando aplica una etiqueta a un único archivo denominado Analysis.docx y también protege el archivo mediante los permisos personalizados del objeto de directiva de protección ad hoc almacenado. Si la etiqueta está configurada para la configuración de protección, se reemplazan por los permisos personalizados.

Ejemplo 7: Examinar todos los archivos de una carpeta y cualquiera de sus subcarpetas, y aplicar etiquetas según las condiciones configuradas para el etiquetado automático

PS C:\> 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    :

Este comando examina todos los archivos de la carpeta Projects y cualquiera de sus subcarpetas, y establece las etiquetas según las condiciones configuradas en la directiva de etiquetado automático. En este ejemplo hay cinco archivos y dos de ellos se etiquetan automáticamente. El archivo Datasheet.pdf no está etiquetado porque su contenido no coincide con las condiciones configuradas para el etiquetado automático Analysis.xlsx ya estaba etiquetado manualmente y Pricelist.xlsx tiene una etiqueta superior. Dado que el comando se ejecuta sin el parámetro -Force , las etiquetas existentes para Analysis.xlsx y Pricelist.xlsx no se sobrescriben.

Si las etiquetas aplicadas también se configuran para aplicar la protección de Rights Management, los archivos que se etiquetan correctamente con este comando también están protegidos. En este caso, el propietario de Rights Management (que tiene el permiso de control total de Rights Management) de estos archivos es el usuario que ejecutó el comando de PowerShell.

Dado que se especifica el parámetro PreserveFileDetails, la fecha modificada de los archivos etiquetados permanece sin cambios.

Ejemplo 8: Examinar todos los archivos de una carpeta y cualquiera de sus subcarpetas, y aplicar etiquetas según las condiciones configuradas para el etiquetado automático, invalidando las etiquetas existentes

PS C:\> 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    :

Este comando es similar al ejemplo anterior en que también examina todos los archivos de la carpeta Projects y cualquiera de sus subcarpetas, y establece las etiquetas según las condiciones configuradas para el etiquetado automático. Sin embargo, esta vez, dado que el comando incluye el parámetro -Force , también reemplaza la etiqueta existente para Dashboard.xlsxy Pricelist.xlsx.

El contenido de Datasheet.pdf no coincidía con ninguna condición configurada y este archivo permanece sin una etiqueta.

Ejemplo 9: Examen de un archivo en modo WhatIf para todos los tipos de información confidencial conocidos

PS C:\> Set-FileLabel -AutoLabel -Path C:\Projects\Project1.docx -WhatIf -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                 :

Este comando detecta todos los tipos de información conocidos en Project1.docx archivo sin aplicar protección ni etiqueta.

Ejemplo 10: Examen de un archivo en modo WhatIf para tipos de información confidencial específicos

PS C:\> Set-FileLabel -AutoLabel -Path C:\Projects\Project1.docx -WhatIf -DiscoveryInfoTypes "50842eb7-edc8-4019-85dd-5a5c1f2bb085","a44669fe-0d48-453d-a9b1-2cc83f2cba77"

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                 :

Este comando detecta los tipos de información específicos de "Número de tarjeta de crédito" y "Número de seguro social (SSN)" en Project1.docx archivo sin aplicar protección ni etiqueta.

Ejemplo 11: Examinar un archivo en modo WhatIf para obtener tipos de información confidencial específicos y mostrar los valores encontrados

PS C:\> $x=Set-FileLabel -AutoLabel -Path "C:\Projects\Project1.docx" -WhatIf -DiscoveryInfoTypes "50842eb7-edc8-4019-85dd-5a5c1f2bb085","a44669fe-0d48-453d-a9b1-2cc83f2cba77"
PS C:\> $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}


PS C:\> $x.MatchedInformationTypes[0].SensitiveContents | fl

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

Al igual que en el ejemplo anterior, el primer comando detecta los tipos de información específicos de "Número de tarjeta de crédito" y "Número de seguridad social (SSN)" en Project1.docx archivo sin aplicar protección ni etiqueta. Sin embargo, en este ejemplo, los resultados se almacenan en una variable para su posterior procesamiento.

A continuación, se usa el segundo comando para mostrar el contenido de los tipos de información coincidentes, que incluye el parámetro SensitiveContents.

El comando final muestra y da formatos para facilitar la lectura de los datos identificados por el primer tipo de información confidencial, que en este ejemplo es los detalles de la tarjeta de crédito.

Parámetros

-AutoLabel

Cuando se usa -AutoLabel, el cmdlet se ejecuta en modo de etiquetado automático. Cuando no se usa el cmdlet -AutoLabel, se ejecuta en modo de etiquetado manual.

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-CustomPermissions

Especifica el nombre de variable que almacena una directiva de protección ad hoc, que se creó mediante el cmdlet New-CustomPermissions . La directiva de protección ad hoc se usa para proteger el archivo o los archivos con permisos personalizados.

Type:	AIPCustomPermissions
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-DiscoveryInfoTypes

Especifique los tipos de información confidencial que se detectarán al usar el parámetro WhatIf .

Si desea buscar tipos de información confidencial específicos, especifique el número de identificador de entidad para ese tipo de información, que puede encontrar en Tipos de información confidencial en Exchange Server.

Por ejemplo, "50842eb7-edc8-4019-85dd-5a5c1f2bb085" es el número que se debe especificar para el tipo de información confidencial Número de tarjeta de crédito.

Type:	String[]
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Force

Cuando se cumplen las condiciones configuradas, reemplaza una etiqueta existente.

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-JustificationMessage

Motivo de justificación para reducir la etiqueta de clasificación, quitar una etiqueta o quitar la protección, si la directiva de confidencialidad requiere que los usuarios proporcionen esta información. Si al establecer una etiqueta se desencadena la justificación y no se proporciona este motivo, no se aplica la etiqueta. En este caso, el estado que se devuelve es "Omitido" con el comentario "Justificación necesaria".

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-LabelId

Especifica la identidad (ID) de la etiqueta que se va a aplicar. Si una etiqueta tiene subetiquetas, especifique únicamente el identificador de una subetiqueta, no el de la etiqueta principal.

Para buscar el identificador de etiqueta:

El valor del identificador de etiqueta no se muestra en el portal de cumplimiento Microsoft Purview. Sin embargo, puede usar el siguiente comando de PowerShell Office 365 Security & Compliance Center para encontrar este valor:Get-Label | Format-Table -Property DisplayName, Name, Guid

Para los archivos que tienen etiquetas aplicadas, también puede ejecutar el cmdlet Get-FileStatus para identificar el identificador de etiqueta (MainLabelId o SubLabelId).

Type:	Guid
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-Owner

Especifica el propietario para aplicar la etiqueta o la protección al archivo.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Path

Especifica una ruta de acceso local, una ruta de acceso de red o una dirección URL de SharePoint Server a los archivos para los que desea obtener la información de etiqueta y protección.

No se admiten los caracteres comodín ni las ubicaciones de WebDAV.

En el caso de las rutas de acceso de SharePoint, se admite lo siguiente:

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

Por ejemplo:

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

Las rutas de acceso pueden incluir espacios al incluir el valor de ruta de acceso entre comillas.

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

-PreserveFileDetails

Especifique este parámetro para dejar la fecha de modificación (Windows y SharePoint) y los valores modificados por (SharePoint) sin modificar para los documentos que etiquete:

En el caso de los archivos locales o de red, el valor fecha de modificación permanece sin cambios.
En el caso de los archivos de SharePoint, los valores Fecha de modificación y Modificado por permanecen sin cambios.

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-WhatIf

Muestra lo que sucedería si se ejecutara el cmdlet. El cmdlet no se ejecuta.

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

Entradas

System.String[]

Salidas

Microsoft.InformationProtection.Powershell.AIP.Results.SetAIPFileResult