Adicionar uma caixa de diálogo aos modelos de Cartões Adaptáveis (pré-visualização)

Pode melhorar as respostas do Cartão Adaptável em agentes declarativos para Microsoft 365 Copilot adicionando caixas de diálogo modais. Essas caixas de diálogo pop-up podem hospedar HTML/JavaScript personalizado ou exibir widgets baseados em iframe - como páginas da Web, vídeos do YouTube ou conteúdo Microsoft Stream - em uma experiência focada e interativa.

Este artigo descreve como utilizar Action.OpenUrlDialog (disponível no esquema de Cartão Adaptável versão 1.5) para iniciar caixas de diálogo modais a partir de modelos de Cartão Adaptável e como configurar a autenticação de utilizador.

Observação

A OpenUrlDialog ação encontra-se atualmente em pré-visualização.

Pré-requisitos

Para utilizar Action.OpenUrlDialogo , precisa dos seguintes pré-requisitos:

  • Esquema de cartão adaptável versão 1.5
  • Manifesto de plug-in API versão 2.3
  • Biblioteca JS do Microsoft Teams(para cenários de autenticação)

Definir o modelo de Cartão Adaptável

Para utilizar a ação da caixa de diálogo modal:

O exemplo a seguir mostra o esquema para Action.OpenUrlDialog.

"actions": [
     {
         "type": "Action.OpenUrlDialog",
         "title": "OpenDialogWithDimension",
         "url": "${url}",
         "dialogHeight": "large",
         "dialogWidth": "600px",
         "dialogTitle": "task module"
     }
    ]

Para obter informações de referência de esquema, consulte Action.OpenUrlDialog.

Configurar o tamanho da caixa de diálogo

Use as propriedades dialogHeight e dialogWidth para definir a altura e a largura da caixa de diálogo. Estes valores ajustam-se dinamicamente com base na resolução do ecrã do utilizador e no tamanho da janela.

Pode especificar:

  • Tamanhos predefinidos - small, medium, ou large.
  • Valores de pixel personalizados - por exemplo, 400px, 600px.

Dica

Utilize valores de píxeis para um controlo preciso. Os tamanhos predefinidos são relativos ao espaço disponível no ecrã.

A imagem seguinte mostra um exemplo de uma caixa de diálogo invocada a partir de um botão Cartão Adaptável devolvido por um agente.

Imagem de uma caixa de diálogo para os utilizadores introduzirem informações de clientes

Configurar autenticação

Para permitir o acesso seguro às APIs a partir da caixa de diálogo, configure a autenticação usando um dos seguintes métodos:

  • Microsoft Entra ID
  • OAuth 2.0 (pré-visualização)

Microsoft Entra ID configuração

Para usar a autenticação de ID de Entra para autenticação de API, use uma das seguintes abordagens:

  • Configure Entra ID, OAuth 2.0 ou autenticação baseada em chave de API usando a Microsoft como o provedor de identidade.
  • Use outro provedor de identidade e registre seu aplicativo em Entra ID.

Configurar a autenticação baseada em SSO

Configure o logon único (SSO) para permitir que os usuários acessem APIs sem precisar entrar várias vezes.

Para ativar o SSO:

  1. Atualize a aplicação Microsoft Entra ID.
    • Configure o URI do ID do aplicativo.
    • Configurar âmbitos e definições de consentimento.
    • Pré-autorize aplicações cliente fidedignas para evitar pedidos de consentimento repetidos.
  2. Implemente a lógica de recuperação e validação do token.
    • Use o getAuthToken() método da biblioteca TeamsJS para recuperar um token de acesso.
    • Envie o token para o servidor no cabeçalho Autorização.
    • Valide o lado do servidor do token.
  3. Atualize o manifesto da aplicação.
    • Adicione a propriedade webApplicationInfo ao manifesto do aplicativo para habilitar o SSO.
    • Adicione o domínio do conteúdo da caixa de diálogo à propriedade "validDomains" do manifesto do aplicativo.

Atualizar a aplicação Microsoft Entra ID

