Microsoft Information Protection SDK - Dosya işleyici kavramları

  • Makale

MIP Dosya SDK'sında, mip::FileHandler desteğin yerleşik olduğu bir dizi dosya türünde etiketleri veya korumayı okumak ve yazmak için kullanılabilecek çeşitli işlemlerin tümünü kullanıma sunar.

Desteklenen dosya türleri

  • OPC'ye Dayalı Office Dosya Biçimleri (Office 2010 ve üzeri)
  • Eski Office Dosya Biçimleri (Office 2007)
  • PDF
  • Genel PFILE desteği
  • Adobe XMP'i destekleyen dosyalar

Dosya işleyici işlevleri

mip::FileHandler hem etiketleri hem de koruma bilgilerini okuma, yazma ve kaldırma yöntemlerini kullanıma sunar. Tam liste için API başvurusuna başvurun.

Bu makalede aşağıdaki yöntemler ele alınacaktır:

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

Gereksinimler

Belirli bir FileHandler dosyayla çalışmak için oluşturmak için şunlar gerekir:

  • FileProfile
  • öğesine FileEngine eklendi FileProfile
  • Devralan bir sınıf mip::FileHandler::Observer

Dosya işleyicisi oluşturma

Dosya SDK'sı içindeki tüm dosyaları yönetmek için gereken ilk adım bir FileHandler nesne oluşturmaktır. Bu sınıf, dosyalarda etiket değişikliklerini almak, ayarlamak, güncelleştirmek, silmek ve işlemek için gereken tüm işlevleri uygular.

oluşturmak FileHandler , promise/future desenini FileEnginekullanarak 's CreateFileHandlerAsync işlevini çağırmak kadar kolaydır.

CreateFileHandlerAsync üç parametre kabul eder: Okunması veya değiştirilmesi gereken dosyanın yolu, mip::FileHandler::Observer zaman uyumsuz olay bildirimleri için ve için FileHandlersöz.

Not: mip::FileHandler::Observer sınıfı, nesnesini gerektirdiğinden CreateFileHandler Observer türetilmiş bir sınıfta uygulanmalıdır.

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();

Nesne başarıyla oluşturulduktan FileHandler sonra dosya işlemleri (get/set/delete/commit) gerçekleştirilebilir.

Etiketi okuma

Meta veri gereksinimleri

Bir dosyadan meta verileri başarıyla okumak ve uygulamasında kullanılabilecek bir şeye çevirmek için birkaç gereksinim vardır.

  • Okunan etiket Microsoft 365 hizmetinde hala mevcut olmalıdır. Tamamen silinmişse, SDK bu etiket hakkında bilgi edinemez ve bir hata döndürür.
  • Dosya meta verilerinin bozulmamış olması gerekir. Bu meta veriler şunları içerir:
    • Öznitelik1
    • Öznitelik2

GetLabelAsync()

Belirli bir dosyaya işaret eden işleyiciyi oluşturduktan sonra, etiketi zaman uyumsuz olarak okumak için promise/future desenine geri döneriz. Söz, uygulanan etiketle ilgili tüm bilgileri içeren bir mip::ContentLabel nesne içindir.

ve future nesnelerinin örneğini promise aldıktan sonra, öğesini çağırarak fileHandler->GetLabelAsync() ve tek parametre olarak sağlayarak promise etiketi okuruz. Son olarak etiket, öğesinden alacağımız bir mip::ContentLabel nesnede futuredepolanabilir.

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

Etiket verileri nesneden okunabilir ve uygulamadaki label diğer bileşenlere veya işlevlere geçirilebilir.

Etiket ayarlama

Etiket ayarlamak iki parçalı bir işlemdir. İlk olarak, söz konusu dosyaya işaret eden bir işleyici oluşturduktan sonra, etiket bazı parametrelerle çağrılarak FileHandler->SetLabel() ayarlanabilir: mip::Label, mip::LabelingOptionsve mip::ProtectionOptions. İlk olarak, etiket kimliğini bir etiket olarak çözümlemeli ve ardından etiketleme seçeneklerini tanımlamalıyız.

Etiket kimliğini mip::Label olarak çözümleme

SetLabel işlevinin ilk parametresi bir mip::Labelparametresidir. Uygulama genellikle etiketler yerine etiket tanımlayıcılarıyla çalışır. Etiket tanımlayıcısı, dosya veya ilke altyapısında mip::Label GetLabelById çağrılarak çözümlenebilir:

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

Etiketleme seçenekleri

Etiketi ayarlamak için gereken ikinci parametre: mip::LabelingOptions.

