API File di Microsoft Information Protection SDK - Giustificazione dell'azione per abbassare un'etichetta di riservatezza per un file (C#)Microsoft Information Protection SDK File API - Action Justification for lowering a sensitivity label on a file (C#)

Questa guida di avvio rapido riguarda la gestione di un'operazione di downgrade di etichette quando i criteri per le etichette richiedono una giustificazione. In questo contesto verrà usata l'interfaccia IFileHandler per modificare le etichette di un file.This quickstart addresses handling of a downgrade label operation when the label policy requires justification.Here, we will use IFileHandler interface for changing the labels of a file. Per altri dettagli, vedere le informazioni di riferimento sull'API.For further details consult API reference.

PrerequisitiPrerequisites

Se non è già stato fatto, completare i prerequisiti seguenti prima di continuare:If you haven't already, be sure to complete the following prerequisites before continuing:

  • In primo luogo completare Avvio rapido: Impostare/ottenere le etichette di riservatezza (C#), che crea una soluzione Visual Studio iniziale, per creare un elenco delle etichette di riservatezza di un'organizzazione, nonché per impostare e leggere le etichette di riservatezza in/da un file.Complete Quickstart: Set/get sensitivity labels(C#) which builds a starter Visual Studio solution to list an organization's sensitivity labels and to set and read sensitivity labels to/from a file. Questa guida di avvio rapido "Procedura - Eseguire il downgrade o la rimozione di un'etichetta che richiede una giustificazione (C#)" si basa su quella precedente.This "How to - Downgrade/Remove a label that needs a justification C#" Quickstart builds on the previous one.
  • Facoltativamente: rivedere i concetti relativi ai gestori di file in MIP SDK.Optionally: Review File handlers concepts in the MIP SDK concepts.

Aggiungere la logica per impostare un'etichetta inferiore su un file protettoAdd logic to set a lower label to a protected file

Aggiungere la logica per impostare un'etichetta di riservatezza su un file usando l'oggetto gestore di file.Add logic to set a sensitivity label on a file, using the File handler object.

  1. Aprire la soluzione Visual Studio creata nell'articolo precedente "Avvio rapido: Impostare/ottenere etichette di riservatezza (C#).Open the Visual Studio solution you created in the previous "Quickstart: Set/get sensitivity labels(C#).

  2. Usare Esplora soluzioni per aprire il file con estensione cs nel progetto che contiene l'implementazione del metodo Main().Using Solution Explorer, open the .cs file in your project that contains the implementation of the Main() method. Per impostazione predefinita il file ha lo stesso nome del progetto che lo contiene, specificato durante la creazione del progetto.It defaults to the same name as the project containing it, which you specified during project creation.

  3. Aggiornare il valore <label-id> dalla guida di avvio rapido precedente impostando un'etichetta di riservatezza che richiede una giustificazione per l'abbassamento.Update the <label-id> value from previous quickstart to a sensitivity label which requires justification for lowering. Durante l'esecuzione di questa guida di avvio rapido, si imposterà prima questa etichetta e quindi si tenterà di abbassarla tramite frammenti di codice in ulteriori passaggi.During this quickstart run, we'll set this label first and then try to lower it via code snippets in further steps.

  4. Verso la fine del corpo di Main(), sotto Console.ReadKey() e prima del bocco di arresto dell'applicazione (il punto in cui è stata interrotta la guida di avvio rapido precedente), inserire il codice seguente.Toward the end of the Main() body, below Console.ReadKey() and above application shutdown block (where you left off in the previous Quickstart), insert the following code.

    //Set paths and label ID
    string lowerInput = actualOutputFilePath;
    string lowerActualInput = lowerInput;
    string newLabelId = "<new-label-id>";
    string lowerOutput = "<downgraded-labled-output>";
    string lowerActualOutput = lowerOutput;
    
    //Create a file handler for that file
    var downgradeHandler = Task.Run(async () => await fileEngine.CreateFileHandlerAsync(lowerInput, lowerActualInput, true)).Result;
    
    //Set Labeling Options
    LabelingOptions options = new LabelingOptions()
    {
        AssignmentMethod = AssignmentMethod.Standard
    };
    
    try
    {
        //Try to set new label
        downgradeHandler.SetLabel(fileEngine.GetLabelById(newLabelId), options, new ProtectionSettings());
    }
    
    catch (Microsoft.InformationProtection.Exceptions.JustificationRequiredException)
    {
        //Request justification from user
        Console.Write("Please provide justification for downgrading a label: ");
        string justification = Console.ReadLine();
    
        options.IsDowngradeJustified = true;
        options.JustificationMessage = justification;
    
        //Set new label
        downgradeHandler.SetLabel(fileEngine.GetLabelById(newLabelId), options, new ProtectionSettings());
    }
    
    // Commit changes, save as outputFilePath
    var downgradedResult = Task.Run(async () => await downgradeHandler.CommitAsync(lowerActualOutput)).Result;
    
    // Create a new handler to read the labeled file metadata
    var commitHandler = Task.Run(async () => await fileEngine.CreateFileHandlerAsync(lowerOutput, lowerActualOutput, true)).Result;
    
    // Get the label from output file
    var newContentLabel = commitHandler.Label;
    Console.WriteLine(string.Format("Getting the new label committed to file: {0}", lowerOutput));
    Console.WriteLine(string.Format("File Label: {0} \r\nIsProtected: {1}", newContentLabel.Label.Name, newContentLabel.IsProtectionAppliedFromLabel.ToString()));
    Console.WriteLine("Press a key to continue.");
    Console.ReadKey();
    
    
  5. Verso la fine di Main() trovare il blocco di arresto dell'applicazione creato nella guida di avvio rapido precedente e aggiungerlo sotto le righe del gestore per rilasciare le risorse.Toward the end of Main() find the application shutdown block created in previous quickstart and add below handler lines to release resources.

    downgradeHandler = null;
    commitHandler = null;
    
  6. Sostituire i valori segnaposto nel codice sorgente, usando i valori seguenti:Replace the placeholder values in the source code using the following values:

    SegnapostoPlaceholder ValoreValue
    <downgraded-labled-output> Percorso del file di output in cui si vuole salvare il file modificato.The output file path you want to save modified file to.
    <new-label-id> ID modello, copiato dall'output della console nell'Avvio rapido precedente, ad esempio: bb7ed207-046a-4caf-9826-647cff56b990.A template ID, copied from the console output in the previous Quickstart, for example: bb7ed207-046a-4caf-9826-647cff56b990. Assicurarsi che abbia una riservatezza inferiore rispetto all'etichetta del file precedentemente protetto.Make sure it has lower sensitivity than the previously protected file label.

Compilare e testare l'applicazioneBuild and test the application

Compilare e testare l'applicazione client.Build and test your client application.

  1. Usare CTRL+MAIUSC+B (Compila soluzione) per compilare l'applicazione client.Use CTRL-SHIFT-B (Build Solution) to build your client application. Se non si registrano errori di compilazione, premere F5 (Avvia debug) per eseguire l'applicazione.If you have no build errors, use F5 (Start debugging) to run your application.

  2. Se il progetto viene compilato ed eseguito correttamente, l'applicazione potrebbe richiedere l'autenticazione tramite ADAL ogni volta che il SDK chiama il metodo AcquireToken().If your project builds and runs successfully, the application may prompt for authentication via ADAL each time the SDK calls your AcquireToken() method. Se esistono già credenziali memorizzate nella cache, non verrà richiesto di accedere e visualizzare l'elenco delle etichette e quindi le informazioni sull'etichetta applicata e sul file modificato.If cached credentials already exist, you won't be prompted to sign in and see the list of labels, followed by the information on the applied label and modified file.

  Personal : 73c47c6a-eb00-4a6a-8e19-efaada66dee6
  Public : 73254501-3d5b-4426-979a-657881dfcb1e
  General : da480625-e536-430a-9a9e-028d16a29c59
  Confidential : 569af77e-61ea-4deb-b7e6-79dc73653959
  Highly Confidential : 905845d6-b548-439c-9ce5-73b2e06be157
  Press a key to continue.

  Getting the label committed to file: c:\Test\Test_labeled.docx
  Name: Confidential
  IsProtected: True
  Press any key to continue . . .

  Please provide justification for downgrading a label: Lower label approved.
  Getting the new label committed to file: c:\Test\Test_downgraded.docx
  File Label: General
  IsProtected: False
  Press a key to continue.

Si noti che è necessario seguire un approccio simile per l'operazione DeleteLabel(), nel caso in cui l'etichetta da eliminare da un file richieda una giustificazione in base ai criteri per le etichette. La funzione DeleteLabel()Please note, similar approach also applies to DeleteLabel() operation, in case the label being deleted from a file requires a justification as per label policy.DeleteLabel() genera un'eccezione JustificationRequiredException e il flag IsDowngradeJustified deve essere impostato su true nella gestione delle eccezioni prima di eliminare correttamente un'etichetta.function throws a JustificationRequiredException exception and IsDowngradeJustified flag should be set to true in exception handling before deleting a label successfully.