快速入门：设置和获取敏感度标签 (C++)

项目
01/30/2024

本快速入门介绍如何使用更多 MIP 文件 SDK。通过上一个快速入门中列出的其中一个敏感度标签，可以使用文件处理程序来设置/获取文件上的标签。文件处理程序类公开用于为支持的文件类型设置/获取标签或保护的各种操作。

先决条件

如果尚未完成，请确保先完成以下先决条件，然后再继续：

首先完成快速入门：列出敏感度标签 (C++)，构建一个入门级 Visual Studio 解决方案，以列出组织的敏感度标签。此“设置和获取敏感度标签”快速入门建立在上一个快速入门的基础之上。
可选：查看 MIP SDK 中的文件处理程序概念。

实现观察程序类来监视文件处理程序对象

与在“应用程序初始化”快速入门中实现的观察程序（针对文件配置文件和引擎）类似，现在为文件处理程序对象实现观察程序类。

通过扩展 SDK 的 mip::FileHandler::Observer 类，为文件处理程序观察程序创建基本实现。观察程序被实例化并稍后使用，以监视文件处理程序操作。

打开在前文“快速入门：列出敏感度标签 (C++)”中使用的 Visual Studio 解决方案。
将新类添加到项目，这将会生成 header/.h 和 implementation/.cpp 文件：
- 在“解决方案资源管理器”中，再次右键单击项目节点，选择“添加”，然后选择“类”。
- 在“添加类”对话框中：
  - 在“类名”字段中，输入“filehandler_observer”。请注意，系统会根据输入的名称自动填充“.h 文件”和“.cpp 文件”字段。
  - 完成后，单击“确定”按钮。

为类生成 .h 文件和 .cpp 文件后，这两个文件都会在编辑器组选项卡中打开。现在更新每个文件，实现新的观察程序类：

通过选择/删除生成的 filehandler_observer 类来更新“filehandler_observer.h”。不要删除上一步生成的预处理器指令（#pragma、#include）。然后，将以下源复制/粘贴到文件中的任何现有预处理器指令之后：

#include <memory>
#include "mip/file/file_engine.h"
#include "mip/file/file_handler.h"

class FileHandlerObserver final : public mip::FileHandler::Observer {
public:
   FileHandlerObserver() { }
   // Observer implementation
   void OnCreateFileHandlerSuccess(const std::shared_ptr<mip::FileHandler>& fileHandler, const std::shared_ptr<void>& context) override;
   void OnCreateFileHandlerFailure(const std::exception_ptr& error, const std::shared_ptr<void>& context) override;
   void OnCommitSuccess(bool committed, const std::shared_ptr<void>& context) override;
   void OnCommitFailure(const std::exception_ptr& error, const std::shared_ptr<void>& context) override;		
};

通过选择/删除生成的 filehandler_observer 类实现来更新“filehandler_observer.cpp”。不要删除上一步生成的预处理器指令（#pragma、#include）。然后，将以下源复制/粘贴到文件中的任何现有预处理器指令之后：

void FileHandlerObserver::OnCreateFileHandlerSuccess(const std::shared_ptr<mip::FileHandler>& fileHandler, const std::shared_ptr<void>& context) {
   auto promise = std::static_pointer_cast<std::promise<std::shared_ptr<mip::FileHandler>>>(context);
   promise->set_value(fileHandler);
}

void FileHandlerObserver::OnCreateFileHandlerFailure(const std::exception_ptr & error, const std::shared_ptr<void>& context) {
   auto promise = std::static_pointer_cast<std::promise<std::shared_ptr<mip::FileHandler>>>(context);
   promise->set_exception(error);
}

void FileHandlerObserver::OnCommitSuccess(bool committed, const std::shared_ptr<void>& context) {
   auto promise = std::static_pointer_cast<std::promise<bool>>(context);
   promise->set_value(committed);
}

void FileHandlerObserver::OnCommitFailure(const std::exception_ptr & error, const std::shared_ptr<void>& context) {
   auto promise = std::static_pointer_cast<std::promise<bool>>(context);
   promise->set_exception(error);
}

（可选）使用 F6（生成解决方案）运行解决方案的测试编译/链接，以确保在继续之前成功完成生成。

添加逻辑以设置和获取敏感度标签

使用文件引擎对象添加逻辑以设置和获取文件的敏感度标签。

使用“解决方案资源管理器”，打开项目中包含 main() 方法实现的 .cpp 文件。该文件默认与包含它的项目同名，该名称在项目创建期间指定。

在该文件顶部将以下 #include 和 using 指令添加到相应的现有指令之下：

#include "filehandler_observer.h" 
#include "mip/file/file_handler.h" 

using mip::FileHandler;

在 main() 主体的末尾，在 system("pause"); 下方和 return 0; 上方（你在上一个快速入门中离开的位置），插入以下代码：

// Set up async FileHandler for input file operations
string inputFilePath = "<input-file-path>";
string actualFilePath = "<content-identifier>";
std::shared_ptr<FileHandler> handler;
try
{
     auto handlerPromise = std::make_shared<std::promise<std::shared_ptr<FileHandler>>>();
     auto handlerFuture = handlerPromise->get_future();
     engine->CreateFileHandlerAsync(
          inputFilePath,
          actualFilePath,                       
          true, 
          std::make_shared<FileHandlerObserver>(), 
          handlerPromise);
     handler = handlerFuture.get();
}
catch (const std::exception& e)
{
     cout << "An exception occurred... did you specify a valid input file path?\n\n" << e.what() << "'\n";
     system("pause");
     return 1;
}

