Aracılığıyla paylaş

Microsoft Information Protection SDK - Dosya işleyici kavramları

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 referansına bakın.

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 şunlar gerekir:

  • FileProfile
  • FileEngine FileProfile öğesine eklendi
  • 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, zaman uyumsuz olay bildirimleri için mip::FileHandler::Observer, ve FileHandler için söz.

Not:mip::FileHandler::Observer sınıfı, nesnesini gerektirdiğinden CreateFileHandlerObserver 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. Verilen söz, uygulanan etiketle ilgili tüm bilgileri içeren bir mip::ContentLabel nesneyi kapsar.

promise ve future nesnelerinin örneklerini aldıktan sonra, fileHandler->GetLabelAsync() öğesini çağırıp, promise'ü tek parametre olarak sağlayarak etiketi okuruz. Son olarak etiket, future'den alacağımız bir mip::ContentLabel nesnesinde depolanabilir.

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 GetLabelById çağrısı yapılmasıyla mip::Label olarak çö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 bir 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 SetLabelmip::ProtectionSettings()geçin. 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

Kimlik kullanılarak mip::Label alındıktan sonra, etiketleme seçeneklerini ayarlayın ve isteğe bağlı olarak koruma ayarlarını yapın, ardından etiket işleyiciye 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şlev FileHandler->CommitAsync() kullanılarak 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.

promise ve future oluşturulduktan sonra CommitAsync() ç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ştirilmesinin uygulanması geliştiricinin sorumluluğundadır.

FileA.docx dosyasına bir etiket yazdığınızda, etiket uygulanmış halini içeren bir kopya FileB.docx olarak oluşturulacaktır. 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, SetLabel() veya DeleteLabel() gibi 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.");
    }
}
  • Last updated on