Bagikan melalui

Microsoft Information Protection SDK - Konsep handler file

  • Artikel

Dalam SDK File MIP, mip::FileHandler mengekspos semua berbagai operasi yang dapat digunakan untuk membaca dan menulis label, atau perlindungan, di seluruh set jenis file yang dukungannya bawaan.

Jenis file yang didukung

  • Format File Office berdasarkan OPC (Office 2010 dan yang lebih baru)
  • Format File Office Warisan (Office 2007)
  • PDF
  • Dukungan PFILE generik
  • File yang mendukung Adobe XMP

Fungsi handler file

mip::FileHandler mengekspos metode untuk membaca, menulis, dan menghapus label dan informasi perlindungan. Untuk daftar lengkapnya, lihat referensi API.

Dalam artikel ini, metode berikut akan dibahas:

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

Persyaratan

FileHandler Membuat untuk bekerja dengan file tertentu memerlukan:

  • FileProfile
  • Ditambahkan FileEngine ke FileProfile
  • Kelas yang mewarisi mip::FileHandler::Observer

Membuat handler file

Langkah pertama yang diperlukan dalam mengelola file apa pun di File SDK adalah membuat FileHandler objek. Kelas ini mengimplementasikan semua fungsionalitas yang diperlukan untuk mendapatkan, mengatur, memperbarui, menghapus, dan menerapkan perubahan label pada file.

FileHandler Membuat semahal memanggil FileEnginefungsi menggunakan CreateFileHandlerAsync pola promise/future.

CreateFileHandlerAsync menerima tiga parameter: Jalur ke file yang harus dibaca atau dimodifikasi, mip::FileHandler::Observer untuk pemberitahuan peristiwa asinkron, dan janji untuk FileHandler.

Catatan: Kelas mip::FileHandler::Observer harus diimplementasikan di kelas turunan Observer karena CreateFileHandler memerlukan objek .

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

Setelah berhasil membuat FileHandler objek, operasi file (get/set/delete/commit) dapat dilakukan.

Membaca label

Persyaratan metadata

Ada beberapa persyaratan untuk berhasil membaca metadata dari file dan menerjemahkan ke sesuatu yang dapat digunakan dalam aplikasi.

  • Label yang sedang dibaca masih harus ada di layanan Microsoft 365. Jika telah dihapus sepenuhnya, SDK akan gagal mendapatkan informasi tentang label tersebut dan akan mengembalikan kesalahan.
  • Metadata file harus utuh. Metadata ini mencakup:
    • Atribut1
    • Atribut2

GetLabelAsync()

Setelah membuat handler untuk menunjuk ke file tertentu, kami kembali ke pola promise/future untuk membaca label secara asinkron. Janji adalah untuk mip::ContentLabel objek yang berisi semua informasi tentang label yang diterapkan.

Setelah membuat promise instans objek dan future , kita membaca label dengan memanggil fileHandler->GetLabelAsync() dan menyediakan promise sebagai parameter lone. Akhirnya, label dapat disimpan dalam mip::ContentLabel objek yang akan kita dapatkan dari 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 label dapat dibaca dari label objek dan diteruskan ke komponen atau fungsionalitas lain dalam aplikasi.

Mengatur label

Mengatur label adalah proses dua bagian. Pertama, setelah membuat handler yang menunjuk ke file yang dimaksud, label dapat diatur dengan memanggil FileHandler->SetLabel() dengan beberapa parameter: mip::Label, , mip::LabelingOptionsdan mip::ProtectionOptions. Pertama, kita harus menyelesaikan ID label ke label lalu menentukan opsi pelabelan.

Mengatasi ID label untuk mip::Label

Parameter pertama fungsi SetLabel adalah mip::Label. Seringkali, aplikasi bekerja dengan pengidentifikasi label daripada label. Pengidentifikasi label dapat diselesaikan dengan mip::Label memanggil GetLabelById pada file atau mesin kebijakan:

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

Opsi pelabelan

Parameter kedua yang diperlukan untuk mengatur label adalah mip::LabelingOptions.

