Microsoft Information Protection SDK - dosya işleyici kavramları

MIP Dosya SDK’sında, mip::FileHandler yerleşik olarak desteklenen dosya türlerinde etiketleri veya korumayı okuma ve yazma işlemlerini 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 makale aşağıdaki yöntemleri kapsar:

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

Gereksinimler

Belirli bir dosya ile çalışacak bir FileHandler oluşturmak için şunları sağlayın:

Dosya işleyicisi oluşturma

Dosya SDK'sında dosyaları yönetmenin 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 işlevleri içerir.

promise/future desenini kullanarak FileEngine öğesinin CreateFileHandlerAsync işlevini çağırarak FileHandler öğesini oluşturun.

CreateFileHandlerAsync, şu parametreleri kabul eder: okunacak veya değiştirilecek dosyanın yolu, denetim raporlaması için kullanılacak yol, denetim bulmayı etkinleştiren bir işaret, eşzamansız olay bildirimleri için mip::FileHandler::Observer ve FileHandler için Promise nesnesi.

Note

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

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

Nesneyi oluşturduktan FileHandler sonra dosya işlemleri (get/set/delete/commit) gerçekleştirebilirsiniz.

Etiketi okuma

Meta veri gereksinimleri

Bir dosyadan meta verileri başarıyla okumak ve uygulamaların kullanabileceği bir şeye çevirmek birkaç gereksinime sahiptir.

  • Okunan etiket Microsoft 365 hizmetinde hala mevcut olmalıdır. Birisi etiketi silerse, 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

GetLabel()

Belirli bir dosyaya işaret eden işleyiciyi oluşturduktan sonra, fileHandler->GetLabel() çağrısı yaparak etiketi eşzamanlı olarak okuyun. yöntemi, uygulanan etiket hakkındaki tüm bilgileri içeren bir mip::ContentLabel nesne döndürür.

auto label = fileHandler->GetLabel();

Nesneden label etiket verilerini okuyabilir ve uygulamadaki diğer bileşenlere veya işlevlere geçirebilirsiniz.

Etiket ayarlama

Etiket ayarlamak iki parçalı bir işlemdir. Söz konusu dosyaya işaret eden bir işleyici oluşturduktan sonra, bazı parametrelerle çağırarak FileHandler->SetLabel() etiketi ayarlayın: mip::Label, mip::LabelingOptionsve mip::ProtectionOptions. İlk olarak etiket kimliğini bir etikete çözümleyin ve ardından etiketleme seçeneklerini tanımlayın.

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. Dosya ya da ilke altyapısında mip::Label yöntemini çağırarak etiket tanımlayıcısını olarak çözümleyin:

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

Etiketleme seçenekleri

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

LabelingOptions, AssignmentMethod ve bir eylemin gerekçesi gibi etiket hakkında daha fazla bilgi 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.
  • Yalnızca hizmet ilkesi gerektiriyorsa ve bir dosyanın mevcut duyarlılık düzeyini düşürürken gerekçe belirtin.

Bu kod parçacığı, mip::LabelingOptions nesnesinin nasıl oluşturulacağını ve alt sürüme geçirme gerekçesi ile iletisinin nasıl ayarlanacağını 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şlem gerçekleştirmesi gerekebilir. sınıfı, mip::ProtectionSettings uygulamanın işleyici başına temsilci kimliği tanımlamasına olanak tanır. Daha önce yetki devrini motor sınıfları gerçekleştiriyordu. Bu tasarımın uygulama ek yükü ve servis gidiş dönüşlerinde önemli dezavantajları vardı. Temsilci kullanıcı ayarlarının öğesine mip::ProtectionSettings taşınması ve işleyici sınıfının bir parçası haline getirilmesi bu ek yükü ortadan kaldırır ve bu da çeşitli kullanıcı kimlikleri kümeleri adına birçok işlem gerçekleştiren uygulamalar için performansı artırır.

Temsilciye ihtiyacınız yoksa SetLabel işlevine geçinmip::ProtectionSettings(). Temsilciye ihtiyacınız varsa bir mip::ProtectionSettings nesne oluşturun ve temsilci olarak atanan posta adresini ayarlayın:

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

Etiketi ayarlama

Kimliği kullanarak mip::Label öğesini aldıktan, etiketleme seçeneklerini ayarladıktan ve isteğe bağlı olarak koruma ayarlarını yapılandırdıktan sonra etiketi işleyici üzerinde ayarlayabilirsiniz.

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 şunu kullanın:

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

İşleyicinin başvuracağı dosyada etiketi ayarladıktan sonra, değişikliği işleyin ve diske bir dosya yazın veya bir çıkış akışı oluşturun.

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. FileHandler->CommitAsync() işlevini kullanın.

Taahhüt fonksiyonunu uygulamak için promise/future konusuna geri dönün ve bir bool için bir promise oluşturun. İşlev, CommitAsync() işlem başarılı olursa true veya herhangi bir nedenle başarısız olursa false döndürür.

promise ve CommitAsync() oluşturduktan sonra, std::string çağrısını yapın ve iki parametre sağlayın: çıkış dosyası yolu (future) ve promise nesnesi. Son olarak, future nesnesinin değerini alarak sonucu elde edin.

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. Etiketlediğiniz dosya için değiştirme uygulamanız gerekir.

FileA.docxbir etiket yazarsanız, CommitAsync() etiketin uygulandığı FileB.docxdosyasının bir kopyasını oluşturur. FileA.docx dosyasını kaldırmak veya yeniden adlandırmak ve FileB.docx dosyasını yeniden adlandırmak için kod yazın.

Etiket silme

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

Korumayı kaldırma

Kullanıcının erişilen dosyadan korumayı kaldırma haklarına sahip olduğunu doğrulayın. Korumayı kaldırmadan önce erişim denetimi gerçekleştirin.

RemoveProtection() işlevi veya DeleteLabel()işlevine SetLabel() benzer şekilde davranır. Mevcut FileHandler nesnede yöntemini çağırın ve değişikliği işleyin.

Önemli

Uygulama geliştiricisi olarak bu erişim denetimini gerçekleştirmek sizin sorumluluğunuzdadır. Erişim denetiminin düzgün gerçekleştirilememesi veri sızıntısına neden olabilir.

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

Sonraki Adımlar

  • Last updated on