Cómo usar la API de gráfico de etiquetas de sensibilidad de extracción

Recuperar información de etiquetas de confidencialidad para documentos de SharePoint Online

En julio de 2022, escribí sobre el uso de Graph API para crear un informe de archivos almacenados en un sitio de SharePoint Online. Fue un proyecto divertido y aprendí mucho sobre cómo navegar en SharePoint Online con solicitudes de Graph usando conceptos como unidades y elementos de unidad. Utilizo el script para generar informes con frecuencia, por lo que obtuve algo del ejercicio.

Una cosa que no pude informar fue si los archivos informados tenían etiquetas de confidencialidad. Creé scripts en el pasado para recuperar archivos con etiquetas de confidencialidad (este ejemplo ofrece la posibilidad de descifrar archivos con etiquetas de confidencialidad usando el cmdlet Unlock-SPOSensitivityLabelEncryptedFile) donde una solicitud como la que se muestra a continuación recupera la información necesaria:

€Uri = "https://graph.microsoft.com/v1.0/sites/€(€Siteid)/lists/Documents/Drive/Items/€(€DriveId)/children?`€select=sensitivitylabel,weburl,name"}  [array]€Files = (Invoke-RestMethod -Uri €URI -Headers €Headers -Method Get -ContentType "application/json") 

Podría haber continuado por ese camino para recuperar la información de la etiqueta de confidencialidad, pero decidí usar la nueva API extractSensitivityLabels. La gran diferencia con esta API es que cuando la usa, la API actualiza «los metadatos de un elemento de la unidad con los últimos detalles de la etiqueta asignada». Como veremos, este aspecto de la API puede tener un efecto secundario inesperado.

Además, la API puede manejar la extracción de «una o más etiquetas de confidencialidad asignadas a un elemento de la unidad». No sabía que los documentos de SharePoint Online pueden tener más de una etiqueta de confidencialidad, pero aparentemente pueden hacerlo si un documento pasa de un inquilino a otro y acumula etiquetas de cada inquilino. Sin embargo, una vez que un usuario aplica una etiqueta con cifrado, el documento puede almacenar solo esa etiqueta.

Cambios realizados para recuperar datos de la etiqueta de confidencialidad

Para probar la API, agregué código a la función UnpackFilesRecursively en el script original (disponible en GitHub). Si desea probar el script, descárguelo e inserte el siguiente código para reemplazar la función UnpackFilesRecursively original:

