Chamar serviços Web de um suplemento do Outlook

Artigo
06/12/2024

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

Importante

Os tokens de identidade de utilizador e tokens de chamada de retorno legados do Exchange serão desativados para todos os inquilinos do Exchange Online em outubro de 2024, como parte da Iniciativa Secure Future da Microsoft, que dá às organizações as ferramentas necessárias para responder ao atual cenário de ameaças. 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. Para obter mais informações, veja a nossa publicação de blogue sobre a autenticação de aplicações aninhadas e os tokens do Exchange legados.

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 você não fornecer um proxy, erros de script 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.

Você pode usar o método mailbox.makeEwsRequestAsync para fazer uma solicitação dos EWS ao servidor Exchange que hospeda a caixa de correio do usuário.

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 termina, você recebe uma resposta SOAP XML que contém dados que são relevantes para a operação. As solicitações e respostas SOAP dos EWS seguem o esquema definido no arquivo Messages.xsd. Como outros arquivos de esquema dos EWS, o arquivo Message.xsd está localizado no diretório virtual do IIS que hospeda os 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 informações relevantes e processa essas informações 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 getElementsByTagNameDOM , para incluir suporte para o 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, function(result) {
     const response = $.parseXML(result.value);
     const extendedProps = response.getElementsByTagName("ExtendedProperty")
});

Para o webview 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, function(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, como innerHTML , 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 .

No XML, substitua as IDs de item e atributos relevantes da operação dos EWS por valores apropriados.
Inclua o pedido SOAP como um argumento para o parâmetro de dados de makeEwsRequestAsync.
Especifique uma função de chamada de retorno e chame makeEwsRequestAsync.
Na função de chamada de retorno, verifique os resultados da operação na resposta SOAP.
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

Não é possível atualizar (ou criar) itens FAI (Informações Associadas da Pasta) usando 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 XML: 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

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

Partilhar via