LabelingOptions bir eylemin ve gerekçesi gibi AssignmentMethod etiket hakkında ek bilgiler belirtir.

  • mip::AssignmentMethod üç değeri olan bir numaralandırıcıdır: STANDARD, PRIVILEGEDveya AUTO. Daha fazla ayrıntı için başvuruyu mip::AssignmentMethod gözden geçirin.
  • Gerekçelendirme yalnızca hizmet ilkesi gerektiriyorsa ve dosyanın mevcut duyarlılığını düşürürken gereklidir.

Bu ekran alıntısı, nesnenin oluşturulmasını mip::LabelingOptions ve eski sürüme düşürme gerekçesini ve iletisini ayarlamayı gösterir.

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

Koruma ayarları

Bazı uygulamaların temsilci kullanıcı kimliği adına işlemler gerçekleştirmesi gerekebilir. sınıfı, mip::ProtectionSettings uygulamanın işleyici başına temsilci kimliği tanımlamasına izin verir. Daha önce, temsilci seçme, altyapı sınıfları tarafından gerçekleştirildi. Bunun uygulama ek yükü ve servis gidiş dönüşlerinde önemli dezavantajları vardı. Temsilci kullanıcı ayarlarını öğesine mip::ProtectionSettings taşıyarak ve işleyici sınıfının bu bölümünü oluşturarak bu ek yükü ortadan kaldırarak farklı kullanıcı kimlikleri kümeleri adına birçok işlem gerçekleştiren uygulamalar için daha iyi performans elde ederiz.

Temsilci seçme gerekli değilse SetLabel işlevine geçinmip::ProtectionSettings(). Temsilci seçimi gerekiyorsa, bir mip::ProtectionSettings nesne oluşturulup temsilci olarak atanan posta adresi ayarlanarak gerçekleştirilebilir:

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

Etiketi ayarlama

kimliği kullanılarak getirildiğinde mip::Label , etiketleme seçeneklerini ayarlayın ve isteğe bağlı olarak koruma ayarlarını yapın; etiket artık işleyicide ayarlanabilir.

Koruma ayarlarını ayarlamadıysanız, işleyicide çağırarak SetLabel etiketi ayarlayın:

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

Temsilcili bir işlem gerçekleştirmek için koruma ayarlarına ihtiyacınız varsa:

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

İşleyicinin başvurmuş olduğu dosyada etiketi ayarladıktan sonra, değişikliği kaydetmek ve diske dosya yazmak veya çıkış akışı oluşturmak için bir adım daha vardır.

Değişiklikleri gönderme

MIP SDK'sında bir dosyada herhangi bir değişiklik yürütmenin son adımı, değişikliği işlemektir. Bu, işlevi kullanılarak FileHandler->CommitAsync() gerçekleştirilir.

Taahhüt işlevini uygulamak için promise/future işlevine geri döner ve bir booliçin bir söz oluştururuz. İşlem CommitAsync() başarılı olursa işlev true veya herhangi bir nedenle başarısız olursa false döndürür.

ve CommitAsync() futureoluşturulduktan promise sonra çağrılır ve iki parametre sağlanır: Çıkış dosyası yolu ()std::string ve promise. Son olarak, sonuç nesnenin future değeri alınarak elde edilir.

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

Önemli: FileHandler , mevcut dosyaları güncelleştirmez veya üzerine yazamaz. Etiketlenen dosyanın değiştirilmesi geliştiriciye bağlı.

FileA.docx bir etiket yazıyorsanız, etiket uygulanmış FileB.docx dosyanın bir kopyası oluşturulur. FileA.docx kaldırmak/yeniden adlandırmak ve FileB.docx yeniden adlandırmak için kod yazılmalıdır.

Etiket silme

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

Korumayı kaldırma

MIP Dosya SDK'sı uygulamanız, kullanıcının erişilen dosyadan korumayı kaldırma haklarına sahip olduğunu doğrulamalıdır. Bu, koruma kaldırılmadan önce bir erişim denetimi gerçekleştirilerek gerçekleştirilebilir.

RemoveProtection() işlevi veya DeleteLabel()gibi SetLabel() davranır. yöntemi mevcut FileHandler nesnede çağrılır, ardından değişikliğin işlenmesi gerekir.

Önemli

Uygulama geliştiricisi olarak, bu erişim denetimini gerçekleştirmek sizin yeniden sorumluluklarınızdır. Erişim denetiminin düzgün şekilde gerçekleştirilememesi, veri sızıntısında yeniden kullanılabilir.

C++ örneği:

// 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.");
    }
}

.NET örneği:

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.");
    }
}