操作说明:启用文档跟踪和撤销How-to: enable document tracking and revocation

本主题涵盖实现文档内容跟踪的基本指导,并提供用于元数据更新和为应用创建“跟踪使用情况按钮(#跟踪使用情况按钮)”的示例代码。This topic covers the basic guidance for implementing document tracking of content as well as example code for metadata updates and for creating a Track Usage button for your app.

实现文档跟踪的步骤Steps to implement document tracking

步骤 1 和步骤 2 可允许跟踪文档。Steps 1 and 2 enable the document to be tracked. 第 3 步可允许应用用户访问文档跟踪站点,以便跟踪和撤销受保护的文档。Step 3 enables your app users to reach the document tracking site in order to track and revoke your protected documents.

  1. 添加文档跟踪元数据Add document tracking metadata
  2. 向 RMS 服务注册文档Register the document with the RMS service
  3. 向应用添加“跟踪使用情况”按钮Add Track Usage button to your app

这些步骤的实现详细信息如下。The implementation details for these steps follow.

1. 添加文档跟踪元数据1. Add document tracking metadata

文档跟踪是 Rights Management 系统的一个功能。Document tracking is a feature of the Rights Management system. 通过在文档保护过程中添加特定的元数据,可以使用提供多个跟踪选项的跟踪服务门户来注册文档。By adding specific metadata during the document protection process, a document can be registered with the tracking service portal which then provides several options for tracking.

使用此 API 添加/更新具有文档跟踪元数据的内容许可证。Use these APIs to add/update a content license with document tracking metadata.

在操作上,只有 内容名称通知类型 属性对于文档跟踪是必需的。Operationally, only the content name and the notification type properties are required for document tracking.

  • IpcCreateLicenseMetadataHandleIpcCreateLicenseMetadataHandle

  • IpcSetLicenseMetadataPropertyIpcSetLicenseMetadataProperty

    我们期望你能设置所有元数据属性。We expect that you will set all of the metadata properties. 就是以下这些按类型列出的属性。Here they are, listed by type.

    有关详细信息,请参阅许可证元数据属性类型For more information, see License metadata property types.

    • IPC_MD_CONTENT_PATHIPC_MD_CONTENT_PATH

      用于标识跟踪的文档。Use to identify the tracked document. 如果完整的路径不可用,则只需提供文件名。In cases where a full path is not possible, just provide the file name.

    • IPC_MD_CONTENT_NAMEIPC_MD_CONTENT_NAME

      用于标识跟踪的文档名称。Use to identify the tracked document name.

    • IPC_MD_NOTIFICATION_TYPEIPC_MD_NOTIFICATION_TYPE

      用于指定发送通知的时间。Use to specify when notification will be sent. 有关详细信息,请参阅“通知类型”。For more information, see Notification type.

    • IPC_MD_NOTIFICATION_PREFERENCEIPC_MD_NOTIFICATION_PREFERENCE

      用于指示通知的类型。Use to specify the type of notification. 有关详细信息,请参阅通知偏好设置。For more information, see Notification preference.

    • IPC_MD_DATE_MODIFIEDIPC_MD_DATE_MODIFIED

      我们建议在每次用户单击“保存”时设置此日期。We suggest that you set this date each time the user clicks Save.

    • IPC_MD_DATE_CREATEDIPC_MD_DATE_CREATED

      用于设置文件的发放日期Use to set the origination date of the file

  • IpcSerializeLicenseWithMetadataIpcSerializeLicenseWithMetadata

使用其中一个合适的 API 将元数据添加到文件或流中。Use the appropriate one of these APIs to add the metadata to your file or stream.

最后,使用此 API 注册具有跟踪系统的跟踪文档。Lastly, use this API to register your tracked document with the tracking system.

2. 向 RMS 服务注册文档2. Register the document with the RMS service

以下是代码段,显示了设置文档跟踪元数据的示例和对跟踪系统中注册的调用。Here's a code snippet showing an example of setting document tracking metadata and the call to register with the tracking system.

C + +C++:

    HRESULT hr = S_OK;
    LPCWSTR wszOutputFile = NULL;
    wstring wszWorkingFile;
    IPC_LICENSE_METADATA md = {0};

    md.cbSize = sizeof(IPC_LICENSE_METADATA);
    md.dwNotificationType = IPCD_CT_NOTIFICATION_TYPE_ENABLED;
    md.dwNotificationPreference = IPCD_CT_NOTIFICATION_PREF_DIGEST;
    //file origination date, current time for this example
    md.ftDateCreated = GetCurrentTime();
    md.ftDateModified = GetCurrentTime();

    LOGSTATUS_EX(L"Encrypt file with official template...");

    hr =IpcfEncryptFileWithMetadata( wszWorkingFile.c_str(),
                             m_wszTestTemplateID.c_str(),
                             IPCF_EF_TEMPLATE_ID,
                             0,
                             NULL,
                             NULL,
                             &md,
                             &wszOutputFile);

   /* This will contain the serialized license */
   PIPC_BUFFER pSerializedLicense;

   /* the context to use for the call */
   PCIPC_PROMPT_CTX pContext;

   wstring wstrContentName("MyDocument.txt");
   bool sendLicenseRegistrationNotificationEmail = FALSE;

   hr = IpcRegisterLicense( pSerializedLicense,
                      0,
                      pContext,
                      wstrContentName.c_str(),
                      sendLicenseRegistrationNotificationEmail);

向应用添加跟踪使用情况按钮Add a Track Usage button to your app

向应用添加跟踪使用情况 UI 项非常简单,使用以下任一 URL 格式即可:Adding a Track Usage UI item to your app is as simple as using one of the following URL formats:

  • 使用内容 IDUsing Content ID

    • 如果许可证已序列化,请使用 IpcGetLicensePropertyIpcGetSerializedLicenseProperty 获取内容 ID,并使用许可证属性 IPC_LI_CONTENT_IDGet the content ID by using IpcGetLicenseProperty or IpcGetSerializedLicenseProperty if the license is serialized and use the license property IPC_LI_CONTENT_ID. 有关详细信息,请参阅许可证属性类型For more information, see License property types.

    • 对于id 为Issuer元数据,使用以下格式:https://track.azurerms.com/#/{ContentId}/{Issuer}With the ContentId and Issuer metadata, use the following format: https://track.azurerms.com/#/{ContentId}/{Issuer}

      示例 - https://track.azurerms.com/#/summary/05405df5-8ad6-4905-9f15-fc2ecbd8d0f7/janedoe@microsoft.comExample - https://track.azurerms.com/#/summary/05405df5-8ad6-4905-9f15-fc2ecbd8d0f7/janedoe@microsoft.com

  • 如果无权访问该元数据(即检查文档的不受保护的版本),可以使用以下格式的Content_Namehttps://track.azurerms.com/#/?q={ContentName}If you don’t have access to that metadata (i.e. you are examining the unprotected version of the document), you can use the Content_Name in the following format: https://track.azurerms.com/#/?q={ContentName}

    示例 - https://track.azurerms.com/#/?q=Secret!.txtExample - https://track.azurerms.com/#/?q=Secret!.txt

客户端只需要使用适当的 URL 打开浏览器。The client simply needs to open a browser with the appropriate URL. RMS 文档跟踪门户将处理身份验证和任何所需重定向。The RMS Document Tracking portal will handle authentication and any required redirection.