Eventos externos e os alertas no Microsoft Office SharePoint Online

Saiba os conceitos por trás da criação de receptores de eventos remotos no SharePoint que podem ser anexados a listas externas e executados quando os dados externos que a lista representa são atualizados.

Cite receptores de evento.

Um receptor de eventos é uma parte do código gerenciado que responde ao SharePoint disparando eventos como adicionar, mover, excluir, fazer check-in e fazer check-out. Quando esses eventos ocorrem e os critérios do receptor de eventos são atendidos, o código que você grava para fornecer funcionalidade adicional é executado. Quando objetos do SharePoint, como listas, fluxos de trabalho e recursos, são configurados para aguardar esses eventos ocorrerem, eles são chamados de hosts de eventos.

Receptores de evento permitem que você execute a lógica de negócios quando ocorre um evento específico. Basicamente, esses são os ganchos onde você pode criar um código para lidar com certas condições, faça as notificações, atualizar outros sistemas e assim por diante. Quando você cria receptores de eventos, uma DLL é gerada. Você pode colocar esse DLL no cache de assembly global, para que os receptores de evento são invocados em resposta a quaisquer alterações em um sistema externo.

O exemplo a seguir contém um receptor de evento externo simples em c# que é executado quando um novo item é adicionado à lista.

public class EntryContentEventReceiver : SPItemEventReceiver
{
  public override void ItemAdded(SPItemEventProperties properties)
  {
    base.ItemAdded(properties);
    // properties.ExternalNotificationMessage holds the message sent by the external system
  }
}

Os receptores de eventos externos também podem ser estendidos para trabalhar em um receptor de eventos de entidade e como receptores de eventos remotos implantados como um serviço local ou no Microsoft Azure.

Cite receptores de evento remoto.

Os receptores de eventos remotos são novos para o SharePoint. Uma solução do SharePoint tradicional, você usa um receptor de evento para manipular eventos como criar ou excluir listas ou itens em listas de usuários. Um Suplemento do SharePoint, você usa um receptor de evento remoto para manipular eventos semelhantes. Receptores de evento remoto funcionam da mesma forma para receptores de evento regular, exceto pelo fato de receptores de evento remoto lidar com eventos que ocorrem quando um Suplemento do SharePoint estiver em um sistema diferente do seu aplicativo da web de host.

Business Connectivity Services (BCS) usa anexados a listas externas e entidades de receptores de evento remoto para permitir que você escreva código que possa reagir às alterações de dados hospedados no sistema externo.

Para acomodar isso, dois estereótipos foram adicionados ao esquema do modelo BDC: EventSubscriber e EventUnsubscriber.

Quais recursos e capacidades a nova infra-estrutura do receptor de evento externo oferece?

Usando e estendendo os recursos do receptor de eventos do SharePoint, o BCS é capaz de adicionar alertas, receptores de eventos de lista externa e receptores de entidade para fornecer funcionalidade estendida.

• Alertas: Os alertas têm sido parte integrante do SharePoint para várias versões, mas até o arePoint, eles não funcionariam com listas externas. Agora um usuário pode criar alertas em uma lista externa que têm o mesmo comportamento de alertas em uma lista do SharePoint padrão.
• Receptores de evento de lista externa: Receptores de evento agora podem ser anexados às listas externas exatamente como eles podem para listas padrão. Isso fornece um mecanismo de extensibilidade que permite que você escreva de que é executado em momentos específicos.
• Receptores de evento de entidade: Receptores de evento de entidade proporcionam flexibilidade, permitindo que você escreva código mais robusto que permite que outras operações como fornecer o contexto do usuário para filtragem de dados. Isso pode permitir que melhor personalização e segurança personalizada.

