Corresponder cadeias de caracteres em um item do Outlook como entidades conhecidas

  • Artigo

Antes de enviar um item de mensagem ou de solicitação de reunião, o Exchange Server analisa o conteúdo do item, identifica e apresenta determinadas cadeias de caracteres no assunto e no corpo semelhantes a entidades conhecidas do Exchange, como endereços de email, números de telefone e URLs. As mensagens e solicitações de reunião são fornecidas pelo Exchange Server em uma Caixa de Entrada do Outlook com entidades conhecidas carimbadas.

Importante

Os suplementos contextuais do Outlook baseados em entidade serão desativados no segundo trimestre de 2024. O trabalho para aposentar esse recurso começará em maio e continuará até o final de junho. Após junho, os suplementos contextuais não poderão mais detectar entidades em itens de email para executar tarefas neles. As APIs a seguir também serão retiradas.

Para ajudar a minimizar possíveis interrupções, o seguinte ainda será suportado depois que os suplementos contextuais baseados em entidade forem retirados.

  • Uma implementação alternativa do botão Ingressar Reunião , que é ativado por suplementos de reunião online, está sendo desenvolvida. Depois que o suporte para suplementos contextuais baseados em entidade terminar, os suplementos de reunião online farão a transição automática para a implementação alternativa para ativar o botão Ingressar Reunião .
  • As regras de expressão regular continuarão a ser suportadas depois que os suplementos contextuais baseados em entidade forem retirados. Recomendamos atualizar seu suplemento contextual para usar regras de expressão regulares como uma solução alternativa. Para obter diretrizes sobre como implementar essas regras, consulte Usar regras regulares de ativação de expressão para mostrar um suplemento do Outlook.

Para obter mais informações, consulte Aposentadoria de suplementos contextuais do Outlook baseados em entidade.

Usando a API JavaScript do Office, você pode obter essas cadeias de caracteres que correspondem a entidades conhecidas específicas para processamento adicional. Também pode especificar uma entidade conhecida em uma regra no manifesto do suplemento, para que o Outlook possa ativar o suplemento quando o usuário estiver exibindo um item que contém correspondências para essa entidade. Em seguida, é possível extrair e agir em relação às correspondências da entidade.

Observação

Recursos de suplemento do Outlook que dependem de regras de ativação não têm suporte quando o suplemento usa um manifesto unificado para o Microsoft 365 (versão prévia).

Convém ser capaz de identificar ou extrair tais instâncias de uma mensagem ou compromisso selecionado. Por exemplo, você pode compilar um serviço de pesquisa invertida de telefones como um suplemento do Outlook. O suplemento pode extrair cadeias de caracteres no corpo ou assunto do item que se parecem com um número de telefone, fazer uma pesquisa invertida e exibir o proprietário registrado de cada número de telefone.

Este tópico apresenta essas entidades conhecidas, mostra exemplos de regras de ativação baseadas em entidades conhecidas e como extrair correspondências de entidade independentemente de ter usado entidades em regras de ativação.

Suporte para entidades conhecidas

O Exchange Server carimba entidades conhecidas em um item de mensagem ou de solicitação de reunião depois que o remetente envia o item e antes de o Exchange entregar o item ao destinatário. Portanto, somente os itens que passaram pelo transporte do Exchange são carimbados, e o Outlook pode ativar suplementos com base nesses carimbos quando o usuário está exibindo esses itens. Do contrário, quando o usuário está redigindo ou visualizando um item que está na pasta Itens Enviados, como o item não passou por transporte, o Outlook não pode ativar suplementos com base em entidades conhecidas.

Da mesma forma, você não pode extrair entidades conhecidas em itens que estão sendo redigidos ou estão na pasta Itens Enviados, já que esses itens não passaram pelo transporte e não foram carimbados. Para saber mais sobre os tipos de itens que dão suporte à ativação, confira Regras de ativação para suplementos do Outlook.

A tabela a seguir lista as entidades que têm suporte e são reconhecidas pelo Exchange Server e pelo Outlook (por isso chamadas "entidades conhecidas") e o tipo de objeto de uma instância de cada entidade. O reconhecimento de linguagem natural de uma cadeia de caracteres como uma dessas entidades baseia-se em um modelo de aprendizagem que foi treinado com grande quantidade de dados. Portanto, o reconhecimento é não determinístico. Confira Dicas para usar entidades conhecidas a fim de saber mais sobre condições de reconhecimento.

