Sdílet prostřednictvím

Microsoft Information Protection SDK – Koncepty obslužných rutin souborů

  • Článek

V sadě MIP File SDK zveřejňuje všechny různé operace, mip::FileHandler které je možné použít ke čtení a zápisu popisků nebo ochrany, a to napříč sadou typů souborů, pro které je integrovaná podpora.

Podporované typy souborů

  • Formáty souborů Office založené na OPC (Office 2010 a novější)
  • Starší formáty souborů Office (Office 2007)
  • PDF
  • Obecná podpora PFILE
  • Soubory, které podporují Adobe XMP

Funkce obslužné rutiny souborů

mip::FileHandler zveřejňuje metody pro čtení, zápis a odebírání popisků i informací o ochraně. Úplný seznam najdete v referenčních informacích k rozhraní API.

V tomto článku jsou popsány následující metody:

  • GetLabelAsync()
  • SetLabel()
  • DeleteLabel()
  • RemoveProtection()
  • CommitAsync()

Požadavky

Vytvoření pro FileHandler práci s konkrétním souborem vyžaduje:

  • Provede FileProfile.
  • A FileEngine added to the FileProfile
  • Třída, která dědí mip::FileHandler::Observer

Vytvoření obslužné rutiny souboru

Prvním krokem při správě všech souborů v sadě File SDK je vytvoření objektu FileHandler . Tato třída implementuje všechny funkce potřebné k získání, nastavení, aktualizaci, odstranění a potvrzení změn popisků do souborů.

FileHandler Vytvoření je stejně snadné jako volání FileEnginefunkce pomocí CreateFileHandlerAsync příslibu a budoucího vzoru.

CreateFileHandlerAsync přijímá tři parametry: Cesta k souboru, který by měl být přečten nebo změněn, mip::FileHandler::Observer pro asynchronní oznámení událostí a příslib pro FileHandler.

Poznámka: Třída mip::FileHandler::Observer musí být implementována v odvozené třídě, jak CreateFileHandler vyžaduje Observer objekt.

auto createFileHandlerPromise = std::make_shared<std::promise<std::shared_ptr<mip::FileHandler>>>();
auto createFileHandlerFuture = createFileHandlerPromise->get_future();
fileEngine->CreateFileHandlerAsync(filePath, std::make_shared<FileHandlerObserver>(), createFileHandlerPromise);
auto fileHandler = createFileHandlerFuture.get();

Po úspěšném vytvoření objektu FileHandler je možné provádět operace se soubory (get/set/delete/commit).

Čtení popisku

Požadavky na metadata

Existuje několik požadavků na úspěšné čtení metadat ze souboru a překlad do něčeho, co je možné použít v aplikacích.

  • Popisek, který se čte, musí stále existovat ve službě Microsoft 365. Pokud se úplně odstraní, sada SDK nebude moct získat informace o daném popisku a vrátí chybu.
  • Metadata souboru musí být nedotčena. Tato metadata zahrnují:
    • Atribut1
    • Atribut2

GetLabelAsync()

Když jsme vytvořili obslužnou rutinu tak, aby odkazovala na určitý soubor, vrátíme se k vzoru příslibu a budoucnosti, abychom popisek asynchronně přečetli. Příslib je pro mip::ContentLabel objekt, který obsahuje všechny informace o použitém popisku.

Po vytvoření instance promise objektů a future objektů přečteme popisek voláním fileHandler->GetLabelAsync() a poskytnutím parametru promise lone. A konečně, popisek může být uložen v objektu mip::ContentLabel , který získáme z objektu future.

auto loadPromise = std::make_shared<std::promise<std::shared_ptr<mip::ContentLabel>>>();
auto loadFuture = loadPromise->get_future();
fileHandler->GetLabelAsync(loadPromise);
auto label = loadFuture.get();

Data popisků je možné číst z objektu label a předávat do jakékoli jiné součásti nebo funkcí aplikace.

Nastavení popisku

Nastavení popisku je proces se dvěma částmi. Nejprve vytvoření obslužné rutiny, která odkazuje na příslušný soubor, lze popisek nastavit voláním FileHandler->SetLabel() s některými parametry: mip::Label, mip::LabelingOptionsa mip::ProtectionOptions. Nejprve musíme ID popisku přeložit na popisek a pak definovat možnosti popisování.

Řešení ID popisku na mip::Label

Prvním parametrem mip::Labelfunkce SetLabel je . Aplikace často pracuje s identifikátory popisků, nikoli s popisky. Identifikátor popisku lze přeložit na mip::Label identifikátor volání GetLabelById v souboru nebo modulu zásad:

mip::Label label = mEngine->GetLabelById(labelId);

Možnosti popisování

Druhý parametr vyžadovaný k nastavení popisku je mip::LabelingOptions.

LabelingOptions určuje další informace o popisku, jako AssignmentMethod je popisek a odůvodnění akce.

  • mip::AssignmentMethod je enumerátor, který má tři hodnoty: STANDARD, PRIVILEGEDnebo AUTO. Další podrobnosti najdete v mip::AssignmentMethod referenčních informacích.
  • Odůvodnění je vyžadováno pouze v případě, že je zásada služby vyžaduje a při snížení stávající citlivosti souboru.

Tento výnip ukazuje vytvoření objektu mip::LabelingOptions a nastavení downgrade odůvodnění a zprávy.

auto labelingOptions = mip::LabelingOptions(mip::AssignmentMethod::STANDARD);
labelingOptions.SetDowngradeJustification(true, "Because I made an educated decision based upon the contents of this file.");

