Usar os Serviços Web do Exchange a partir de um suplemento do Outlook

O seu suplemento do Outlook pode utilizar os Serviços Web exchange (EWS) a partir de um ambiente que executa Exchange Server (no local). O EWS é um serviço Web que está disponível no servidor que fornece a localização de origem para a IU do suplemento. Este artigo fornece um exemplo que mostra como um suplemento do Outlook pode solicitar informações dos EWS.

Importante

Os tokens legados do Exchange foram preteridos. A partir de fevereiro de 2025, vamos começar a desativar a identidade de utilizador e os tokens de chamada de retorno legados do Exchange para Exchange Online inquilinos. Para obter os detalhes e linha do tempo, consulte a nossa página de FAQ. Isto faz parte da Iniciativa Secure Future da Microsoft, que fornece às organizações as ferramentas necessárias para responder ao cenário de ameaças atual. Os tokens de identidade de utilizador do Exchange continuarão a funcionar para o Exchange no local. A autenticação de aplicações aninhadas é a abordagem recomendada para tokens em curso.

A forma como chama um serviço Web varia consoante a localização do serviço Web. As tabelas seguintes listam as diferentes formas de chamar um serviço Web com base na localização.

Local do serviço Web	Maneira de chamar o serviço Web
O servidor Exchange que hospeda a caixa de correio do cliente	Use o método mailbox.makeEwsRequestAsync para chamar operações EWS com suporte dos suplementos. O servidor Exchange que hospeda a caixa de correio também expõe os EWS.
O servidor Web que fornece o local de origem para a interface do usuário	Chame o serviço Web usando técnicas JavaScript padrão. O código JavaScript no quadro da interface do usuário é executado no contexto do servidor Web que fornece a interface do usuário. Portanto, ele pode chamar serviços Web nesse servidor sem causar um erro de script entre sites.
Todos os outros locais	Crie um proxy para o serviço Web no servidor Web que fornece o local de origem para a interface do usuário. Se não fornecer um proxy, os erros de scripting entre sites impedirão a execução do suplemento. Uma maneira de fornecer um proxy é usar JSON/P. Para saber mais, confira Privacidade e segurança para suplementos do Office.

Usar o método makeEwsRequestAsync para acessar operações dos EWS

Importante

As chamadas e operações EWS não são suportadas em suplementos em execução no Outlook para Android e no iOS.

Pode utilizar o método mailbox.makeEwsRequestAsync para fazer um pedido EWS ao servidor Exchange no local que aloja a caixa de correio do utilizador.

Os EWS oferecem suporte a diferentes operações em um servidor Exchange, por exemplo, operações no nível do item para copiar, localizar, atualizar ou enviar um item e operações no nível da pasta para criar, acessar ou atualizar uma pasta. Para executar uma operação EWS, crie um pedido SOAP XML para essa operação. Quando a operação for concluída, obtém uma resposta SOAP XML que contém dados relevantes para a operação. Os pedidos e respostas SOAP do EWS seguem o esquema definido no ficheiro Messages.xsd . Tal como outros ficheiros de esquema EWS, o ficheiro Message.xsd está localizado no diretório virtual do IIS que aloja o EWS.

Para utilizar o makeEwsRequestAsync método para iniciar uma operação EWS, forneça o seguinte:

• O XML para o pedido SOAP para essa operação EWS como um argumento para o parâmetro de dados .

• Uma função de chamada de retorno (como o argumento de chamada de retorno ).

• Quaisquer dados de entrada opcionais para essa função de chamada de retorno (como o argumento userContext ).

Quando o pedido SOAP do EWS estiver concluído, o Outlook chama a função de chamada de retorno com um argumento, que é um objeto AsyncResult . A função de chamada de retorno pode aceder a duas propriedades do AsyncResult objeto: a value propriedade, que contém a resposta SOAP XML da operação EWS e, opcionalmente, a asyncContext propriedade, que contém quaisquer dados transmitidos como o userContext parâmetro . Normalmente, a função de chamada de retorno analisa o XML na resposta SOAP para obter quaisquer informações e processos relevantes dessa informação em conformidade.

Dicas para analisar respostas dos EWS

Ao analisar uma resposta SOAP de uma operação EWS, tenha em atenção os seguintes problemas dependentes do browser.