LabelingOptions menentukan informasi tambahan tentang label seperti dan pembenaran AssignmentMethod untuk tindakan.

  • mip::AssignmentMethod adalah enumerator yang memiliki tiga nilai: STANDARD, , PRIVILEGEDatau AUTO. mip::AssignmentMethod Tinjau referensi untuk detail selengkapnya.
  • Pembenaran diperlukan hanya jika kebijakan layanan memerlukannya dan saat menurunkan sensitivitas file yang ada .

Cuplikan ini menunjukkan pembuatan mip::LabelingOptions objek dan mengatur pembenaran dan pesan penurunan tingkat.

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

Pengaturan perlindungan

Beberapa aplikasi mungkin perlu melakukan operasi atas nama identitas pengguna yang didelegasikan. Kelas mip::ProtectionSettings memungkinkan aplikasi untuk menentukan identitas yang didelegasikan per handler. Sebelumnya, delegasi dilakukan oleh kelas mesin. Ini memiliki kerugian yang signifikan dalam overhead aplikasi dan layanan pulang pergi. Dengan memindahkan pengaturan pengguna yang didelegasikan ke mip::ProtectionSettings dan menjadikannya bagian dari kelas handler, kami menghilangkan overhead ini, menghasilkan performa yang lebih baik untuk aplikasi yang melakukan banyak operasi atas nama berbagai set identitas pengguna.

Jika delegasi tidak diperlukan, teruskan mip::ProtectionSettings()ke fungsi SetLabel . Jika delegasi diperlukan, delegasi dapat dicapai dengan membuat mip::ProtectionSettings objek dan mengatur alamat email yang didelegasikan:

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

Mengatur label

Setelah mengambil mip::Label menggunakan ID, atur opsi pelabelan, dan, secara opsional, atur pengaturan perlindungan, label sekarang dapat diatur pada handler.

Jika Anda tidak mengatur pengaturan perlindungan, atur label dengan memanggil SetLabel pada handler:

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

Jika Anda memerlukan pengaturan perlindungan untuk melakukan operasi yang didelegasikan, maka:

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

Setelah sekarang mengatur label pada file yang dirujuk oleh handler, masih ada satu langkah lagi untuk melakukan perubahan dan menulis file ke disk atau membuat aliran output.

Menerapkan perubahan

Langkah terakhir dalam melakukan perubahan apa pun pada file di MIP SDK adalah menerapkan perubahan. Ini dicapai dengan menggunakan FileHandler->CommitAsync() fungsi .

Untuk menerapkan fungsi komitmen, kami kembali ke janji/masa depan, menciptakan janji untuk .bool Fungsi CommitAsync() akan mengembalikan true jika operasi berhasil atau salah jika gagal karena alasan apa pun.

Setelah membuat promise dan future, CommitAsync() dipanggil dan dua parameter disediakan: Jalur file output (std::string), dan janji. Terakhir, hasilnya diperoleh dengan mendapatkan nilai future objek.

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

Penting:FileHandler Tidak akan memperbarui atau menimpa file yang ada. Terserah pengembang untuk menerapkan mengganti file yang sedang diberi label.

Jika menulis label ke FileA.docx, salinan file, FileB.docx, akan dibuat dengan label yang diterapkan. Kode harus ditulis untuk menghapus/mengganti nama FileA.docx dan mengganti nama FileB.docx.

Menghapus label

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

Hapus proteksi

Aplikasi MIP File SDK Anda harus memvalidasi bahwa pengguna memiliki hak untuk menghapus perlindungan dari file yang diakses. Ini dapat dicapai dengan melakukan pemeriksaan akses sebelum menghapus perlindungan.

Fungsi ini RemoveProtection() berulah dengan cara yang mirip SetLabel() dengan atau DeleteLabel(). Metode ini dipanggil pada objek yang ada FileHandler , maka perubahan harus dilakukan.

Penting

Sebagai pengembang aplikasi, anda bertanggung jawab untuk melakukan pemeriksaan akses ini. Kegagalan untuk melakukan pemeriksaan akses dengan benar dapat digunakan kembali dalam kebocoran data.

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

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