方法: ドキュメント追跡の有効化と取り消し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.

    詳細については、「License metadata property types (ライセンス メタデータ プロパティの種類)」を参照してください。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. 詳細については、「Notification type (通知の種類)」を参照してください。For more information, see Notification type.

    • IPC_MD_NOTIFICATION_PREFERENCEIPC_MD_NOTIFICATION_PREFERENCE

      通知の種類の指定に使用します。Use to specify the type of notification. 詳細については、「Notification preference (通知の基本設定)」を参照してください。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++
  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:

  • コンテンツ ID の使用Using Content ID

    • ライセンスがシリアル番号になっており、ライセンス プロパティの IPC_LI_CONTENT_ID が使用される場合、IpcGetLicenseProperty または IpcGetSerializedLicenseProperty を使用してコンテンツ ID を入手します。Get the content ID by using IpcGetLicenseProperty or IpcGetSerializedLicenseProperty if the license is serialized and use the license property IPC_LI_CONTENT_ID. 詳細については、「License property types」 (ライセンスのプロパティの種類) を参照してください。For more information, see License property types.

    • メタデータの ContentIdIssuer については、次の形式を使用します。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.