Para configurar âmbitos e autorizar aplicações cliente fidedignas, atualize a sua aplicação Microsoft Entra ID da seguinte forma:

  1. Adicione um URI da API à propriedade identifierUris do manifesto do aplicativo. Utilize o seguinte formato para o URI: 'api://fully-qualified-domain-name.com/{AppID}, conforme mostrado no exemplo seguinte.

    "identifierUris": [
    "api://b4ab3a28-16da-4a19-a07a-51ab0f3553db",
    "api://4-213-70-45.ngrok-free.app/b4ab3a28-16da-4a19-a07a-51ab0f3553db",
    "api://auth-58bfdecc-2870-4cda-99b4-1d30383b952b/b4ab3a28-16da-4a19-a07a-51ab0f3553db"
    ],
    
  2. Defina o escopo da API e quem pode consentir o escopo. Na seçãoEscopos definidos por esta API do centro de administração do Microsoft Entra, selecione + Adicionar um escopo.

    Uma captura de ecrã dos campos para adicionar um âmbito

    1. Introduza o nome do âmbito. Este campo é obrigatório.
    2. Selecione o utilizador que pode dar consentimento para este âmbito. A opção predefinida é apenas Administradores.
    3. Introduza o nome a apresentar do consentimento Administração. Este campo é obrigatório.
    4. Introduza a descrição do consentimento de administrador. Este campo é obrigatório.
    5. Introduza o nome a apresentar do Consentimento do utilizador.
    6. Introduza a descrição para a descrição de consentimento do utilizador.
    7. No campo Estado , selecione a opção Habilitado para estado.
    8. Selecione Adicionar âmbito.
  3. Crie IDs de cliente autorizados para aplicativos que você deseja pré-autorizar. Isto permite que o utilizador da aplicação aceda aos âmbitos (permissões) da aplicação que configurou sem necessitar de consentimento adicional. Uma vez que os utilizadores da aplicação não terão a oportunidade de recusar o consentimento, efetue uma pré-autorização apenas a aplicações cliente fidedignas.

    1. Na seção Aplicativo cliente autorizado do centro de administração do Microsoft Entra, selecione + Adicionar um aplicativo cliente.

      Captura de ecrã com o botão Adicionar uma aplicação cliente realçado

    2. Introduza o ID de cliente do Microsoft 365 para as aplicações que pretende autorizar.

Implementar lógica de recuperação e validação de tokens

Adicione código para manipular o token de acesso, envie o token para o código do servidor do seu aplicativo no cabeçalho Autorização e valide o token de acesso quando ele for recebido.

Para obter acesso à aplicação para o utilizador atual da aplicação, o seu código do lado do cliente tem de efetuar uma chamada para o Teams para obter um token de acesso. Atualize o código do lado do cliente para iniciar getAuthToken() o processo de validação, conforme mostrado no exemplo a seguir.

// Get auth token
// Ask Teams to get us a token from AAD
function getClientSideToken() {
     return new Promise((resolve, reject) => {
         display("1. Get auth token from Microsoft Teams");

         microsoftTeams.authentication.getAuthToken().then((result) => {
             display(result);
             resolve(result);
         }).catch((error) => {
             reject("Error getting token: " + error);
         });
     });
 }

Quando o Teams recebe o token de acesso, armazena-o em cache para ser reutilizado conforme necessário. O token é utilizado quando getAuthToken() é chamado sem necessidade de efetuar outra chamada ao Microsoft Entra ID, até o token expirar.

Quando telefona getAuthToken() e é necessário o consentimento do utilizador para as permissões ao nível do utilizador, o utilizador com sessão iniciada vê uma caixa de diálogo Microsoft Entra e tem de dar consentimento inicial uma vez.

Após o consentimento do utilizador, pode aceder à página Web da caixa de diálogo. Os seguintes pontos aplicam-se ao consentimento do utilizador:

  • Se o administrador tiver concedido consentimento em nome do inquilino, não é necessário pedir consentimento aos utilizadores da aplicação. Isto significa que os utilizadores da aplicação não veem a caixa de diálogo de consentimento e podem aceder à aplicação sem problemas.
  • Se a sua aplicação Microsoft Entra estiver registada no mesmo inquilino ao qual está a pedir uma autenticação no Teams, não será pedido ao utilizador da aplicação que dê consentimento e ser-lhe-á concedido um token de acesso de imediato. Os utilizadores da aplicação só consentem estas permissões se a aplicação Microsoft Entra estiver registada num inquilino diferente.
  • Uma vez que os utilizadores têm de fornecer consentimento para o acesso à API e que o consentimento é necessário apenas uma vez por utilizador, não é necessário consentimento adicional para as caixas de diálogo.

Atualizar o manifesto da aplicação

Configure a propriedade webApplicationInfo no arquivo de manifesto do aplicativo para habilitar o SSO. Isso ajuda os usuários do agente a acessar seu agente perfeitamente. A tabela a seguir lista as propriedades da propriedade webApplicationInfo .

