如何：啟用文件追蹤和撤銷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:

  • 使用內容識別碼Using Content ID

    • 使用 IpcGetLicenseProperty 取得內容識別碼；若授權已序列化則使用 IpcGetSerializedLicenseProperty，並使用授權屬性 IPC_LI_CONTENT_ID。Get 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.

    • 使用 ContentId 和 簽發者 中繼資料，請使用下列格式： 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_Name ： https://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.