• Especifique o prefixo de um nome de etiqueta ao utilizar o método getElementsByTagName DOM para incluir suporte para a Internet Explorer e o Trident Webview.

  getElementsByTagName tem um comportamento diferente consoante o tipo de browser. Por exemplo, uma resposta EWS pode conter o seguinte XML (formatado e abreviado para fins de apresentação).

  <t:ExtendedProperty><t:ExtendedFieldURI PropertySetId="00000000-0000-0000-0000-000000000000" 
  PropertyName="MyProperty" 
  PropertyType="String"/>
  <t:Value>{
  ...
  }</t:Value></t:ExtendedProperty>
  

  O código, tal como no seguinte, funcionaria num browser como o Chrome para colocar o XML entre as ExtendedProperty etiquetas.

  const mailbox = Office.context.mailbox;
  mailbox.makeEwsRequestAsync(mailbox.item.itemId, (result) => {
       const response = $.parseXML(result.value);
       const extendedProps = response.getElementsByTagName("ExtendedProperty")
  });
  

  Para a vista Web Trident (Internet Explorer), tem de incluir o t: prefixo do nome da etiqueta, da seguinte forma.

  const mailbox = Office.context.mailbox;
  mailbox.makeEwsRequestAsync(mailbox.item.itemId, (result) => {
       const response = $.parseXML(result.value);
       const extendedProps = response.getElementsByTagName("t:ExtendedProperty")
  });
  

• Utilize a propriedade textContent DOM para obter o conteúdo de uma etiqueta numa resposta EWS, da seguinte forma.

  content = $.parseJSON(value.textContent);
  

  Outras propriedades, comoinnerHTML, por exemplo, podem não funcionar na vista Web Trident (Internet Explorer) para algumas etiquetas numa resposta EWS.

Exemplo

O exemplo seguinte chama makeEwsRequestAsync para utilizar a operação GetItem para obter o assunto de um item. Este exemplo inclui as três funções seguintes.

• getSubjectRequest – Utiliza um ID de item como entrada e devolve o XML para o pedido SOAP chamar GetItem para o item especificado.

• sendRequest – Chama getSubjectRequest para obter o pedido SOAP para o item selecionado e, em seguida, transmite o pedido SOAP e a função de chamada de retorno, callback, para makeEwsRequestAsync obter o assunto do item especificado.

• callback – Processa a resposta SOAP, que inclui qualquer assunto e outras informações sobre o item especificado.

function getSubjectRequest(id) {
   // Return a GetItem operation request for the subject of the specified item. 
   const result = 
    '<?xml version="1.0" encoding="utf-8"?>' +
    '<soap:Envelope xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"' +
    '               xmlns:xsd="https://www.w3.org/2001/XMLSchema"' +
    '               xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"' +
    '               xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">' +
    '  <soap:Header>' +
    '    <RequestServerVersion Version="Exchange2013" xmlns="http://schemas.microsoft.com/exchange/services/2006/types" soap:mustUnderstand="0" />' +
    '  </soap:Header>' +
    '  <soap:Body>' +
    '    <GetItem xmlns="http://schemas.microsoft.com/exchange/services/2006/messages">' +
    '      <ItemShape>' +
    '        <t:BaseShape>IdOnly</t:BaseShape>' +
    '        <t:AdditionalProperties>' +
    '            <t:FieldURI FieldURI="item:Subject"/>' +
    '        </t:AdditionalProperties>' +
    '      </ItemShape>' +
    '      <ItemIds><t:ItemId Id="' + id + '"/></ItemIds>' +
    '    </GetItem>' +
    '  </soap:Body>' +
    '</soap:Envelope>';

   return result;
}

function sendRequest() {
   // Create a local variable that contains the mailbox.
   const mailbox = Office.context.mailbox;

   mailbox.makeEwsRequestAsync(getSubjectRequest(mailbox.item.itemId), callback);
}

function callback(asyncResult)  {
   const result = asyncResult.value;
   const context = asyncResult.context;

   // Process the returned response here.
}

Operações dos EWS compatíveis com suplementos

Os suplementos do Outlook podem aceder a um subconjunto de operações que estão disponíveis no EWS através do makeEwsRequestAsync método . Se não estiver familiarizado com as operações do EWS e como utilizar o makeEwsRequestAsync método para aceder a uma operação, comece com um exemplo de pedido SOAP para personalizar o argumento de dados .

O seguinte descreve como pode utilizar o makeEwsRequestAsync método .

1. No XML, substitua as IDs de item e atributos relevantes da operação dos EWS por valores apropriados.

2. Inclua o pedido SOAP como um argumento para o parâmetro de dados de makeEwsRequestAsync.

3. Especifique uma função de chamada de retorno e chame makeEwsRequestAsync.

4. Na função de chamada de retorno, verifique os resultados da operação na resposta SOAP.