O evento remoto no SharePoint torna vários cenários interessantes possíveis. Por exemplo, você pode ter um aplicativo "Vendas liderança acompanhamento" que permite que uma equipe de vendas ser notificado quando novos clientes potenciais são inseridos em um aplicativo externo líder. Quando um novo líder de venda for digitado, SharePoint é notificado por meio do sistema de notificação que faz parte do aplicativo cliente potencial. SharePoint recebe a notificação e cria novas tarefas para os vendedores especificados a ser acompanhado em cada novo líder. Configurando o aplicativo de entrada de entrega das vendas no sistema externo para enviar uma notificação para o SharePoint na criação de cada novo líder, SharePoint é mantido completamente atualizado.

Pré-requisitos para o uso de receptores de evento para listas externas

Para usar os receptores de evento para listas externas, você precisará dos seguintes itens:

• SharePoint
• Visual Studio 2012

Para obter mais informações sobre como configurar um ambiente de desenvolvimento do SharePoint, consulte Configurar um ambiente de desenvolvimento geral para o SharePoint.

Configurar o sistema externo para notificar o SharePoint de eventos externos

Para eventos externos funcionar, um número de componentes precisa ser instalado e configurado no host do SharePoint e o sistema externo.

Você precisa configurar o sistema externo para que ele possa fazer o seguinte:

• Determinar quando as alterações de dados de base. Para o sistema externo saber quando são feitas alterações, você precisa criar um mecanismo para sondagem para alterações específicas. Você pode fazer isso usando um serviço cronometrado que controla a fonte de dados a intervalos específicos.
• Recebimento e solicitações de registro de assinaturas para notificações de alteração. O sistema externo deve implementar um repositório de inscrição para que ele possa armazenar que devem receber notificações de alteração. Provavelmente, a solução mais simples é uma tabela de banco de dados. A tabela (ou qualquer anismo que você escolher) deve gravar SubscriptionID, Endereço de Entrega, Tipo de Evento e Nome da Entidade.
• Postar notificações aos pontos de extremidade de transferência de estado representacional (REST). Para que os assinantes do SharePoint saibam que ocorreu uma alteração, o aplicativo do sistema externo precisa enviar um HTTPWebRequest para o endereço de entrega registrado no repositório de assinaturas. Esse endereço de entrega é um ponto de extremidade RESTful gerado pelo SharePoint durante o processo de assinatura

Configurar o SharePoint para permitir a comunicação com sistemas externos

Para permitir a comunicação com o sistema externo, o SharePoint deve ser configurado com os seguintes itens:

• Um modelo BDC com EventSubscriber e EventUnsubscriber estereótipos configurado
• Receptores de eventos

Como a eventos externos está habilitado?

Você pode habilitar o evento externo no SharePoint por meio de Configurações do Site ou adicionando a seguinte ID de recurso personalizado ao seu projeto

<ActivationDependency FeatureTitle="BCSEvents" FeatureId="60c8481d-4b54-4853-ab9f-ed7e1c21d7e4" />

Eventos de um sistema externo é habilitado quando o SharePoint cria o endereço do destinatário e enviá-la para o sistema externo durante o processo de assinatura.

Fluxo geral do eventos externos entre o SharePoint e sistemas externos

Na Figura 1, observe que há três etapas distintas envolvidas ao usar os receptores de evento externo: inscrever, notificação e Cancelar.

Figura 1 o fluxo de dados completa para notificações externas

Data flow for external event notifications

EventSubscriber: Assine as notificações

Para um usuário (SharePoint object) receber notificações quando os dados subjacentes foi alterada, o usuário deve assine as notificações para uma entidade. Para permitir isso, o esquema de modelo BDC foi estendido para incluir o estereótipo Subscribe. O estereótipo Subscribe é usado pelo SharePoint para informar o sistema externo que o remetente está solicitando sejam notificados das alterações nos dados base.

Figura 2 demonstra o fluxo de informações entre o SharePoint e o sistema externo durante o processo de assinatura.

Figura 2. Fluxo de processo de assinatura

O exemplo a seguir descreve o fluxo geral do processo de assinatura:

