Bagikan melalui

Microsoft Information Protection SDK - Konsep Pengelolaan File

Dalam SDK File MIP, mip::FileHandler menawarkan berbagai operasi yang dapat digunakan untuk membaca dan menulis label serta perlindungan pada sejumlah jenis file dengan dukungan bawaan.

Jenis file yang didukung

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

Fungsi pengelola berkas

mip::FileHandler menawarkan metode untuk membaca, menulis, dan menghapus baik label maupun informasi perlindungan. Untuk daftar lengkapnya, kunjungi referensi API.

Dalam artikel ini, metode berikut akan dibahas:

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

Persyaratan

Membuat FileHandler untuk bekerja dengan file tertentu memerlukan:

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

Membuat file handler

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.

Membuat FileHandler semudah memanggil fungsi CreateFileHandlerAsync dari FileEngine menggunakan 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 CreateFileHandler karena Observer 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.

Bacalah 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 tersebut adalah kepada mip::ContentLabel objek yang berisi semua informasi tentang label yang diterapkan.

Setelah membuat objek promise dan future, kita membaca label dengan memanggil fileHandler->GetLabelAsync() dan menyediakan promise sebagai satu-satunya parameter. Akhirnya, label dapat disimpan dalam objek mip::ContentLabel 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.

Menetapkan label

Mengatur label adalah proses yang terdiri dari 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 mengonversi ID label menjadi label dan kemudian menetapkan opsi pelabelan.

Menentukan ID label menjadi mip::Label

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

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

Pilihan pelabelan

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

LabelingOptions menentukan informasi tambahan tentang label seperti AssignmentMethod dan pembenaran 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 objek mip::LabelingOptions dan mengatur alasan 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, maka 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");

Atur label

Setelah mip::Label diambil menggunakan ID, atur opsi pelabelan, dan, jika diinginkan, atur pengaturan perlindungan. Setelah itu, label 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 mengkomit perubahan. Ini dicapai dengan menggunakan FileHandler->CommitAsync() fungsi .

Untuk menerapkan fungsi komitmen, kami kembali ke konsep promise/future, menciptakan sebuah 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: Fitur tersebut 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 RemoveProtection() berperilaku dengan cara yang mirip dengan SetLabel() 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 mengakibatkan 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.");
    }
}
  • Last updated on