Procedimentos: ativar o controlo e a revogação de documentosHow-to: enable document tracking and revocation

Este tópico inclui a documentação de orientação básica para implementação do controlo de documento do conteúdo, bem como código de exemplo para atualizações de metadados e criação de um botão Controlar Utilização para a sua aplicação.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.

Passos para implementar o controlo de documentoSteps to implement document tracking

Os passos 1 e 2 ativam o controlo de documento.Steps 1 and 2 enable the document to be tracked. O passo 3 permite que os utilizadores de aplicação acedam ao site de controlo de documentos para controlarem e revogarem os seus documentos protegidos.Step 3 enables your app users to reach the document tracking site in order to track and revoke your protected documents.

  1. Adicionar metadados de controlo de documentoAdd document tracking metadata
  2. Registar o documento no serviço RMSRegister the document with the RMS service
  3. Adicionar o botão Controlar Utilização à sua aplicaçãoAdd Track Usage button to your app

Os detalhes de implementação para estes passos são descritos em seguida.The implementation details for these steps follow.

1. Adicionar metadados de controlo de documento1. Add document tracking metadata

O controlo de documentos é uma funcionalidade do sistema Rights Management.Document tracking is a feature of the Rights Management system. Ao adicionar metadados específicos durante o processo de proteção de documentos, um documento pode ser registado com o portal do serviço de controlo que fornece várias opções de controlo.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.

Utilize estas APIs para adicionar/atualizar uma licença de conteúdo com os metadados de controlo de documentos.Use these APIs to add/update a content license with document tracking metadata.

Operacionalmente, apenas as propriedades nome do conteúdo e tipo de notificação são necessárias para o controlo de documentos.Operationally, only the content name and the notification type properties are required for document tracking.

  • IpcCreateLicenseMetadataHandleIpcCreateLicenseMetadataHandle
  • IpcSetLicenseMetadataPropertyIpcSetLicenseMetadataProperty

    Esperamos que defina todas as propriedades de metadados.We expect that you will set all of the metadata properties. Aqui estão, listadas por tipo.Here they are, listed by type.

    Para obter mais informações, consulte Tipos de propriedade de metadados de licença.For more information, see License metadata property types.

    • IPC_MD_CONTENT_PATHIPC_MD_CONTENT_PATH

      Utilize para identificar o documento controlado.Use to identify the tracked document. Nos casos em que um caminho completo não seja possível, basta indicar o nome do ficheiro.In cases where a full path is not possible, just provide the file name.

    • IPC_MD_CONTENT_NAMEIPC_MD_CONTENT_NAME

      Utilize para identificar o nome do documento controlado.Use to identify the tracked document name.

    • IPC_MD_NOTIFICATION_TYPEIPC_MD_NOTIFICATION_TYPE

      Utilize para especificar quando a notificação será enviada.Use to specify when notification will be sent. Para obter mais informações, consulte Tipo de notificação.For more information, see Notification type.

    • IPC_MD_NOTIFICATION_PREFERENCEIPC_MD_NOTIFICATION_PREFERENCE

      Utilize para especificar o tipo de notificação.Use to specify the type of notification. Para obter mais informações, consulte Preferência de notificação.For more information, see Notification preference.

    • IPC_MD_DATE_MODIFIEDIPC_MD_DATE_MODIFIED

      Sugerimos que defina esta data sempre que o utilizador clicar em Guardar.We suggest that you set this date each time the user clicks Save.

    • IPC_MD_DATE_CREATEDIPC_MD_DATE_CREATED

      Utilize para definir a data de origem do ficheiroUse to set the origination date of the file

  • IpcSerializeLicenseWithMetadataIpcSerializeLicenseWithMetadata

Utilize a API adequada das apresentadas para adicionar os metadados ao seu ficheiro ou fluxo.Use the appropriate one of these APIs to add the metadata to your file or stream.

Por último, utilize esta API para registar o documento controlado com o sistema de controlo.Lastly, use this API to register your tracked document with the tracking system.

2. Registar o documento no serviço RMS2. Register the document with the RMS service

Veja a seguir um fragmento de código que mostra um exemplo de definição de metadados de controlo de documentos e a chamada para registar com o sistema de controlo.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);

Adicionar um botão Controlar Utilização à sua aplicaçãoAdd a Track Usage button to your app

Adicionar um item de IU Controlar Utilização à sua aplicação é tão simples quanto utilizar um dos seguintes formatos de URL:Adding a Track Usage UI item to your app is as simple as using one of the following URL formats:

  • Utilizar ID de ConteúdoUsing Content ID

    • Obtenha o ID de conteúdo utilizando IpcGetLicenseProperty ou IpcGetSerializedLicenseProperty, se a licença for serializada e utilize a propriedade de licença 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. Para obter mais informações, consulte Tipos de propriedade de licença.For more information, see License property types.
    • Com os metadados ContentId e Issuer, utilize o seguinte formato: https://track.azurerms.com/#/{ContentId}/{Issuer}With the ContentId and Issuer metadata, use the following format: https://track.azurerms.com/#/{ContentId}/{Issuer}

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

  • Se não tiver acesso a esses metadados (ou seja, está a examinar a versão não protegida do documento), pode utilizar Content_Name no seguinte formato: 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}

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

O cliente só tem de abrir um browser com o URL adequado.The client simply needs to open a browser with the appropriate URL. O portal de Controlo de Documento RMS processará a autenticação e qualquer redirecionamento necessário.The RMS Document Tracking portal will handle authentication and any required redirection.

ComentáriosComments

Antes de inserir um comentário, pedimos-lhe que reveja as nossas Regras básicas.Before commenting, we ask that you review our House rules.