1. Usuário solicita uma assinatura de notificações. Usando uma interface de usuário personalizada (um botão em uma página ou uma faixa de opções), o SharePoint inicia uma solicitação para o aplicativo de sistema externo para notificações.

2. SharePoint gera um endereço de entrega. Como parte do processo de assinatura, o SharePoint cria um ponto de extremidade REST onde as notificações serão entregue.

3. Solicitação de assinatura é enviada para o sistema externo. SharePoint encapsula as informações do solicitante junto com a URL do REST gerada dinamicamente e envia uma solicitação da web para o sistema externo.

4. Sistema externo recebe a solicitação. Há diferentes possibilidades para a implementação de um repositório de inscrição. Neste exemplo, você usará uma tabela de banco de dados do SQL Server.

5. Sistema externo gera um subscriptionId. Um novo subscriptionId é gerado usando o código no aplicativo de linha de negócios (LOB). O subscriptionId deve ser um GUID.

6. a inscrição de registros do sistema externo. O aplicativo de sistema externo registra o subscriptionId, endereço de entrega, tipo de evento e outras informações enviadas a partir do SharePoint para o repositório de inscrição.

7. Sistema externo envia a subscriptionId para o SharePoint. Para o SharePoint rotear corretamente as atualizações que são enviadas pelo sistema externo, o subscriptionId será enviada para SharePoint e SharePoint registros essas informações no seu banco de dados.

   O modelo BDC está funcionando contra uma importação de função Subscribe. Os metadados para a importação de função é mostrado neste exemplo.

<EntityType Name="EntitySubscribe">
   <Key>
      <PropertyRef Name="SubscriptionId" />
   </Key>
   <Property xmlns:p6="http://schemas.microsoft.com/ado/2009/02/edm/annotation"
             Name="SubscriptionId"
             Type="Edm.Int32"
             Nullable="false"
             p6:StoreGeneratedPattern="Identity" />
   <Property Name="EntityName"
             Type="Edm.String"
             MaxLength="250"
             FixedLength="false"
             Unicode="true" />
   <Property Name="DeliveryURL"
             Type="Edm.String"
             MaxLength="250"
             FixedLength="false"
             Unicode="true" />
   <Property Name="EventType" Type="Edm.Int32" />
   <Property Name="UserId"
             Type="Edm.String"
             MaxLength="50"
             FixedLength="false"
             Unicode="true" />
   <Property xmlns:p6="http://schemas.microsoft.com/ado/2009/02/edm/annotation"
             Name="SubscribeTime"
             Type="Edm.Binary"
             MaxLength="8"
             FixedLength="true"
             p6:StoreGeneratedPattern="Computed" />
   <Property Name="SelectColumns"
             Type="Edm.String"
             MaxLength="10"
             FixedLength="false"
             Unicode="true" />
</EntityType>

Exemplo de código: o modelo BDC com Subscribe

O exemplo a seguir é um exemplo de um modelo BDC com o método Subscribe adicionado.

