Microsoft Information Protection SDK – principy obslužné rutiny souborů

V sadě MIP File SDK prvek mip::FileHandler zpřístupňuje veškeré operace, které lze použít ke čtení a zápisu popisků nebo ochran pro řadu typů souborů, pro které je k dispozici 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)
  • soubor PDF
  • Obecná podpora PFILE
  • Soubory, které podporují Adobe XMP

Funkce pro obsluhu souborů

mip::FileHandler poskytuje metody pro čtení, zápis a odstraňování štítků 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í FileHandler pro práci s konkrétním souborem vyžaduje:

  • A FileProfile
  • Přidání FileEngine do FileProfile
  • Třída, která dědí mip::FileHandler::Observer

Vytvořit obslužnou rutinu pro práci se soubory

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ů.

Vytvoření FileHandler je stejně snadné jako zavolání funkce CreateFileHandlerAsync z FileEngine pomocí vzoru promise/future.

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).

Přečtěte štítek

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.

  • Štítek, který se načítá, musí ve službě Microsoft 365 stále existovat. 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í:
    • Attribute1
    • Attribute2

GetLabelAsync()

Poté, co jsme vytvořili handler tak, aby směřoval na konkrétní soubor, vrátíme se ke vzoru promise/future, abychom asynchronně načetli popisek. Promise je pro objekt mip::ContentLabel, který obsahuje všechny informace o použitém štítku.

Po vytvoření instancí objektů promise a future přečteme popisek voláním fileHandler->GetLabelAsync() s promise jako jediným parametrem. 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, po vytvoření obslužné rutiny, která odkazuje na příslušný soubor, lze popisek nastavit voláním FileHandler->SetLabel() s několika parametry: mip::Label, mip::LabelingOptions a mip::ProtectionOptions. Nejprve musíme převést ID štítku na štítek a poté definovat možnosti označování.

Převést ID štítku na mip::Label

Prvním parametrem funkce mip::Label je . Aplikace často pracuje s identifikátory popisků, nikoli s popisky. Identifikátor popisku lze převést na mip::Label voláním metody GetLabelById v modulu souborů nebo zásad:

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

Možnosti označování

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

LabelingOptions uvádí další informace o štítku, například AssignmentMethod a odůvodnění akce.

  • mip::AssignmentMethod je enumerátor, který má tři hodnoty: STANDARD, PRIVILEGEDnebo AUTO. Další informace najdete v referenci mip::AssignmentMethod.
  • 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.

Tato ukázka kódu demonstruje vytvoření objektu mip::LabelingOptions a nastavení odůvodnění snížení verze 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 mohou potřebovat provádět operace jménem delegované identity 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 jádra. To mělo značné nevýhody z hlediska režie aplikace a počtu komunikací se službami. 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");

Nastavte popisek

Po načtení mip::Label pomocí ID, nastavení možností popisku a případném nastavení ochrany lze nyní štítek nastavit v obslužné rutině.

Pokud jste nenastavili nastavení ochrany, nastavte popisek voláním SetLabel u 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 commitment se vrátíme k promise/future a vytvoříme promise 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í promise a future se zavolá CommitAsync() a jsou předány dva parametry: cesta k výstupnímu souboru (std::string) a Promise. 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é: Stávající FileHandler 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 k odebrání nebo přejmenování FileA.docx a přejmenování FileB.docx.

Odstranit štítek

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 vaší odpovědností provést tuto kontrolu přístupu. Nesprávné provedení kontroly přístupu může vést k ú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.");
    }
}
  • Last updated on