Function UnpackFilesRecursively { # Unpack set of items (files and folders) param (         [parameter(Mandatory = €true)]         €Items, # Items to unpack 	 		[parameter(Mandatory = €true)]         €SiteUri, # Base site URI 		 		[parameter(Mandatory = €true)]         €FolderPath, # Folder path 		         [parameter(Mandatory = €true)]         €SiteFiles, 		 		[parameter(Mandatory = €false)] 		[bool]€IsNextLink     )    # Sensitivity label document types   [array]€ValidDocumentTypes = "docx", "pptx", "xlsx", "pdf"   # Find sub-folders that we need to check for files   [array]€Folders = €Items.Value | Where-Object {€_.Folder.ChildCount -gt 0 }   # And any files in the folder   [array]€Files = €Items.Value | Where-Object {€_.Folder.ChildCount -eq €Null}      €before = €SiteFiles.count      # Report the files   ForEach (€D in €Files) {     €LabelName = €Null     €FileSize = FormatFileSize €D.Size     # Check Sensitivity label     €Type = €D.Name.Split(".")[1]     If (€Type -in €ValidDocumentTypes) {       # Write-Host "Processing filename:" €D.Name       €Uri = ("https://graph.microsoft.com/beta/sites/{0}/drive/items/{1}/extractSensitivityLabels" -f €Site.Id, €D.id)       Try {          €LabelsInfo = Invoke-MgGraphRequest -Uri €Uri -Method POST }       Catch {          Write-Host ("Failure reading data from file {0}" -f €D.Name)           €LabelsInfo = €Null       }       # Resolve sensitivity label identifier if one is found to find label name       If (€LabelsInfo.labels.sensitivityLabelId) {        #  Write-Host "Label Id" €LabelsInfo.labels.sensitivityLabelId          €LabelName = €LabelsHash[€LabelsInfo.labels.sensitivityLabelId ]      } # End if Label data     } # End if type     €ReportLine  = [PSCustomObject] @{            FileName            = €D.Name         Folder              = €FolderPath         Author              = €D.createdby.user.displayname         Created             = €D.createdDateTime         Modified            = €D.lastModifiedDateTime         Size                = €FileSize         'Sensitivity Label' = €LabelName         Uri                 = €D.WebUrl          Id                  = €D.Id}      €SiteFiles.Add(€ReportLine)    } # End If    €NextLink = €Items."@odata.nextLink"   €Uri = €Items."@odata.nextLink"   While (€NextLink) {      €MoreData = Invoke-MgGraphRequest -Uri €Uri -Method Get     UnpackFilesRecursively -Items €MoreData -SiteUri €SiteUri -FolderPath €FolderPath -SiteFiles €SiteFiles -IsNextLink €true        €NextLink = €MoreData."@odata.nextLink"     €Uri = €MoreData."@odata.nextLink"    } # End While      €count = €SiteFiles.count - €before   if (-Not €IsNextLink) {     Write-Host "  €FolderPath (€count)"   }      # Report the files in each sub-folder   ForEach (€Folder in €Folders) { 	€NewFolderPath = €FolderPath + "/" + €Folder.Name 	€Uri = €SiteUri + "/" + €Folder.parentReference.path + "/" + €Folder.Name + ":/children" 	€SubFolderData = Invoke-MgGraphRequest -Uri €Uri -Method Get     UnpackFilesRecursively -Items €SubFolderData -SiteUri €SiteUri -FolderPath €NewFolderPath -SiteFiles €SiteFiles -IsNextLink €IsNextLink   } # End Foreach Folders } 

Puede ver que el script declara el conjunto de extensiones de archivo y verificará las etiquetas de confidencialidad. Agregué las extensiones para Word, PowerPoint, Excel y PDF a la matriz. Con el tiempo, dado que Microsoft Information Protection admite tipos de archivos adicionales, se pueden agregar las extensiones para esos archivos.

Interpretación de los datos de la etiqueta de sensibilidad

La información devuelta para un archivo se ve así:

Name                           Value ----                           ----- tenantId                       a662313f-14fc-43a2-9a7a-d2e27f4f3478 assignmentMethod               standard sensitivityLabelId             1b070e6f-4b3c-4534-95c4-08335a5ca610 

No todo el mundo habla GUID con fluidez, por lo que para interpretar el identificador de la etiqueta de sensibilidad al nombre de la etiqueta, creamos una tabla hash para contener los identificadores de etiquetas y los nombres que el script puede buscar. Este código debe ejecutarse al comienzo del script:

Connect-IPPSSession [Array]€LabelData = Get-Label | Select-Object ImmutableId, DisplayName €Global:LabelsHash = @{} ForEach (€L in €LabelData) {€LabelsHash.Add([string]€L.ImmutableId,[string]€L.DisplayName) } 

Todo funciona muy bien (Figura 1) con la advertencia de que la secuencia de comandos ahora realiza una solicitud de gráfico adicional para cada documento con un tipo de archivo compatible. Esto inevitablemente ralentizará el procesamiento. Ejecuté el script en bibliotecas de documentos que contienen miles de archivos y el rendimiento no fue inaceptable. Puede tomar aproximadamente un segundo obtener la información de la etiqueta para un documento muy grande (por ejemplo, un documento de Word de 38 MB de 1400 páginas), pero los archivos más pequeños no causan una gran demora.

Figura 1: Información de etiquetas de confidencialidad de informes para archivos en una biblioteca de documentos de SharePoint Online

Discrepancias de documentos

Como se señaló anteriormente, hubo un efecto secundario inesperado. Debido a que la API actualiza los documentos con los metadatos de etiquetas más recientes, ejecutar el script en una gran biblioteca de documentos provocó que llegaran diez notificaciones de discrepancias de documentos en rápida sucesión. La explicación era simple: cada etiqueta de confidencialidad tiene un orden de prioridad. Si coloca un documento con una etiqueta de prioridad alta en un sitio al que se le asignó una etiqueta de prioridad más baja (administración de contenedores), se produce una discrepancia. En mi caso, la prioridad de las etiquetas de confidencialidad asignadas a los documentos cambió desde su asignación original y los documentos ahora tenían una etiqueta de mayor prioridad que el sitio.

Informes de gobierno de datos

Uno de los beneficios de la licencia de administración avanzada de Microsoft Syntex-SharePoint es que los administradores pueden acceder a los informes de control de datos a través del centro de administración de SharePoint Online (Figura 2).

Figura 2: Informes de etiquetas de confidencialidad disponibles para el control de datos

Los informes de gobierno de datos no son nada especial y ciertamente no son una buena razón para comprar la licencia de gestión avanzada. Puede hacer un trabajo mucho mejor usted mismo con PowerShell, incluida la salida a (con el módulo PSWriteHTML) o Excel (con el módulo ImportExcel). Si está interesado en la licencia de administración avanzada de Microsoft Syntex-SharePoint, concéntrese en características como el bloqueo de descargas para grabaciones de reuniones de Teams. Serás más feliz.

Próxima parada, asignación de etiquetas de sensibilidad con una API gráfica

Junto con una API para recuperar la información de la etiqueta de confidencialidad para los documentos de SharePoint Online, la API de gráfico AssignSensitivityLabel está disponible para asignar etiquetas de confidencialidad a los documentos. El problema es que esta API está medida y protegida. Medido significa que paga para usarlo a través de una suscripción de Azure. Protegido significa que Microsoft debe dar su consentimiento para que una aplicación use la API. Solicité el permiso y preparé a Azure para aceptar cargos. Una vez que Microsoft dé el visto bueno, volveré a informar sobre el uso de la API para asignar etiquetas de confidencialidad.