<Method Name="SubscribeCustomer" DefaultDisplayName="Customer Subscribe" IsStatic="true">
   <Properties>
     <Property Name="ODataEntityUrl" Type="System.String">/EntitySubscribes</Property>
     <Property Name="ODataHttpMethod" Type="System.String">POST</Property>
     <Property Name="ODataPayloadKind" Type="System.String">Entry</Property>
     <Property Name="ODataFormat" Type="System.String">application/atom+xml</Property>
     <Property Name="ODataServiceOperation" Type="System.Boolean">false</Property>
   </Properties>
   <AccessControlList>
      <AccessControlEntry Principal="NT Authority\\Authenticated Users">
         <Right BdcRight="Edit" />
         <Right BdcRight="Execute" />
         <Right BdcRight="SetPermissions" />
         <Right BdcRight="SelectableInClients" />
      </AccessControlEntry>
   </AccessControlList>
   <Parameters>
      <Parameter Direction="In" Name="@DeliveryURL">
         <TypeDescriptor TypeName="System.String" Name="DeliveryURL" >
            <Properties>
               <Property Name="IsDeliveryAddress" Type="System.Boolean">true</Property>
            </Properties>
         </TypeDescriptor>
      </Parameter>
      <Parameter Direction="In" Name="@EventType">
         <TypeDescriptor TypeName="System.Int32" Name="EventType" >
            <Properties>
               <Property Name="IsEventType" Type="System.Boolean">true</Property>
            </Properties>
         </TypeDescriptor>
      </Parameter>
      <Parameter Direction="In" Name="@EntityName">
         <TypeDescriptor TypeName="System.String" Name="EntityName" >
            <DefaultValues>
               <DefaultValue MethodInstanceName="SubscribeCustomer"
                  Type="System.String">Customers</DefaultValue>
            </DefaultValues>
      </TypeDescriptor>
    </Parameter>
    <Parameter Direction="In" Name="@SelectColumns">
      <TypeDescriptor TypeName="System.String" Name="SelectColumns" >
        <DefaultValues>
          <DefaultValue MethodInstanceName="SubscribeCustomer" Type="System.String">*</DefaultValue>
        </DefaultValues>
      </TypeDescriptor>
    </Parameter>
    <Parameter Direction="Return" Name="SubscribeReturn">
      <TypeDescriptor Name="SubscribeReturnRootTd" TypeName="Microsoft.BusinessData.Runtime.DynamicType">
        <TypeDescriptors>
          <TypeDescriptor Name="SubscriptionId" TypeName="System.String" >
            <Properties>
              <Property Name="SubscriptionIdName" Type="System.String">Default</Property>
            </Properties>
            <Interpretation>
              <ConvertType LOBType="System.Int32" BDCType="System.String"/>
            </Interpretation>
          </TypeDescriptor>
          <TypeDescriptor Name="DeliveryURL" TypeName="System.String" />
          <TypeDescriptor Name="SelectColumns" TypeName="System.String" >
          </TypeDescriptor>
          <TypeDescriptor Name="EntityName" TypeName="System.String" />
          <TypeDescriptor Name="EventType" TypeName="System.Int32" />
          <TypeDescriptor Name="UserId" TypeName="System.String" />
          <!--TypeDescriptor Name="SubscribeTime" TypeName="System." /-->
        </TypeDescriptors>
      </TypeDescriptor>
    </Parameter>
  </Parameters>
  <MethodInstances>
    <MethodInstance Type="EventSubscriber" ReturnParameterName="SubscribeReturn" ReturnTypeDescriptorPath="SubscribeReturnRootTd" Default="true" Name="SubscribeCustomer" DefaultDisplayName="Customer Subscribe">
      <AccessControlList>
        <AccessControlEntry Principal="NT Authority\\Authenticated Users">
          <Right BdcRight="Edit" />
          <Right BdcRight="Execute" />
          <Right BdcRight="SetPermissions" />
          <Right BdcRight="SelectableInClients" />
        </AccessControlEntry>
      </AccessControlList>
    </MethodInstance>
  </MethodInstances>
</Method>

A tabela 1 lista os atributos importantes do modelo BDC que são necessárias para fazer com que o estereótipo Subscribe funcionem.

Tabela 1. Atributos de modelo BDC

Notificações

No SharePoint, a infraestrutura de tratamento de eventos foi aprimorada para permitir que fontes de dados externas notifiquem o SharePoint quando as informações no sistema externo foram modificadas. Em seguida, quando o SharePoint recebe uma notificação, receptores de evento que estão associados a lista externa do SharePoint ou a entidade podem executar código para executar as ações especificadas.

Quando uma assinatura é criada, o sistema externo precisa de uma forma para informar ao SharePoint sobre as alterações que ocorreram em uma determinada entidade. O sistema externo é esperado para fornecer notificações para o endereço do destinatário, conforme fornecido pelo SharePoint para o sistema externo durante o processo de assinatura usando uma carga OData Atom formatada.

