Chamar serviços Web de um suplemento do Outlook

Artigo
05/20/2023

Seu suplemento pode usar o EWS (Exchange Web Services) de um computador que está executando Exchange Server, um serviço Web disponível no servidor que fornece o local de origem para a interface do usuário 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

Não há suporte para chamadas e operações do EWS em suplementos em execução no Outlook no iOS e Android.

A maneira como você chama um serviço Web varia de acordo com a localização do serviço Web. As tabelas a seguir listam as diferentes maneiras pelas quais você pode chamar um serviço Web com base no local.

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

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 uma solicitação 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 usar o makeEwsRequestAsync método para iniciar uma operação EWS, forneça o seguinte:

O XML para a solicitação SOAP para essa operação EWS, como um argumento para o parâmetro de dados
Uma função de retorno de chamada (como o argumento de retorno de chamada )
Quaisquer dados de entrada opcionais para essa função de retorno de chamada (como o argumento userContext )

Quando a solicitação SOAP do EWS é concluída, o Outlook chama a função de retorno de chamada com um argumento, que é um objeto AsyncResult . A função de retorno de chamada pode acessar duas propriedades do AsyncResult objeto: a value propriedade, que contém a resposta SOAP XML da operação EWS e, opcionalmente, a propriedade, que contém todos os asyncContext dados passados como o userContext parâmetro. Normalmente, a função de retorno de chamada analisa o XML na resposta SOAP para obter qualquer informação relevante e processa essas informações de acordo.

Dicas para analisar respostas dos EWS

Ao analisar uma resposta SOAP de uma operação EWS, observe os seguintes problemas dependentes do navegador.

Especifique o prefixo para um nome de marca ao usar o método getElementsByTagNameDOM , para incluir o suporte para o Explorer da Internet e a visão web do Trident.

getElementsByTagName se comporta de forma diferente dependendo do tipo de navegador. Por exemplo, uma resposta EWS pode conter o XML a seguir (formatado e abreviado para fins de exibição).

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

O código, como no seguinte, funcionaria em um navegador como o Chrome para obter o XML fechado pelas ExtendedProperty marcas.

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

Para a visão web do Trident (Internet Explorer), você deve incluir o t: prefixo do nome da marca, da seguinte maneira.

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

Use a propriedade textContent DOM para obter o conteúdo de uma marca em uma resposta EWS, da seguinte maneira.
```
content = $.parseJSON(value.textContent);
```
Outras propriedades, como innerHTML pode não funcionar na webview do Trident (Internet Explorer) para algumas marcas em uma resposta EWS.

Exemplo

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

getSubjectRequest – usa uma ID do item como entrada e retorna o XML para a solicitação SOAP para chamar GetItem o item especificado.
sendRequest – Chama getSubjectRequest para obter a solicitação SOAP para o item selecionado e, em seguida, passa a solicitação SOAP e a função de retorno de chamada, callbackpara 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 acessar um subconjunto de operações que estão disponíveis no EWS por meio do makeEwsRequestAsync método. Se você não estiver familiarizado com as operações EWS e como usar o makeEwsRequestAsync método para acessar uma operação, comece com um exemplo de solicitação SOAP para personalizar seu argumento de dados .

O seguinte descreve como você pode usar o makeEwsRequestAsync método.

No XML, substitua as IDs de item e atributos relevantes da operação dos EWS por valores apropriados.
Inclua a solicitação SOAP como um argumento para o parâmetro de dados de makeEwsRequestAsync.
Especifique uma função de retorno de chamada e chame makeEwsRequestAsync.
Na função de retorno de chamada, 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 você usa o makeEwsRequestAsync método, a solicitação é autenticada usando as credenciais da conta de email do usuário atual. O makeEwsRequestAsync método gerencia as credenciais para você para que você não precise fornecer credenciais de autenticação com sua solicitação.

Observação

O administrador do servidor deve usar o cmdlet New-WebServicesVirtualDirectory ou set-WebServicesVirtualDirectory para definir o parâmetro OAuthAuthentication no true diretório EWS do servidor de acesso ao cliente para habilitar o makeEwsRequestAsync método para fazer solicitações EWS.

Para usar o método, o makeEwsRequestAsync suplemento deve solicitar a permissão de caixa de correio de leitura/gravação no manifesto. A marcação varia dependendo do tipo de manifesto.

Manifesto XML: defina o <elemento Permissions> como ReadWriteMailbox.
Manifesto unificado para o Microsoft 365 (versão prévia): defina a propriedade "name" de um objeto na matriz "authorization.permissions.resourceSpecific" como "Mailbox.ReadWrite.User".

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

Confira também

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