Exemplarische Vorgehensweise: Aktivieren von Dokumentenverfolgung und -widerrufHow-to: enable document tracking and revocation

Dieses Thema bietet grundlegende Anleitungen zum Implementieren der Dokumentnachverfolgung für Inhalte sowie Beispielcode für Metadatenaktualisierungen und zum Erstellen einer Schaltfläche Verwendung nachverfolgen für Ihre App.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.

Schritte zum Implementieren der DokumentnachverfolgungSteps to implement document tracking

In den Schritten 1 und 2 wird die Nachverfolgung des Dokuments aktiviert.Steps 1 and 2 enable the document to be tracked. In Schritt 3 wird der Zugriff der App-Benutzer auf die Website für die Dokumentnachverfolgung eingerichtet, sodass Ihre geschützten Dokumente nachverfolgt und gesperrt werden können.Step 3 enables your app users to reach the document tracking site in order to track and revoke your protected documents.

  1. Hinzufügen von Metadaten für die DokumentnachverfolgungAdd document tracking metadata
  2. Registrieren des Dokuments beim RMS-DienstRegister the document with the RMS service
  3. Hinzufügen einer Schaltfläche „Verwendung nachverfolgen“ zur AppAdd Track Usage button to your app

Die Implementierungsdetails für diese Schritte folgen.The implementation details for these steps follow.

1. Hinzufügen von Dokumenten nach Verfolgungs Metadaten1. Add document tracking metadata

Dokumentnachverfolgung ist ein Feature des Rights Management-Systems.Document tracking is a feature of the Rights Management system. Durch das Hinzufügen bestimmter Metadaten während des Dokumentschutzprozesses kann ein Dokument beim Nachverfolgungsdienstportal registriert werden, das dann mehrere Optionen für die Nachverfolgung bereitstellt.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.

Verwenden Sie diese APIs zum Hinzufügen/Aktualisieren einer Inhaltslizenz mit Metadaten für die Dokumentnachverfolgung.Use these APIs to add/update a content license with document tracking metadata.

Im Prinzip sind nur für die Dokumentenverfolgung nur das contentName- und das notificationType-Objekt erforderlich.Operationally, only the content name and the notification type properties are required for document tracking.

  • IpcCreateLicenseMetadataHandleIpcCreateLicenseMetadataHandle

  • IpcSetLicenseMetadataPropertyIpcSetLicenseMetadataProperty

    Wir erwarten, dass Sie alle Metadateneigenschaften festlegen.We expect that you will set all of the metadata properties. Diese werden im Folgenden nach Typ aufgelistet.Here they are, listed by type.

    Weitere Informationen finden Sie unter Lizenzmetadaten-Eigenschaftstypen.For more information, see License metadata property types.

    • IPC_MD_CONTENT_PATHIPC_MD_CONTENT_PATH

      Hiermit identifizieren Sie das nachverfolgte Dokument.Use to identify the tracked document. In Fällen, in denen ein vollständiger Pfad nicht möglich ist, geben Sie nur den Dateinamen an.In cases where a full path is not possible, just provide the file name.

    • IPC_MD_CONTENT_NAMEIPC_MD_CONTENT_NAME

      Hiermit identifizieren Sie den Namen des nachverfolgten Dokuments.Use to identify the tracked document name.

    • IPC_MD_NOTIFICATION_TYPEIPC_MD_NOTIFICATION_TYPE

      Damit geben Sie an, wann eine Benachrichtigung gesendet wird.Use to specify when notification will be sent. Weitere Informationen finden Sie unter „Benachrichtigungstyp“.For more information, see Notification type.

    • IPC_MD_NOTIFICATION_PREFERENCEIPC_MD_NOTIFICATION_PREFERENCE

      Damit geben Sie den Benachrichtigungstyp an.Use to specify the type of notification. Weitere Informationen finden Sie unter „Benachrichtigungseinstellungen“.For more information, see Notification preference.

    • IPC_MD_DATE_MODIFIEDIPC_MD_DATE_MODIFIED

      Es wird empfohlen, dieses Datum bei jedem Klicken des Benutzers auf „Speichern“ festzulegen.We suggest that you set this date each time the user clicks Save.

    • IPC_MD_DATE_CREATEDIPC_MD_DATE_CREATED

      Legen Sie hier das Ursprungsdatum der Datei fest.Use to set the origination date of the file

  • IpcSerializeLicenseWithMetadataIpcSerializeLicenseWithMetadata

Verwenden Sie die richtige dieser APIs, um die Metadaten Ihrer Datei oder Ihrem Stream hinzuzufügen.Use the appropriate one of these APIs to add the metadata to your file or stream.

Verwenden Sie schließlich diese API, um das nachverfolgte Dokument beim Nachverfolgungssystem zu registrieren.Lastly, use this API to register your tracked document with the tracking system.

2. registrieren Sie das Dokument beim RMS-Dienst.2. Register the document with the RMS service

Es folgt ein Codeausschnitt, der ein Beispiel für das Festlegen der Metadaten für die Dokumentnachverfolgung und das Aufrufen für die Registrierung beim Nachverfolgungssystem zeigt.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);

Hinzufügen einer Schaltfläche Verwendung nachverfolgen zur AppAdd a Track Usage button to your app

Das Hinzufügen einer Schaltfläche Verwendung nachverfolgen zur App ist genauso einfach wie die Verwendung eines der folgenden URL-Formate:Adding a Track Usage UI item to your app is as simple as using one of the following URL formats:

  • Verwenden der Inhalts-IDUsing Content ID

    • Rufen Sie die Inhalts-ID mit IpcGetLicenseProperty oder der IpcGetSerializedLicenseProperty ab, wenn die Lizenz serialisiert ist, und verwenden Sie die Lizenzeigenschaft 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. Weitere Informationen finden Sie unter den Angaben zu Lizenzeigenschaftstypen.For more information, see License property types.

    • Verwenden Sie die Metadaten contentid und Aussteller , und verwenden Sie das folgende Format:https://track.azurerms.com/#/{ContentId}/{Issuer}With the ContentId and Issuer metadata, use the following format: https://track.azurerms.com/#/{ContentId}/{Issuer}

      Beispiel – 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

  • Wenn Sie keinen Zugriff auf diese Metadaten haben (d. h., Sie untersuchen die ungeschützte Version des Dokuments), können Sie die Content_Name im folgenden Format verwenden: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}

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

Der Client muss lediglich einen Browser mit der entsprechenden URL öffnen.The client simply needs to open a browser with the appropriate URL. Im Portal für die RMS-Dokumentnachverfolgung werden die Authentifizierung und alle erforderlichen Umleitungen verarbeitet.The RMS Document Tracking portal will handle authentication and any required redirection.