Ativar a experiência de administrador simplificada para o conector do Microsoft Graph

Artigo
11/07/2024

Este artigo descreve como ativar a experiência de administração simplificada para o seu conector do Microsoft Graph no centro de administração do Teams. Quando ativa esta experiência, os administradores do Teams podem ativar ou desativar o conector personalizado do Microsoft Graph de forma totalmente integrada no centro de administração do Teams.

Experiência de administrador simplificada no centro de administração do Teams

Para ativar a experiência de administrador simplificada no centro de administração do Teams:

Atualize o manifesto da aplicação Teams.
Atualizar as permissões do Microsoft Graph.
Processe as notificações do webhook do Microsoft Graph.
Criar ou eliminar ligações do Microsoft Graph.
Valide a experiência ao ativar o Conector do Microsoft Graph no centro de administração do Teams.

Atualizar o manifesto da aplicação Teams

No manifesto da aplicação Teams, na raiz, no mesmo nível que propriedades como nome, descrição e ícones, adicione a propriedade graphConnector (introduzida na v1.11 do manifesto da aplicação) com um notificationUrl. Este campo contém o URL para o qual são enviadas notificações do conector do Microsoft Graph para a aplicação. A versão do manifesto da aplicação tem de ser v1.13 ou superior para que a experiência de administração simplificada funcione.

Certifique-se de que a propriedade webApplicationInfo é adicionada ao manifesto. Depois de atualizar o manifesto, carregue-o ao fazer sideload da aplicação ou ao publicar a aplicação na loja.

{
 "$schema":"https://developer.microsoft.com/json-schemas/teams/v1.13/MicrosoftTeams.schema.json",
  "manifestVersion": "1.13",
  ...
  "webApplicationInfo": {
    "id": "<AAD_APP_ID>",  // e.g. "7e47846e-4bef-4c42-9817-a14e92287f28"
    "resource": "<AAD_APP_RESOURCE>" // e.g. "api://xmngc.loca.lt/7e47846e-4bef-4c42-9817-a14e92287f28"

  },
  "graphConnector": {
    "notificationUrl": "<AAD_APP_NOTIFICATION_URL>"
  }
}

Atualizar permissões do Microsoft Graph

Aceda a centro de administração do Microsoft Entra.
Expanda o menu Identidade e aceda a Aplicações>Registros de aplicativo.
Selecione o registo da sua aplicação.
Aceda a Permissões> de APIAdicionar uma permissão>do Microsoft Graph.
Selecione as permissões e ExternalItem.ReadWrite.OwnedBy do ExternalConnection.ReadWrite.OwnedBy Microsoft Graph, conforme mostrado no exemplo seguinte.

Permissões atualizadas do Microsoft Graph

Processar notificações de webhook do Microsoft Graph

Quando o administrador ativa oudesativa o conector do Microsoft Graph a partir do centro de administração do Teams, o Microsoft Graph envia uma notificação de alteração para o URL especificado na propriedade notificationUrl no manifesto. A sua aplicação tem de gerir estas ligações do Microsoft Graph em conformidade.

Notificações de alteração

Para obter mais informações sobre como configurar notificações de alteração, veja Configurar notificações para alterações nos dados de recursos. O exemplo seguinte mostra um payload:

{
  "validationTokens": [
    "[jwt validation token]"
  ],
  "value": [
    {
      "changeType": "updated",
      "clientState": null,
      "resource": "external",
      "resourceData": {
        "@odata.id": "external",
        "id": "[graph connector id]",
        "state": "enabled", // or disabled
        "connectorsTicket": "[An opaque encoded string]",
        "@odata.type": "#Microsoft.Graph.connector"
      },
      "subscriptionExpirationDateTime": "2024-08-30T13:01:48.3441108-07:00",
      "subscriptionId": "[change notification's subscription id]",
      "tenantId": "[customer's tenant id]"
    }
  ]
}

Para compreender como validar a notificação de alteração de entrada, veja Validar a autenticidade das notificações.

Lembre-se das seguintes dicas:

Pode ignorar subscriptionExpirationDateTime e subscriptionId.
A notificação de alteração destina-se à gestão do conector do Microsoft Graph apenas quando o @odata.type dos dados do recurso corresponde ao do payload de exemplo.
O tenantId identificado é o ID de inquilino do cliente. Quando chama o Microsoft API do Graph para gerir as ligações do Microsoft Graph, tem de gerar o token de aplicação em nome do ID de inquilino deste cliente.
Pode chamar o microsoft API do Graph para obter o nome a apresentar do cliente e o nome de domínio predefinido. Estas informações podem ajudá-lo a mapear o tenantId para o identificador exclusivo no seu sistema. Para saber mais, veja Localizar informações de inquilino por ID de inquilino.
No resourceData, utilize o estado para determinar se pretende criar ou eliminar ligações. Precisa dos conectoresTicket para criar as ligações.

Processar a notificação de "ativação do conector"

Para processar as notificações de "ativação do conector":