Tipo de entidade Condições de reconhecimento Tipo de objeto
Endereço Estados Unidos endereços de rua. Por exemplo, "1234 Main Street, Redmond, WA 07722". Geralmente, para que um endereço seja reconhecido, ele deve seguir a estrutura de um endereço postal Estados Unidos, com a maioria dos elementos de um número de rua, nome da rua, cidade, estado e CEP presentes. O endereço pode ser especificado em uma ou várias linhas. Objeto JavaScript String
Contato Uma referência às informações de uma pessoa assim reconhecida em sua língua materna. O reconhecimento de um contato depende do contexto. Por exemplo, uma assinatura no final de uma mensagem ou o nome da pessoa que aparece perto de algumas das seguintes informações: número de telefone, endereço, endereço de e-mail e URL. Objeto Contact
EmailAddress Endereços de email SMTP. Objeto JavaScript String
MeetingSuggestion Uma referência a uma reunião ou a um evento. Por exemplo, o Exchange reconheceria o seguinte texto como uma sugestão de reunião: "Vamos nos reunir amanhã para almoçar". Objeto MeetingSuggestion
PhoneNumber Estados Unidos números de telefone. Por exemplo, (235) 555-0110. Objeto PhoneNumber
TaskSuggestion Frases acionáveis em um email. Por exemplo, "Atualize a planilha". Objeto TaskSuggestion
Url Um endereço Web que especifica explicitamente o local de rede e o identificador de um recurso da Web. Exchange Server não requer o protocolo de acesso no endereço Web e não reconhece URLs inseridas no texto do link como instâncias da Url entidade. Exchange Server pode corresponder aos seguintes exemplos:www.youtube.com/user/officevideoshttps://www.youtube.com/user/officevideos Objeto JavaScript String

A figura a seguir descreve como Exchange Server e o Outlook dão suporte a entidades conhecidas para suplementos e o que os suplementos podem fazer com entidades conhecidas. Confira Recuperar entidades em seu suplemento e Ativar um suplemento com base na existência de uma entidade para obter mais detalhes sobre como usar essas entidades.

Suporte e uso de entidades conhecidas em um suplemento do Outlook.

Permissões para extrair entidades

Para extrair entidades no seu código JavaScript ou fazer com que seu suplemento seja ativado com base na existência de determinadas entidades conhecidas, verifique se você solicitou as permissões apropriadas no manifesto do suplemento.

Especificar a permissão restrita padrão permite que seu suplemento extraia a Addressentidade , MeetingSuggestionou TaskSuggestion . Para extrair qualquer uma das outras entidades, especifique item de leitura, item de leitura/gravação ou permissão de caixa de correio de leitura/gravação no manifesto.

O exemplo a seguir solicita a permissão do item de leitura no manifesto.

<Permissions>ReadItem</Permissions>

Para saber mais sobre as permissões de suplemento do Outlook, confira Noções básicas sobre as permissões de suplemento do Outlook.

Recuperar entidades no seu suplemento

Enquanto o assunto ou o corpo do item que está sendo exibido pelo usuário contiver cadeias de caracteres que o Exchange e o Outlook podem reconhecer como entidades conhecidas, essas instâncias estão disponíveis para suplementos. Eles estão disponíveis mesmo que um suplemento não seja ativado com base em entidades conhecidas. Com a permissão apropriada, você pode usar o getEntities método ou getEntitiesByType para recuperar entidades conhecidas que estão presentes na mensagem ou compromisso atual.

O getEntities método retorna uma matriz de objetos Entities que contém todas as entidades conhecidas no item.

Se você estiver interessado em um tipo específico de entidades, use o getEntitiesByTypemétodo que retorna uma matriz de apenas as entidades desejadas. A enumeração EntityType representa todos os tipos de entidades conhecidas que você pode extrair.

Depois de chamar getEntities, você pode usar a propriedade correspondente do Entities objeto para obter uma matriz de instâncias de um tipo de entidade. Dependendo do tipo de entidade, as instâncias na matriz podem ser apenas cadeias de caracteres ou podem mapear para objetos específicos.

Como o exemplo mostrado na figura anterior, acesse a matriz retornada por getEntities().addresses[] para obter endereços no item. A Entities.addresses propriedade retorna uma matriz de cadeias de caracteres que o Outlook reconhece como endereços postais. Da mesma forma, a propriedade retorna uma matriz de Contact objetos que o Entities.contacts Outlook reconhece como informações de contato. A Tabela 1 lista o tipo de objeto de uma instância de cada entidade compatível.

O exemplo a seguir mostra como recuperar endereços encontrados em uma mensagem.

// Get the address entities from the item.
const entities = Office.context.mailbox.item.getEntities();
// Check to make sure that address entities are present.
if (null != entities && null != entities.addresses && undefined != entities.addresses) {
   //Addresses are present, so use them here.
}

Ativar um suplemento com base na existência de uma entidade

Outra maneira de usar entidades conhecidas é fazer com que o Outlook ative o suplemento baseado na existência de um ou mais tipos de entidades no assunto ou no corpo do item exibido no momento. Você pode fazer isso especificando uma ItemHasKnownEntity regra no manifesto de suplemento. O tipo simples EntityType representa os diferentes tipos de entidades conhecidas com suporte por ItemHasKnownEntity regras. Depois de ativar o suplemento, também é possível recuperar as instâncias de tais entidades para seus propósitos, como descrito na seção anterior, Recuperar entidades no seu suplemento.