Figura 3 mostra o fluxo de comunicação entre o SharePoint e o sistema externo, quando um novo registro é adicionado aos dados no sistema externo.

Processo de notificação de Figura 3

1. Novo registro for adicionado ao sistema externo. Neste exemplo, um novo registro é adicionado para o sistema externo usando a interface de usuário do aplicativo ou diretamente no banco de dados.
2. Aplicativo de sistema externo é notificado da alteração. O aplicativo de sistema externo deve estar cientes das alterações que estão acontecendo aos dados subjacentes. Há várias maneiras de fazer isso. Você pode usar disparadores SQL que é acionado quando os dados forem alterados em tabelas específicas, ou você pode criar um mecanismo de pesquisa para consultar o repositório de dados para que as alterações. Existem outras maneiras para realizar essa tarefa, mas cada terá a ser avaliada com desempenho em mente.
3. Sistema externo envia a solicitação de notificação para o SharePoint por meio do endereço do destinatário. Para se comunicar as alterações, uma solicitação formatada Atom tem a serem enviados para o endereço do destinatário que é armazenado no repositório de inscrição do aplicativo LOB.

Carga de notificação

Construindo que a notificação, o sistema LOB tem para criar uma carga HTTP que inclui os detalhes completos do item que foi alterado ou simplesmente a identidade do item que foi alterado.

• Identidade: Quando a carga é enviada como uma identidade, espera-se que a carga têm apenas informações sobre a identidade do item alterado. Por exemplo, para um cliente em uma entidade de clientes, a carga apenas conteria a ID do cliente que foi alterada.
• Completa item: Nesse caso, a carga é um registro inteiro que foi alterado no sistema externo. O exemplo de cliente, o registro do cliente alterados inteira está incluído.

O tipo de carga que está sendo enviada pelo sistema externo deve ser indicado durante o processo de inscrição.

O exemplo a seguir é um exemplo da propriedade do modelo BDC usado para notificações.

<Property Name="NotificationParserType" Type="System.String">
   ODataEntryContentNotificationParser
</Property>

Se não for especificado, a carga de padrão é a carga de identidade.

Endereço de entrega de notificação (endereço virtual)

O processo de inscrição iniciado a partir de resultados do SharePoint em um endereço virtual está sendo criado pelo SharePoint, permitindo que um ponto de entrada para o sistema externo postar notificações. O endereço do destinatário é usado pelo sistema externo para postar das notificações. O endereço do destinatário também é passado para o sistema externo durante a solicitação de assinatura.

EventUnsubscriber: remover a inscrição da lista de notificações

A operação Unsubscribe remove uma assinatura da lista de notificações.

Figura 4 mostra que o método UnSubscribe é muito mais simples. Como a ID de assinatura foi enviada para o SharePoint e SharePoint registradas-lo, tudo o que é necessário é enviar a solicitação de cancelamento da assinatura com o ID de assinatura correto.

Figura 4 fluxo de código para o método de cancelamento da assinatura

Modelo BDC para o cancelamento da assinatura

O exemplo XML a seguir mostra como você pode criar um modelo BDC que cancela a inscrição de notificações de eventos do sistema externo.

