Microsoft Information Protection SDK – koncepty obsluhy souborů

V sadě MIP File SDK mip::FileHandler zpřístupňuje operace pro čtení a zápis štítků nebo ochrany u typů souborů s integrovanou podporou.

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.

Tento článek popisuje následující metody:

• GetLabel()
• SetLabel()
• DeleteLabel()
• RemoveProtection()
• CommitAsync()

Požadavky

Pokud chcete vytvořit soubor FileHandler pro práci s konkrétním souborem, zadejte:

• 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ě souborů v sadě File SDK je vytvoření objektu FileHandler . Tato třída obsahuje funkce potřebné k získání, nastavení, aktualizaci, odstranění a potvrzení změn popisků do souborů.

Vytvořte FileHandler voláním funkce CreateFileHandlerAsync objektu FileEngine pomocí vzoru promise/future.

CreateFileHandlerAsync přijímá následující parametry: cestu k souboru, který se má číst nebo upravit, cestu používanou pro vykazování auditu, příznak, který povoluje detekci auditu, mip::FileHandler::Observer pro asynchronní oznámení událostí a promise pro FileHandler.

Note

Implementujte třídu mip::FileHandler::Observer v odvozené třídě, protože CreateFileHandler vyžaduje objekt Observer.

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

Po vytvoření objektu FileHandler můžete provádět operace se soubory (get/set/delete/commit).

Přečtěte štítek

Požadavky na metadata

Úspěšné čtení metadat ze souboru a jeho překlad do něčeho, co můžou aplikace používat, má několik požadavků.

• Štítek, který se načítá, musí ve službě Microsoft 365 stále existovat. Pokud někdo štítek odstranil, sadě SDK se nepodaří získat informace o tomto štítku a vrátí chybu.
• Metadata souboru musí být nedotčena. Tato metadata zahrnují:
  • Attribute1
  • Attribute2

GetLabel()

Po vytvoření obslužné rutiny, která odkazuje na určitý soubor, načtěte popisek synchronně voláním fileHandler->GetLabel(). Metoda vrátí mip::ContentLabel objekt, který obsahuje všechny informace o použitém popisku.

auto label = fileHandler->GetLabel();

Můžete číst data popisků z objektu label a předat je jakékoli jiné komponentě nebo funkcím v aplikaci.

---

Nastavení popisku

Nastavení popisku je proces se dvěma částmi. Poté, co vytvoříte obslužnou rutinu, která odkazuje na daný soubor, nastavte popisek voláním FileHandler->SetLabel() s několika parametry: mip::Label, mip::LabelingOptions a mip::ProtectionOptions. Nejprve převeďte ID štítku na štítek a poté definujte možnosti štítků.

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. Převeďte identifikátor popisku na mip::Label voláním GetLabelById v modulu pro soubory nebo modulu zásad:

std::shared_ptr<mip::Label> label = engine->GetLabelById(labelId);

Možnosti označování

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

LabelingOptions upřesňuje 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.
• Uveďte odůvodnění pouze v případě, že je zásada služby vyžaduje a když snížíte stávající citlivost souboru.

Tento fragment kódu ukazuje, jak vytvořit mip::LabelingOptions objekt a nastavit odůvodnění a zprávu downgrade.

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ého uživatele identity. Třída mip::ProtectionSettings umožňuje aplikaci definovat delegovanou identitu pro každou obslužnou rutinu. Dříve delegování zajišťovaly třídy enginu. Tento návrh měl značné nevýhody z hlediska aplikační režie a počtu komunikací se službou. Přesunutí delegovaných uživatelských nastavení do mip::ProtectionSettings třídy obslužné rutiny eliminuje tuto režii, což zlepšuje výkon aplikací, které provádějí mnoho operací jménem různorodých sad identit uživatelů.

Pokud nepotřebujete delegování, předejte funkci SetLabel hodnotu mip::ProtectionSettings(). Pokud potřebujete delegování, vytvořte mip::ProtectionSettings objekt a nastavte delegovanou poštovní adresu:

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 můžete v obslužné rutině nastavit popisek.

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

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

Pokud potřebujete nastavení ochrany k provedení delegovaných operací, použijte:

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

Po nastavení popisku v souboru, na který obslužná rutina odkazuje, potvrďte změnu a zapište soubor na disk nebo vytvořte výstupní datový proud.

Potvrzení změn

Posledním krokem při potvrzení jakékoli změny souboru v sadě MIP SDK je potvrzení změny. Použijte funkci FileHandler->CommitAsync().

Chcete-li implementovat funkci commitment, vraťte se k promise/future a vytvořte 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 CommitAsync() zavolejte future a zadejte dva parametry: cestu k výstupnímu souboru (std::string) a Promise. Nakonec získejte výsledek 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íší. Musíte implementovat nahrazení souboru, který označujete.

Pokud napíšete popisek do FileA.docx, CommitAsync() vytvoří kopii souboru FileB.docxs použitým popiskem. Napište kód pro odebrání nebo přejmenování FileA.docx a přejmenování FileB.docx.

---

Odstranit štítek

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

mip::LabelingOptions labelingOptions(mip::AssignmentMethod::PRIVILEGED);
labelingOptions.SetDowngradeJustification(true, "Label unnecessary.");
fileHandler->DeleteLabel(labelingOptions);

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

Odebrání ochrany

Ověřte, že uživatel má práva k odebrání ochrany ze souboru, ke kterému se přistupuje. Před odebráním ochrany proveďte kontrolu přístupu .

Funkce RemoveProtection() se chová podobně jako SetLabel() nebo DeleteLabel(). Zavolejte metodu u existujícího FileHandler objektu a potvrďte změnu.

Důležité

Jako vývojář aplikace je vaší zodpovědností provést tuto kontrolu přístupu. Selháním správné kontroly přístupu může dojít 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.");
    }
}

Další kroky

• Prozkoumejte ukázku sady MIP File SDK C++ na GitHub.