Assinar as notificações de lista

Artigo
03/21/2023

Introduzido em Estrutura do SharePoint v1.7.0, você pode assinar alterações nos arquivos armazenados em uma Biblioteca de Documentos do SharePoint. Isso permite responder a alterações quando elas ocorrerem, sem precisar fazer votação regularmente no conteúdo da biblioteca.

Pré-requisitos

Para usar o recurso de assinatura de lista Estrutura do SharePoint, primeiro você precisa instalar o pacote npm @microsoft/sp-list-subscription. Você pode fazer isso usando o snippet de código a seguir:

npm install @microsoft/sp-list-subscription --save --save-exact

Ser notificado sobre alterações em documentos armazenados em uma biblioteca de documentos do SharePoint

Para assinar alterações em arquivos armazenados em uma biblioteca de documentos do SharePoint, crie uma instância da classe ListSubscriptionFactory. Em seguida, chame o método createSubscription() passando a ID da biblioteca de documentos que você deseja assinar. Se a biblioteca de documentos estiver localizada no site atual, será suficiente especificar apenas a ID da biblioteca. Se ele estiver localizado em um site ou conjunto de sites diferente, você precisará especificar suas IDs também.

Veja a seguir um exemplo de uma assinatura da lista para uma biblioteca de documentos localizada no site atual:

import { ListSubscriptionFactory, IListSubscription } from '@microsoft/sp-list-subscription';
import { Guid } from '@microsoft/sp-core-library';

export default class LatestDocumentsWebPart extends BaseClientSideWebPart<ILatestDocumentsWebPartProps> {
  private _listSubscriptionFactory: ListSubscriptionFactory;
  private _listSubscription: IListSubscription;

  private async createListSubscription(): Promise<void> {
    this._listSubscriptionFactory = new ListSubscriptionFactory(this);
    this._listSubscription = await this._listSubscriptionFactory.createSubscription({
      listId: Guid.parse(this.properties.listId),
      callbacks: {
        notification: this._loadDocuments.bind(this)
      }
    });
  }

  private _loadDocuments(): void {
    // load documents here
  }

  // omitted for brevity
}

Ao criar uma assinatura da lista, usando a propriedade callbacks.notification, você precisa especificar o método que deve ser chamado quando uma alteração foi detectada. O método não tem argumentos e, por motivos de segurança, você não recebe notificações do que foi alterado exatamente. Para obter o conteúdo mais recente da biblioteca de documentos, aderindo às permissões configuradas, você pode usar as APIs REST do SharePoint ou o Microsoft Graph.

Configuração adicional

Dependendo da solução, talvez seja necessário fornecer configuração adicional ao assinar notificações de lista.

Conectar a um conjunto de sites em um locatário multigeográfico

Se você usar o SharePoint em um locatário multigeográfico, será necessário fornecer o domínio no qual o conjunto de sites específico reside. Você pode fazer isso usando a propriedade domain, por exemplo:

this._listSubscriptionFactory.createSubscription({
  domain: this.properties.siteDomain,
  siteId: Guid.parse(this.properties.siteId),
  webId: Guid.parse(this.properties.webId),
  listId: Guid.parse(this.properties.listId),
  callbacks: {
    notification: this._loadDocuments.bind(this)
  }
});

Seja notificado quando a assinatura tiver sido estabelecida ou cancelada

Em alguns casos, convém receber notificações quando o componente que você está criando assinou com êxito notificações de lista ou se a conexão foi interrompida. Isso permitirá que você comunique a conexão para o usuário por meio da interface do usuário.

A API de assinatura de lista expõe dois retornos de chamada adicionais que você pode implementar para responder ao status da assinatura. O código a seguir ilustra o caso, em que o componente será notificado quando a assinatura tiver sido estabelecida e quando ele foi desconectado.

private createListSubscription(): void {
  this._listSubscriptionFactory.createSubscription({
    domain: this.properties.siteDomain,
    siteId: Guid.parse(this.properties.siteId),
    webId: Guid.parse(this.properties.webId),
    listId: Guid.parse(this.properties.listId),
    callbacks: {
      notification: this._loadDocuments.bind(this),
      connect: this._subscriptionConnected.bind(this),
      disconnect: this._subscriptionDisconnected.bind(this)
    }
  });
}

private _subscriptionConnected(): void {
  // code to execute when the subscription to the list has been established
}

private _subscriptionDisconnected(reason: string): void {
  // code to execute when the connection to the list has been disconnected
}

O método para o retorno de chamada callbacks.disconnect passa como argumento o motivo por que a conexão foi desconectada. Os valores possíveis são io server disconnect, quando a conexão foi interrompida pelo cliente ou io client disconnect, quando o servidor fecha a conexão.

Considerações

todos os componentes Estrutura do SharePoint podem usar os recursos de assinatura de lista
você pode assinar eventos de bibliotecas e listas
há alguns segundos de atraso entre a alteração e a notificação recebida pelo componente
componentes podem assinar alterações em várias bibliotecas de documentos
a notificação de alteração não passa informações sobre o documento adicionado ou alterado. Para ver o que foi alterado, use a API REST do SharePoint ou o Microsoft Graph

Confira também

Código de exemplo das assinaturas de lista

Compartilhar via