Nastavení ochrany

Některé aplikace můžou potřebovat provádět operace jménem delegovaná identita uživatele. Třída mip::ProtectionSettings umožňuje aplikaci definovat delegovanou identitu na obslužnou rutinu. Dříve delegování prováděly třídy modulu. To mělo významné nevýhody v režii aplikací a odezvách služeb. Přesunutím delegovaných uživatelských nastavení do mip::ProtectionSettings třídy obslužné rutiny tuto režii eliminujeme, což vede k lepšímu výkonu pro aplikace, které provádějí mnoho operací jménem různorodých sad identit uživatelů.

Pokud se delegování nevyžaduje, předejte mip::ProtectionSettings() funkci SetLabel . Pokud je delegování potřeba, můžete ho dosáhnout vytvořením objektu mip::ProtectionSettings a nastavením delegované poštovní adresy:

mip::ProtectionSettings protectionSettings; 
protectionSettings.SetDelegatedUserEmail("alice@contoso.com");

Nastavení popisku

Po načtení mip::Label pomocí ID, nastavení možností popisování a volitelně nastavení ochrany můžete popisek nastavit u obslužné rutiny.

Pokud jste nenastavili nastavení ochrany, nastavte popisek voláním SetLabel obslužné rutiny:

fileHandler->SetLabel(label, labelingOptions, mip::ProtectionSettings());

Pokud jste k provedení delegovaných operací vyžadovali nastavení ochrany, postupujte takto:

fileHandler->SetLabel(label, labelingOptions, protectionSettings);

Když teď nastavíte popisek v souboru odkazovaném obslužnou rutinou, stále existuje ještě jeden krok k potvrzení změny a zápisu souboru na disk nebo vytvoření výstupního datového proudu.

Potvrzení změn

Posledním krokem při potvrzení jakékoli změny souboru v sadě MIP SDK je potvrzení změny. Toho se dosahuje pomocí FileHandler->CommitAsync() funkce.

K implementaci funkce závazku se vrátíme k příslibu a budoucnosti a vytvoříme příslib pro .bool Funkce CommitAsync() vrátí hodnotu true, pokud operace proběhla úspěšně nebo nepravda, pokud z nějakého důvodu selhala.

Po vytvoření a promise future, CommitAsync() je volána a dva parametry zadané: cesta k výstupnímu souboru (std::string) a příslib. Nakonec se výsledek získá získáním hodnoty objektu future .

auto commitPromise = std::make_shared<std::promise<bool>>();
auto commitFuture = commitPromise->get_future();
fileHandler->CommitAsync(outputFile, commitPromise);
auto wasCommitted = commitFuture.get();

Důležité: FileHandler Stávající soubory se neaktualizují ani nepřepíší. Je na vývojáři, aby implementoval nahrazení souboru, který je označený.

Pokud zapíšete popisek do FileA.docx, vytvoří se s použitým popiskem kopie souboru FileB.docx. Kód musí být zapsán pro odebrání nebo přejmenování FileA.docx a přejmenování FileB.docx.

Odstranění popisku

auto fileHandler = mEngine->CreateFileHandler(filePath, std::make_shared<FileHandlerObserverImpl>());
fileHandler->DeleteLabel(mip::AssignmentMethod::PRIVILEGED, "Label unnecessary.");
auto commitPromise = std::make_shared<std::promise<bool>>();
auto commitFuture = commitPromise->get_future();
fileHandler->CommitAsync(outputFile, commitPromise);

Odebrání ochrany

Vaše aplikace MIP File SDK musí ověřit, že uživatel má práva k odebrání ochrany ze souboru, ke kterému se přistupuje. Toho lze dosáhnout provedením kontroly přístupu před odebráním ochrany.

Funkce RemoveProtection() se chová podobným způsobem jako SetLabel() nebo DeleteLabel(). Metoda je volána u existujícího FileHandler objektu a pak musí být potvrzena změna.

Důležité

Jako vývojář aplikace je to vaše reponsibility k provedení této kontroly přístupu. Nepodařilo se správně provést kontrolu přístupu při úniku dat.

Příklad jazyka C++:

// Validate that the file referred to by the FileHandler is protected.
if (fileHandler->GetProtection() != nullptr)
{
    // Validate that user is allowed to remove protection.
    if (fileHandler->GetProtection()->AccessCheck(mip::rights::Export() || fileHandler->GetProtection()->AccessCheck(mip::rights::Owner()))
    {
        auto commitPromise = std::make_shared<std::promise<bool>>();
        auto commitFuture = commitPromise->get_future();
        // Remove protection and commit changes to file.
        fileHandler->RemoveProtection();
        fileHandler->CommitAsync(outputFile, commitPromise);
        result = commitFuture.get();
    }
    else
    {
        // Throw an exception if the user doesn't have rights to remove protection.
        throw std::runtime_error("User doesn't have EXPORT or OWNER right.");
    }
}

Příklad .NET:

if(handler.Protection != null)
{                
    // Validate that user has rights to remove protection from the file.                    
    if(handler.Protection.AccessCheck(Rights.Export) || handler.Protection.AccessCheck(Rights.Owner))
    {
        // If user has Extract right, remove protection and commit the change. Otherwise, throw exception. 
        handler.RemoveProtection();
        bool result = handler.CommitAsync(outputPath).GetAwaiter().GetResult();     
        return result;   
    }
    else
    {
        throw new Microsoft.InformationProtection.Exceptions.AccessDeniedException("User lacks EXPORT right.");
    }
}