// Set a label on input file
try
{
     string labelId = "<label-id>";
     cout << "\nApplying Label ID " << labelId << " to " << filePathIn << endl;
     mip::LabelingOptions labelingOptions(mip::AssignmentMethod::PRIVILEGED);
     handler->SetLabel(engine->GetLabelById(labelId), labelingOptions, new ProtectionSettings());
}
catch (const std::exception& e)
{
     cout << "An exception occurred... did you specify a valid label ID?\n\n" << e.what() << "'\n";
     system("pause");
     return 1; 
}

// Commit changes, save as a different/output file
string filePathOut = "<output-file-path>";
try
{
 	cout << "Committing changes" << endl;
     auto commitPromise = std::make_shared<std::promise<bool>>();
     auto commitFuture = commitPromise->get_future();
     handler->CommitAsync(filePathOut, commitPromise);
 	if (commitFuture.get()) {
 		cout << "\nLabel committed to file: " << filePathOut << endl;
 	}
 	else {
 		cout << "Failed to label: " + filePathOut << endl;
 		return 1;
 	}
}
catch (const std::exception& e)
{
     cout << "An exception occurred... did you specify a valid commit file path?\n\n" << e.what() << "'\n";
     system("pause");
     return 1;
}
system("pause");

// Set up async FileHandler for output file operations
actualFilePath = "<content-identifier>";
try
{
     auto handlerPromise = std::make_shared<std::promise<std::shared_ptr<FileHandler>>>();
     auto handlerFuture = handlerPromise->get_future();
     engine->CreateFileHandlerAsync(
          filePathOut,
          actualFilePath,
          true,
          std::make_shared<FileHandlerObserver>(),
          handlerPromise);

     handler = handlerFuture.get();
}
catch (const std::exception& e)
{
     cout << "An exception occurred... did you specify a valid output file path?\n\n" << e.what() << "'\n";
     system("pause");
     return 1;
}

// Get the label from output file
try
{
     cout << "\nGetting the label committed to file: " << filePathOut << endl;
     auto label = handler->GetLabel();
     cout << "Name: " + label->GetLabel()->GetName() << endl;
     cout << "Id: " + label->GetLabel()->GetId() << endl;
}
catch (const std::exception& e)
{
     cout << "An exception occurred... did you specify a valid label ID?\n\n" << e.what() << "'\n";
     system("pause");
     return 1;
}
system("pause");

在 main() 末尾找到在第一个快速入门中创建的应用程序关闭块并注释掉处理程序行：

// Application shutdown. Null out profile and engine, call ReleaseAllResources();
// Application may crash at shutdown if resources aren't properly released.
profile = nullptr;
engine = nullptr;
handler = nullptr;
mipContext = nullptr;

使用字符串常量替换源代码中的占位符值，如下所示：

占位符	值
<input-file-path>	测试输入文件的完整路径，例如：`"c:\\Test\\Test.docx"`。
<content-identifier>	内容的易记标识符。例如：对于文件，请考虑路径\文件名：`"c:\Test\Test.docx"` 对于电子邮件，请考虑主题:发件人：`"RE: Audit design:user1@contoso.com"`
<label-id>	从上一快速入门中的控制台输出复制的敏感度标签 ID，例如：`"f42a3342-8706-4288-bd31-ebb85995028z"`。
<output-file-path>	输出文件的完整路径，它将是输入文件的标记副本，例如：`"c:\\Test\\Test_labeled.docx"`。

生成并测试应用

生成和测试客户端应用程序。

使用 F6（生成解决方案）生成客户端应用程序。如果没有生成错误，请使用 F5（启动调试）运行应用程序。

如果项目成功生成并运行，则应用程序在 SDK 每次调用 AcquireOAuth2Token() 方法时都会提示输入访问令牌。正如之前在“列出敏感度标签”快速入门中所做的那样，每次都使用为 $authority 和 $resourceUrl 提供的值运行 PowerShell 脚本以获取令牌。

Run the PowerShell script to generate an access token using the following values, then copy/paste it below:

Sensitivity labels for your organization:
Non-Business : 87ba5c36-17cf-14793-bbc2-bd5b3a9f95cz
Public : 83867195-f2b8-2ac2-b0b6-6bb73cb33afz
General : f42a3342-8706-4288-bd31-ebb85995028z
Confidential : 074e457c-5848-4542-9a6f-34a182080e7z
Highly Confidential : f55c2dea-db0f-47cd-8520-a52e1590fb6z
Press any key to continue . . .

Applying Label ID 074e457c-5848-4542-9a6f-34a182080e7z to c:\Test\Test.docx
Committing changes

Label committed to file: c:\Test\Test_labeled.docx
Press any key to continue . . .

Getting the label committed to file: c:\Test\Test_labeled.docx
Name: Confidential
Id: 074e457c-5848-4542-9a6f-34a182080e7z
Press any key to continue . . .

可以通过打开输出文件并查看文档的信息保护设置来验证标签的应用。

注意

如果要标记 Office 文档，但未使用获得访问令牌（并配置了敏感度标签）的 Microsoft Entra 租户中的帐户登录，系统可能会提示先进行登录，然后才能打开标记的文档。

通过

快速入门：设置和获取敏感度标签 (C++)

先决条件

实现观察程序类来监视文件处理程序对象

添加逻辑以设置和获取敏感度标签

生成并测试应用

反馈

其他资源