<Method Name="UnSubscribeExpenseReport" DefaultDisplayName="ExpenseReport
    Unsubscribe">
    <Properties>
        <Property Name="ODataEntityUrl" Type="System.String">
            /Subscriptions(@ID)</Property>
        <Property Name="ODataHttpMethod" Type="System.String">DELETE</Property>
        <Property Name="ODataPayloadKind" Type="System.String">Property</Property>
        <Property Name="ODataServiceOperation" Type="System.Boolean">false</Property>
    </Properties>
    <AccessControlList>
        <AccessControlEntry Principal="NT Authority\\Authenticated Users">
            <Right BdcRight="Edit" />
            <Right BdcRight="Execute" />
            <Right BdcRight="SetPermissions" />
            <Right BdcRight="SelectableInClients" />
        </AccessControlEntry>
    </AccessControlList>
    <Parameters>
        <Parameter Name="@ID" Direction="In">
            <TypeDescriptor Name="ID" TypeName="System.Int32">
                <Properties>
                    <Property Name="SubscriptionIdName" Type="System.String">ID</Property>
                </Properties>
                <Interpretation>
                    <ConvertType LOBType="System.Int32" BDCType="System.String" />
                </Interpretation>
            </TypeDescriptor>
        </Parameter>
    </Parameters>
    <MethodInstances>
        <MethodInstance Name="UnSubscribeExpenseReport" DefaultDisplayName="ExpenseReport
             Unsubscribe" Type="EventUnsubscriber" Default="true">
            <AccessControlList>
                <AccessControlEntry Principal="NT Authority\\Authenticated Users">
                    <Right BdcRight="Edit" />
                    <Right BdcRight="Execute" />
                    <Right BdcRight="SetPermissions" />
                    <Right BdcRight="SelectableInClients" />
                </AccessControlEntry>
            </AccessControlList>
        </MethodInstance>
    </MethodInstances>
</Method>

<Method IsStatic="false" Name="Unsubscribe">
    <AccessControlList>
        <AccessControlEntry Principal="NT AUTHORITY\\Authenticated Users">
            <Right BdcRight="Edit" />
            <Right BdcRight="Execute" />
            <Right BdcRight="SetPermissions" />
            <Right BdcRight="SelectableInClients" />
        </AccessControlEntry>
    </AccessControlList>
    <Parameters>
        <Parameter Direction="In" Name="subscriptionId">
            <TypeDescriptor TypeName="System.String" Name="subscriptionId"
                IsSubscriptionId="true" />
         </Parameter>
    </Parameters>
    <MethodInstances>
        <MethodInstance Type="EventUnsubscriber" Default="true" Name="Unsubscribe"
            DefaultDisplayName="UnSubscriber">
            <Properties>
                <Property Name="LastDesignedOfficeItemType" Type="System.String">None</Property>
            </Properties>
            <AccessControlList>
                <AccessControlEntry Principal=" NT AUTHORITY\\Authenticated Users ">
                    <Right BdcRight="Edit" />
                    <Right BdcRight="Execute" />
                    <Right BdcRight="SetPermissions" />
                    <Right BdcRight="SelectableInClients" />
                </AccessControlEntry>
            </AccessControlList>
        </MethodInstance>
    </MethodInstances>
</Method>

Exemplo de código: anexar um receptor de evento em uma lista externa

O código a seguir fornece um exemplo de como anexar um receptor de evento em uma lista externa. Depois que ela está anexada, o receptor de evento escuta para notificações do sistema externo sobre atualizações, adições e exclusões são executadas nos dados nativos.

private static void AddEventReceiver(string siteUrl, string listTitle)
{
  string assembly = "SampleEventReceiver, Culture=neutral, Version=1.0.0.0,PublicKeyToken=1bfafa687d2e46a7";
  string className = "SampleEventReceiver.EntryContentEventReceiver";
  try
  {
    using (SPSite site = new SPSite(siteUrl))
    {
      using (SPWeb web = site.OpenWeb())
      {
        SPList list = web.Lists[listTitle];
        list.EventReceivers.Add(SPEventReceiverType.ItemAdded, assembly, className);
      }
    }
  }
  catch (Exception e)
  {
    Console.WriteLine(e);
  }
}

Além do básico: Saiba mais sobre como usar os receptores de evento externo

Para obter mais informações sobre eventos externos e alertas, consulte o seguinte:

Tabela 2. Conceitos avançados para trabalhar com receptores de eventos externos

Confira também

• O que há de novo no Serviços Corporativos de Conectividade do SharePoint
• Serviços Corporativos de Conectividade do SharePoint