Determine as ligações do Microsoft Graph a criar (quantas ligações e que esquema para cada ligação) através da API de Lista de Ligações externas para consultar todas as ligações. Determine se pretende criar todas as ligações do zero, retomar a criação de ligações (no fluxo de resiliência) ou não (quando todas as ligações pretendidas já estiverem no estado pronto ).
A ligação é criada num estado de rascunho . Transmita a connectorsTicket cadeia codificada opaca para a API de criação da ligação no GraphConnectors-Ticket cabeçalho HTTP.
Registe o esquema.
Após uma criação ou atualização com êxito do esquema, a ligação deverá atingir um estado pronto .

Processar a notificação de "desativação do conector"

Para processar as notificações de "desativação do conector":

Determine as ligações do Microsoft Graph a eliminar com a API da Lista de Ligações externas para consultar todas as ligações.
Elimine todas as ligações com a API de Eliminação de Ligação externa.
Recomendamos que crie uma lógica de resiliência para repetir a ligação eliminada para verificar se foi eliminada.

Solicitação

POST https://example.com/notificationEndpoint
Content-type: application/json
Content-length: 100

{
  "value": [
    {
      "changeType": "updated",
      "subscriptionId": "79f3b611-7f15-4bdd-9422-9606a24e49f3",
      "resource": "external",
      "clientState": null,
      "resourceData": {
        "@odata.type": "#Microsoft.Graph.connector",
        "@odata.id": "external",
        "id": "{{connectorId}}",
        "state": "enabled" //e.g. enabled or disabled
        "connectorsTicket":"eyJhbGciOiJIUzI1…"
      },
      "subscriptionExpirationDateTime": "2021-06-26T12:40:26.4436785-07:00",
      "tenantId": "9f4ebab6-520d-49c0-85cc-7b25c78d4a93"
    }
  ],
  "validationTokens": [ "eyJ0eXAiOiJKV…" ]
}

Resposta

HTTP/1.1 202 Accepted
Content-type: application/json
Content-length: 0

Tem de enviar um 202 - Accepted código de status na sua resposta ao Microsoft Graph. Se o Microsoft Graph não receber um código de classe 2xx, tentará publicar a notificação de alteração várias vezes durante cerca de quatro horas. Depois disso, a notificação de alteração é removida e não é entregue.

Para validar a autenticidade de um validatonToken:

Verifique se o token não expirou.
Verifique se o token não foi adulterado e que foi emitido pelo plataforma de identidade da Microsoft.
Verifique se a afirmação appId no validationToken.
Verifique se a afirmação aud no validationToken é a mesma que "{{Teams-appid}}" que especificou.

Para obter mais informações, veja Validar a autenticidade da notificação.

O exemplo seguinte mostra um token de validação.

{ "typ": "JWT", "alg": "RS256", "x5t": "nOo3ZDrODXEK1jKWhXslHR_KXEg", "kid": "nOo3ZDrODXEK1jKWhXslHR_KXEg" }.{ "aud": "e478830d-8f49-4c26-80c6-58f68e0f064b", "iss": "https://sts.windows.net/9f4ebab6-520d-49c0-85cc-7b25c78d4a93/", "iat": 1624649764, "nbf": 1624649764, "exp": 1624736464, "aio": "E2ZgYGjnuFglnX7mtjJzwR5lYaWvAA==", "appid": "0bf30f3b-4a52-48df-9a82-234910c4a086", "appidacr": "2", "idp": "https://sts.windows.net/9f4ebab6-520d-49c0-85cc-7b25c78d4a93/", "oid": "1e7d79fa-7893-4d50-bdde-164260d9c5ba", "rh": "0.AX0AtrpOnw1SwEmFzHslx41KkzsP8wtSSt9ImoIjSRDEoIZ9AAA.", "sub": "1e7d79fa-7893-4d50-bdde-164260d9c5ba", "tid": "9f4ebab6-520d-49c0-85cc-7b25c78d4a93", "uti": "mIB4QKCeZE6hK71XUHJ3AA", "ver": "1.0" }.[Signature]

Criar ou eliminar ligações do Microsoft Graph

Tem de enviar o conectorTickets a partir do payload que recebeu como cabeçalho GraphConnectors-Ticket quando inicia a criação da ligação da aplicação Teams. O exemplo seguinte mostra este processo.

Solicitação

POST https://graph.microsoft.com/v1.0/external/connection
GraphConnectors-Ticket: {{connectorsTicket}}
Content-type: application/json
Authorization: bearer {{accessToken}}

{
    "id": "{{connectionId}}",
    "name": "Contoso HR",
    "description": "Connection to index Contoso HR system",
    "connectorId": "{{connectorId}}",
    "enabledContentExperiences": "MicrosoftSearch, Compliance, …",
    "searchSettings": { … },
    "complianceSettings": { … },
    …
}

Observação

Tem de definir {{connectorId}} para o valor fornecido na notificação dos Conectores do Graph quando criar a ligação.
Deve adquirir o {{accessToken}} do plataforma de identidade da Microsoft do inquilino que é notificado.

Resposta

HTTP/1.1 200 Accepted
Content-type: application/json
Content-length: 0

Observação