Propriedade Descrição
id Introduza o ID da aplicação (GUID) que criou no Microsoft Entra ID.
recurso Insira o URI do subdomínio do seu aplicativo e o URI da ID do aplicativo que você criou no Microsoft Entra ID quando criou o escopo.
"webApplicationInfo": {
  "id": "7c7c79df-bf9d-43b7-a464-1cb9995eb3b2",
  "resource": "api://67ec-4-213-76-42.ngrok-free.app/7c7c79df-bf9d-43b7-a464-1cb9995eb3b2"
 }

Especifique o domínio da URL que você deseja renderizar na caixa de diálogo na propriedade validDomains do manifesto do aplicativo, conforme mostrado no exemplo a seguir.

"validDomains": [
     "contoso.com",
     "mysite.someplace.com",
     "othersite.someplace.com"
 ]

Configuração do OAuth 2.0 (versão prévia)

Para agentes que usam o OAuth 2.0 com o Microsoft Entra ID ou outros provedores de identidade, use a authentication.authenticate() função na biblioteca do TeamsJS para iniciar o fluxo de autenticação.

Para habilitar a autorização do OAuth 2.0 para caixas de diálogo de plug-in de API:

  • Configure seu aplicativo para usar o Microsoft Entra ID como um provedor de identidade.
  • Faça alterações no código para iniciar o fluxo de autenticação e manipular o token.

Configurar seu aplicativo para usar o Microsoft Entra ID como um provedor de identidade

Para configurar seu aplicativo para usar o Microsoft Entra ID:

  • No portal do Azure, vá para o registro do aplicativo.
  • Em Autenticação, na seção URI de redirecionamento , adicione a URL de redirecionamento ao ponto de extremidade de autenticação. Use o seguinte formato para a URL de redirecionamento: https://<hostname>/auth/simple-start.

Iniciar o fluxo de autenticação e manipular o token

A maioria dos provedores de identidade não permite que o conteúdo seja colocado em um iframe. Isso significa que você precisa de uma página para hospedar o provedor de identidade que o Copilot exibe em uma janela pop-up. Use a authentication.authenticate() função da biblioteca TeamsJS para iniciar esta página quando o botão Cartão Adaptável for selecionado.

Observação

A URL para authenticate() a qual você passa é a página inicial do fluxo de autenticação. Ele deve corresponder ao que você registrou no portal do Azure. O fluxo de autenticação deve começar em uma página do seu domínio. Certifique-se de listar esse domínio na propriedade validDomains no manifesto.

import { authentication } from "@microsoft/teams-js";

authentication.authenticate({
     url: window.location.origin + "/auth/simple-start",
     width: 600,
     height: 535
 })
.then((result) => {
     console.log("Login succeeded: " + result);
     let data = localStorage.getItem(result);
     localStorage.removeItem(result);
     let tokenResult = JSON.parse(data);
     showIdTokenAndClaims(tokenResult.idToken);
     getUserProfile(tokenResult.accessToken);
 })
.catch((reason) => {
     console.log("Login failed: " + reason);
     handleAuthError(reason);
 });

A página pop-up redireciona para o provedor de identidade para que o usuário possa entrar. O agente chama o serviço de autorização do Microsoft Entra e passa informações do usuário e do aplicativo para que o usuário possa se autenticar no Entra ID. Em seguida, o ID do Entra chama a página de retorno de chamada fornecida.

app.getContext().then((context) => {
// Generate random state string and store it, so we can verify it in the callback
     let state = _guid(); // _guid() is a helper function in the sample
     localStorage.setItem("simple.state", state);
     localStorage.removeItem("simple.error");

     // Go to the Azure AD authorization endpoint
     let queryParams = {
         client_id: "{{appId}}",
         response_type: "id_token token",
         response_mode: "fragment",
         scope: "https://graph.microsoft.com/User.Read openid",
         redirect_uri: window.location.origin + "/auth/simple-end",
         nonce: _guid(),
         state: state,
         // The context object is populated by Teams; the loginHint attribute
         // is used as hinting information
         login_hint: context.user.loginHint,
     };

     let authorizeEndpoint = `https://login.microsoftonline.com/${context.user.tenant.id}/oauth2/v2.0/authorize?${toQueryString(queryParams)}`;
     window.location.assign(authorizeEndpoint);
 });

Determine o sucesso ou a falha da solicitação de autenticação com base nas informações retornadas pelo Entra ID e chame ou authentication.notifySuccess()authentication.notifyFailure(). Se a entrada foi bem-sucedida, o usuário tem acesso aos recursos de serviço.