Opcionalmente, você pode aplicar uma expressão regular em uma ItemHasKnownEntity regra, de modo a filtrar mais instâncias de uma entidade e fazer com que o Outlook ative um suplemento apenas em um subconjunto das instâncias da entidade. Por exemplo, você pode especificar um filtro para a entidade de rua do endereço em uma mensagem que contenha um CEP do Rio de Janeiro que comece com "021". Para aplicar um filtro nas instâncias de entidade, use os RegExFilter atributos e FilterName no Rule elemento do tipo ItemHasKnownEntity .

De forma semelhante às outras regras de ativação, você pode especificar várias regras a fim de formar uma coleção de regras para seu suplemento. O exemplo a seguir aplica uma operação "AND" em duas regras: uma ItemIs regra e uma ItemHasKnownEntity regra. Essa coleção de regras ativa o suplemento sempre que o item atual for uma mensagem e o Outlook reconhecer um endereço no assunto ou no corpo do item.

<Rule xsi:type="RuleCollection" Mode="And">
   <Rule xsi:type="ItemIs" ItemType="Message" />
   <Rule xsi:type="ItemHasKnownEntity" EntityType="Address" />
</Rule>

O exemplo a seguir usa getEntitiesByType o item atual para definir uma variável addresses para os resultados da coleção de regras anterior.

const addresses = Office.context.mailbox.item.getEntitiesByType(Office.MailboxEnums.EntityType.Address);

O exemplo de regra a seguir ItemHasKnownEntity ativa o suplemento sempre que houver uma URL no assunto ou no corpo do item atual e a URL contém a cadeia de caracteres "youtube", independentemente do caso da cadeia de caracteres.

<Rule xsi:type="ItemHasKnownEntity" 
    EntityType="Url" 
    RegExFilter="youtube"
    FilterName="youtube"
    IgnoreCase="true"/>

O exemplo a seguir usa getFilteredEntitiesByName(name) o item atual para definir uma variável videos para obter uma matriz de resultados que correspondam à expressão regular na regra anterior ItemHasKnownEntity .

const videos = Office.context.mailbox.item.getFilteredEntitiesByName(youtube);

Dicas para usar entidades conhecidas

Existem alguns fatos e limites de que você deve estar ciente ao usar entidades conhecidas no seu suplemento. O seguinte se aplica desde que seu suplemento seja ativado quando o usuário estiver lendo um item que contém correspondências de entidades conhecidas, independentemente de você usar uma ItemHasKnownEntity regra.

  • Você somente pode extrair cadeias de caracteres que sejam entidades conhecidas se elas estiverem em inglês.

  • Você pode extrair entidades conhecidas dos primeiros dois mil caracteres no corpo do item, mas não além disso. Esse limite de tamanho ajuda a equilibrar a necessidade de funcionalidade e desempenho, para que Exchange Server e o Outlook não fiquem atolados analisando e identificando instâncias de entidades conhecidas em mensagens grandes e compromissos. Observe que esse limite é independente de o suplemento especificar uma ItemHasKnownEntity regra. Se o suplemento usar tal regra, observe também o limite de processamento de regra para o Outlook no Windows e no Mac mais adiante nesta seção.

  • Você pode extrair entidades de compromissos que sejam reuniões organizadas por alguém que não seja o proprietário da caixa de correio. Você não pode extrair entidades de itens de calendário que não são reuniões ou reuniões organizadas pelo proprietário da caixa de correio.

  • Você pode extrair entidades do MeetingSuggestion tipo apenas de mensagens, mas não de compromissos.

  • Você pode extrair URLs que existem explicitamente no corpo do item, mas não URLs que estão inseridas no texto de hiperlink no corpo do item HTML. Considere usar uma ItemHasRegularExpressionMatch regra para obter URLs explícitas e inseridas. Especifique como PropertyName e uma expressão regular que corresponda BodyAsHTML às URLs como RegExValue.

  • Você não pode extrair entidades de itens na pasta Itens Enviados .

Além disso, o seguinte se aplica se você usar uma regra ItemHasKnownEntity e pode afetar os cenários em que, de outra forma, você esperaria que seu suplemento fosse ativado.

  • Ao usar a regra, espere que o ItemHasKnownEntity Outlook corresponda às cadeias de caracteres de entidade somente em inglês, independentemente da localidade padrão especificada no manifesto.

  • Quando o suplemento estiver em execução no Outlook no Windows ou no Mac, espere que o Outlook aplique a ItemHasKnownEntity regra ao primeiro megabyte do corpo do item e não ao restante do corpo acima desse limite.

  • Você não pode usar uma ItemHasKnownEntity regra para ativar um suplemento para itens na pasta Itens Enviados .

Confira também