Várias experiências do Microsoft 365 podem ser ativadas para as ligações criadas. Para saber mais, confira a Visão Geral dos conectores do Microsoft Graph.

Para saber como ingerir itens externos numa ligação funcional do Microsoft Graph, consulte Criar, atualizar e eliminar itens adicionados pela sua aplicação através de conectores do Microsoft Graph.

Validar a experiência ao ativar o conector do Microsoft Graph no centro de administração do Teams

Para validar a experiência:

Inicie sessão no centro de administração do Teams como administrador do Teams ou Administrador global do inquilino.
Selecione o painel Gerir aplicações no painel esquerdo.
Aceda à sua aplicação do Teams.
Na página de detalhes da aplicação Teams, irá reparar num novo separador conector do Graph que permite a um administrador ativar ou desativar o conector do Microsoft Graph.
Selecione o botão de alternar para enviar as notificações ativar ou desativar para o ponto final de notificação da aplicação, conforme especificado pela propriedade graphConnector.notificationUrl no manifesto da aplicação.

Disponibilizar o conector do Microsoft Graph para outras organizações no centro de administração do Teams

Pode submeter o seu conector do Microsoft Graph empacotado como uma aplicação do Teams expandida pelo Microsoft 365 para o Centro de Parceiros da Microsoft. Isto permite à Microsoft validar o seu conector do Microsoft Graph, para que outras organizações possam detetá-lo e implementá-lo no centro de administração do Microsoft Teams.

Pode utilizar o guia de submissão passo a passo para saber como submeter a sua aplicação. Certifique-se de que submete uma aplicação do Teams no separador Microsoft 365 e Copilot nas ofertas do Marketplace.

Tem de submeter um PDF no passo Informações de certificação adicionais . A Microsoft utiliza as informações que fornece neste PDF para garantir que o conector do Microsoft Graph funciona conforme esperado no Microsoft 365 Copilot. O SEU PDF tem de ter as seguintes secções:

Contas de teste, chaves de licença e credenciais
Nome Vertical Personalizado
Etiquetas Semânticas
Solicitações de exemplo
Descrição da Ligação
Definições de Atividade

Contas de teste, chaves de licença e credenciais

Crie uma conta de utilizador no seu inquilino de demonstração que a Microsoft possa utilizar para validar o conector do Microsoft Graph. Isto pode ser feito na secção Utilizadores do Centro de Administração Microsoft 365. Certifique-se de que esta nova conta de utilizador tem uma licença de Microsoft 365 Copilot.

Nesta secção do PDF, forneça as credenciais e quaisquer chaves de licença aplicáveis para esta nova conta de utilizador. Estas informações são obrigatórias. Para saber mais sobre como preparar a conta de utilizador para validação, veja melhores práticas para fornecer notas de teste.

Depois de a Microsoft validar a sua aplicação, pode revogar o acesso à conta de utilizador.

Nome Vertical Personalizado

Crie um vertical personalizado que só devolve resultados do seu conector personalizado do Microsoft Graph. Faça-o na secção Verticais do separador Personalização do Portal de Pesquisa & Intelligence. Nesta secção do PDF, indique o nome desta vertical personalizada. Um nome para a vertical personalizada é obrigatório.

Etiquetas Semânticas

Na secção Etiquetas Semânticas, indique que propriedades do esquema de ligação têm as titleetiquetas , urle iconUrl semânticas. Este mapeamento de esquema é obrigatório.

Solicitações de exemplo

Na secção Exemplo Solicitações, forneça dois pedidos de exemplo que a Microsoft pode utilizar para validar o conector do Microsoft Graph no Microsoft 365 Copilot. Estes pedidos devem incluir, pelo menos, uma correspondência parcial com a title etiqueta semântica. Estes pedidos são obrigatórios.

Descrição da Ligação

Na secção Descrição da Ligação, forneça a propriedade para a description sua ligação personalizada do Microsoft Graph. A Microsoft utiliza esta opção para garantir que a sua ligação ao Microsoft Graph tem uma descrição avançada para Microsoft 365 Copilot. Essa descrição é opcional.

Definições de Atividade

Na secção Definições de Atividade, forneça as definições de atividade para a sua ligação do Microsoft Graph com um urlToItemResolvers recurso. As definições de atividade são opcionais, mas recomendamos vivamente que as forneça.

Compartilhar via

Ativar a experiência de administrador simplificada para o conector do Microsoft Graph

Atualizar o manifesto da aplicação Teams

Atualizar permissões do Microsoft Graph

Processar notificações de webhook do Microsoft Graph

Notificações de alteração

Processar a notificação de "ativação do conector"

Processar a notificação de "desativação do conector"

Solicitação

Resposta

Criar ou eliminar ligações do Microsoft Graph

Solicitação

Resposta

Validar a experiência ao ativar o conector do Microsoft Graph no centro de administração do Teams

Disponibilizar o conector do Microsoft Graph para outras organizações no centro de administração do Teams

Contas de teste, chaves de licença e credenciais

Nome Vertical Personalizado

Etiquetas Semânticas

Solicitações de exemplo

Descrição da Ligação

Definições de Atividade

Comentários

Recursos adicionais