5. Use os resultados da operação dos EWS de acordo com as suas necessidades.

A tabela a seguir lista as operações dos EWS compatíveis com suplementos. Para ver exemplos de solicitações e respostas SOAP, escolha o link para cada operação. Para saber mais sobre operações dos EWS, confira Operações dos EWS no Exchange.

Operação do EWS	Descrição
Operação CopyItem	Copia os itens especificados e coloca os novos itens em uma pasta designada no repositório do Exchange.
Operação CreateFolder	Cria pastas no local especificado no repositório do Exchange.
Operação CreateItem	Cria os itens especificados no repositório do Exchange.
Operação ExpandDL	Exibe a associação completa das listas de distribuição.
Operação FindConversation	Enumera uma lista de conversas na pasta especificada no repositório do Exchange.
Operação FindFolder	Localiza subpastas de uma pasta identificada e retorna um conjunto de propriedades que descreve o conjunto de subpastas.
Operação FindItem	Identifica os itens que estão localizados em uma pasta especificada no repositório do Exchange.
Operação GetConversationItems	Obtém um ou mais conjuntos de itens que estão organizados em nós em uma conversa.
Operação GetFolder	Obtém as propriedades especificadas e o conteúdo de pastas do repositório do Exchange.
Operação GetItem	Obtém as propriedades especificadas e o conteúdo de itens do repositório do Exchange.
Operação GetUserAvailability	Fornece informações detalhadas sobre a disponibilidade de um conjunto de usuários, salas e recursos em um período especificado.
Operação MarkAsJunk	Move mensagens de email para a pasta Lixo Eletrônico e adiciona ou remove, adequadamente, remetentes das mensagens na lista de remetentes bloqueados.
Operação MoveItem	Move itens para uma única pasta de destino no repositório do Exchange.
Operação ResolveNames	Resolve endereços de email e nomes de exibição ambíguos.
Operação SendItem	Envia mensagens de email que estão localizadas no repositório do Exchange.
Operação UpdateFolder	Modifica as propriedades de pastas existentes no repositório do Exchange.
Operação UpdateItem	Modifica as propriedades de itens existentes no repositório do Exchange.

Observação

Os itens FAI (Informação Associada à Pasta) não podem ser atualizados (ou criados) a partir de um suplemento. Essas mensagens ocultas são armazenadas em uma pasta e usadas para armazenar diversas configurações e dados auxiliares. Tentar usar a operação UpdateItem gera um erro ErrorAccessDenied: "A extensão do Office não tem permissão para atualizar esse item". Se preferir, use a API Gerenciada do EWS para atualizar esses itens usando um cliente do Windows ou um aplicativo para servidores. Recomenda-se cuidado já que as estruturas de dados internos de tipo de serviço estão sujeitas a alterações e podem invalidar sua solução.

Considerações sobre autenticação e permissão para makeEwsRequestAsync

Quando utiliza o makeEwsRequestAsync método , o pedido é autenticado com as credenciais da conta de e-mail do utilizador atual. O makeEwsRequestAsync método gere as credenciais para que não tenha de fornecer credenciais de autenticação com o seu pedido.

Observação

O administrador do servidor tem de utilizar o cmdlet New-WebServicesVirtualDirectory ou Set-WebServicesVirtualDirectory para definir o parâmetro trueOAuthAuthentication como no diretório EWS do servidor de Acesso de Cliente para ativar o makeEwsRequestAsync método para fazer pedidos EWS.

Para utilizar o makeEwsRequestAsync método , o suplemento tem de pedir a permissão de caixa de correio de leitura/escrita no manifesto. A marcação varia consoante o tipo de manifesto.

• Manifesto apenas de suplemento: defina o <elemento Permissões> como ReadWriteMailbox.
• Manifesto unificado para o Microsoft 365: defina a propriedade "name" de um objeto na matriz "authorization.permissions.resourceSpecific" como "Mailbox.ReadWrite.User".

Para obter informações sobre como utilizar a permissão de caixa de correio de leitura/escrita , consulte permissão de caixa de correio de leitura/escrita.

Confira também

• Privacidade e segurança para Suplementos do Office
• Como lidar com limitações de política de mesma origem nos Suplementos do Office
• Referência do EWS para Exchange
• Aplicativos de email para Outlook e EWS no Exchange

Veja o seguinte para criar serviços de back-end para suplementos com ASP.NET Web API.

• Criar um serviço Web para um suplemento do Office usando a API Web ASP.NET
• Noções básicas sobre a criação de um serviço HTTP usando a API Web ASP.NET