Microsoft Information Protection SDK - konsep penanganan file

Dalam MIP File SDK, mip::FileHandler menyediakan operasi untuk membaca dan menulis label atau perlindungan pada berbagai jenis file yang didukung secara 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 pengelola berkas

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

Artikel ini membahas metode berikut:

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

Persyaratan

Untuk membuat FileHandler untuk bekerja dengan file tertentu, berikan:

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

Membuat file handler

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

Buat FileHandler dengan memanggil fungsi CreateFileHandlerAsync milik FileEngine menggunakan pola promise/future.

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

Note

Implementasikan kelas mip::FileHandler::Observer dalam kelas turunan karena Observer memerlukan objek CreateFileHandler.

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 membuat FileHandler objek, Anda dapat melakukan operasi file (get/set/delete/commit).

Bacalah label

Persyaratan metadata

Berhasil membaca metadata dari file dan menerjemahkannya ke dalam sesuatu yang dapat digunakan aplikasi memiliki beberapa persyaratan.

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

GetLabelAsync()

Setelah Anda membuat handler yang menunjuk ke file tertentu, 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 Anda membuat instans objek promise dan future, baca label dengan memanggil fileHandler->GetLabelAsync() dan memberikan promise sebagai satu-satunya parameter. Terakhir, simpan label dalam objek yang mip::ContentLabel Anda 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();

Anda dapat membaca data label dari label objek dan meneruskannya ke komponen atau fungsionalitas lain dalam aplikasi.

---

Menetapkan label

Menetapkan label adalah proses dua tahap. Setelah Anda membuat handler yang menunjuk ke file yang dimaksud, atur label dengan memanggil FileHandler->SetLabel() dengan beberapa parameter: mip::Label, mip::LabelingOptions, dan mip::ProtectionOptions. Pertama, tentukan terlebih dahulu label dari ID label, lalu tentukan opsi pelabelan.

Menentukan ID label menjadi mip::Label

Parameter pertama fungsi SetLabel adalah mip::Label. Sering kali, aplikasi menggunakan pengidentifikasi label daripada label. Temukan pengidentifikasi label ke mip::Label dengan memanggil GetLabelById pada mesin file atau kebijakan:

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

Pilihan pelabelan

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

LabelingOptions menentukan informasi lebih lanjut tentang label, seperti AssignmentMethod dan justifikasi untuk suatu tindakan.

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

Cuplikan ini menunjukkan cara membuat objek mip::LabelingOptions dan menetapkan alasan serta pesan downgrade.

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 menentukan identitas yang didelegasikan per handler. Sebelumnya, kelas-kelas engine melakukan pendelegasian. Desain itu memiliki kelemahan yang signifikan dalam overhead aplikasi dan layanan pulang pergi. Memindahkan pengaturan pengguna yang didelegasikan ke mip::ProtectionSettings dan menjadikannya bagian dari kelas handler menghilangkan overhead ini, yang meningkatkan performa untuk aplikasi yang melakukan banyak operasi atas nama berbagai set identitas pengguna.

Jika Anda tidak memerlukan delegasi, teruskan mip::ProtectionSettings() ke fungsi SetLabel . Jika Anda memerlukan delegasi, buat mip::ProtectionSettings objek dan atur alamat email yang didelegasikan:

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

Atur label

Setelah Anda mengambil mip::Label dengan menggunakan ID, atur opsi pelabelan, dan secara opsional mengatur pengaturan perlindungan, Anda dapat mengatur label 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, gunakan:

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

Setelah Anda mengatur label pada file yang dirujuk oleh handler, terapkan perubahan dan tulis file ke disk atau buat aliran output.

Menerapkan perubahan

Langkah terakhir dalam melakukan perubahan apa pun pada file di MIP SDK adalah mengkomit perubahan. Gunakan fungsi FileHandler->CommitAsync().

Untuk mengimplementasikan fungsi commit, kembali ke promise/future, dengan membuat promise untuk bool. Fungsi CommitAsync() mengembalikan true jika operasi berhasil atau salah jika gagal karena alasan apa pun.

Setelah Anda membuat promise dan CommitAsync(), panggil std::string dan berikan dua parameter: jalur file output (future) dan promise. Terakhir, dapatkan hasilnya 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. Anda harus menerapkan penggantian untuk file yang Anda beri label.

Jika Anda menulis label ke FileA.docx, CommitAsync() membuat salinan file, FileB.docx, dengan label diterapkan. Tulis kode untuk menghapus atau 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

Validasi bahwa pengguna memiliki hak untuk menghapus perlindungan dari file yang diakses. Lakukan pemeriksaan akses sebelum menghapus perlindungan.

Fungsi RemoveProtection() berperilaku serupa dengan SetLabel() atau DeleteLabel(). Panggil metode pada objek yang ada FileHandler , lalu terapkan perubahan.

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

Langkah berikutnya

• Jelajahi sampel MIP File SDK C++ di GitHub.