Exercício – Configurar uma ligação externa e implementar o esquema

8 minutos

Neste exercício, vai criar um conector personalizado do Microsoft Graph como uma aplicação de consola. Regista um novo Microsoft Entra registo de aplicações e adiciona o código para criar uma ligação externa e implementar o respetivo esquema.

Criar um novo projeto de conector do Graph

Comece por criar um novo projeto de conector do Graph. Embora possa criar o projeto e todos os ficheiros necessários manualmente, neste exemplo, vai utilizar o repositório do GitHub de modelo para conectores do Graph. A vantagem de utilizar o repositório de modelos é criar um projeto simples para si com os ficheiros e dependências necessários, poupando-lhe tempo.

Numa linha de comandos:

Clonar o repositório de modelos ao executar git clone https://github.com/microsoft/learn-microsoft-graph-connectors-dotnet.git

Dica

Se não tiver o git instalado ou não tiver uma conta do GitHub, pode transferir o repositório como um ficheiro ZIP. Extraia o ficheiro ZIP para uma pasta no seu computador para continuar o exercício.
Altere o diretório de trabalho para o repositório clonado.
Abra o projeto recém-criado no editor de código.

No editor de código:

Abra o ficheiro ConnectionConfiguration.cs . No objeto devolvido pelo ExternalConnection getter:
1. Altere o valor da propriedade ID para msgraphdocs.
2. Altere o valor da propriedade Nome para Microsoft Graph documentation.
3. Altere o valor da propriedade Descrição para Documentation for Microsoft Graph API which explains what Microsoft Graph is and how to use it.
Salve suas alterações.

Dica

O README.md ficheiro no projeto gerado contém mais informações sobre os diferentes ficheiros e pastas no projeto. Dedique algum tempo a lê-lo e familiarize-se com a estrutura do projeto.

Registar um novo registo de aplicações Microsoft Entra

O projeto que criou contém um script de configuração que cria e configura um novo Microsoft Entra registo de aplicações. O conector do Graph utiliza este registo de aplicação para autenticar com o Microsoft 365.

Numa linha de comandos:

Altere o diretório de trabalho para a pasta do projeto.
Execute o script de configuração: .\setup.ps1
Quando lhe for pedido, inicie sessão no seu inquilino do Microsoft 365 com a sua conta profissional.
Aguarde até que o script conclua a criação do registo da aplicação. O script cria um registo da aplicação Entra com o nome Documentação do Microsoft Graph.
Quando o script for concluído, armazena em segurança as informações de registo de aplicações em segredos do utilizador.

O script de configuração utiliza o SDK do PowerShell do Microsoft Graph para criar um novo Microsoft Entra registo de aplicações no seu inquilino. Configura o registo de aplicações com o Microsoft API do Graph permissões necessárias para criar uma ligação externa e ingerir conteúdo. Também configura o registo da aplicação com um segredo para permitir a autenticação sem interação do utilizador.

Dica

Para explorar a configuração do registo de aplicações, num browser:

Aceda ao Portal do Azure em https://portal.azure.com.
Na navegação, selecione Microsoft Entra ID.
Na navegação lateral, selecione Registros de aplicativo.
Na lista de registos de aplicações, selecione o registo de aplicações criado pelo script de configuração.
Explore as diferentes propriedades, como permissões de API, Certificados & segredos e Autenticação.

Definir a ligação externa e a configuração do esquema

O próximo passo é definir a ligação externa e o esquema que o conector do Graph deve utilizar. Uma vez que o código do conector precisa de acesso ao ID da ligação externa em vários locais, armazene-o num local central no seu código.

No editor de código:

Abra o ficheiro ConnectionConfiguration.cs .
No objeto devolvido pela ExternalConnection propriedade , remova as ActivitySettings propriedades e SearchSettings . Não precisa deles para este exercício.
Repare nas propriedades do esquema devolvidas pela Schema propriedade .

A primeira propriedade é title, que armazena o título do item externo importado para o Microsoft 365. O título do item faz parte do índice de texto completo (IsSearchable = true). Os utilizadores também podem consultar explicitamente os respetivos conteúdos em consultas palavra-chave (IsQueryable = true). O título também pode ser obtido e apresentado nos resultados da pesquisa (IsRetrievable = true). A title propriedade representa o título do item, que indica com a Title etiqueta semântica.

Em seguida, existe a url propriedade , que armazena o URL original do item externo. Os utilizadores utilizam este URL para navegar para o item externo a partir dos resultados da pesquisa ou copilot do Microsoft 365. O URL é uma das propriedades necessárias Microsoft 365 Copilot, razão pela qual o mapeia com a Url etiqueta semântica.

Por fim, existe a iconUrl propriedade que armazena o URL do ícone para cada item. Microsoft 365 Copilot requer esta propriedade e tem de ser mapeada com a IconUrl etiqueta semântica.

Microsoft 365 Copilot requer que os conectores do Graph definam, pelo menos, estas três propriedades e as designem com as etiquetas semânticas adequadas.
À matriz, adicione uma nova propriedade com o Properties nome description:
```
new Property
{
  Name = "description",
  Type = PropertyType.String,
  IsQueryable = true,
  IsSearchable = true,
  IsRetrievable = true
}
```
A description propriedade armazena o resumo do conteúdo do item externo. A definição é semelhante ao título. No entanto, não existe uma etiqueta semântica para a descrição, razão pela qual não a define.

O código completo tem o seguinte aspeto:

using System.Text.Json;
using Microsoft.Graph.Models;
using Microsoft.Graph.Models.ExternalConnectors;

static class ConnectionConfiguration
{
  private static Dictionary<string, object>? _layout;
  private static Dictionary<string, object> Layout
  {
    get
    {
      if (_layout is null)
      {
        var adaptiveCard = File.ReadAllText("resultLayout.json");
        _layout = JsonSerializer.Deserialize<Dictionary<string, object>>(adaptiveCard);
      }

      return _layout!;
    }
  }

  public static ExternalConnection ExternalConnection
  {
    get
    {
      return new ExternalConnection
      {
        Id = "msgraphdocs",
        Name = "Microsoft Graph documentation",
        Description = "Documentation for Microsoft Graph API which explains what Microsoft Graph is and how to use it."
      };
    }
  }

  public static Schema Schema
  {
    get
    {
      return new Schema
      {
        BaseType = "microsoft.graph.externalItem",
        Properties = new()
        {
          new Property
          {
            Name = "title",
            Type = PropertyType.String,
            IsQueryable = true,
            IsSearchable = true,
            IsRetrievable = true,
            Labels = new() { Label.Title }
          },
          new Property
          {
            Name = "url",
            Type = PropertyType.String,
            IsRetrievable = true,
            Labels = new() { Label.Url }
          },
          new Property
          {
            Name = "iconUrl",
            Type = PropertyType.String,
            IsRetrievable = true,
            Labels = new() { Label.IconUrl }
          },
          new Property
          {
            Name = "description",
            Type = PropertyType.String,
            IsQueryable = true,
            IsSearchable = true,
            IsRetrievable = true
          }
        }
      };
    }
  }
}

Save your changes

Rever o código de criação da ligação

O gerador de projetos do conector do Graph cria código que cria a ligação externa e aprovisiona o esquema. Pode utilizá-lo sem alterações. Antes de o fazer, consulte-o para compreender como funciona. O código está no ficheiro ConnectionService.cs .

No editor de código:

Abra o ficheiro ConnectionService.cs .
O ficheiro contém dois métodos: CreateConnection e CreateSchema. O CreateConnection método cria a ligação externa e o método aprovisiona CreateSchema o esquema.

Caso se lembre, o aprovisionamento do esquema de ligação externa é uma operação de execução prolongada. No entanto, o código no CreateSchema método não parece estar à espera que o esquema seja aprovisionado. O cliente do Microsoft Graph neste projeto utiliza um middleware personalizado que aguarda a conclusão da operação. Uma vez que este middleware processa a espera que a operação seja concluída, a CreateSchema função não precisa de incluir outro código e só precisa de aguardar o pedido da API. O middleware está no ficheiro CompleteJobWithDelayHandler.cs .

Testar o código

O último passo à esquerda é verificar se o código está a funcionar corretamente. O ficheiro Program.cs contém o ponto de entrada da aplicação. Utiliza o pacote System.CommandLine para definir um comando que invoca ao iniciar a aplicação a partir da linha de comandos.

Numa linha de comandos:

Abrir um terminal.
Altere o diretório de trabalho para a pasta do projeto.
Execute dotnet build para compilar o projeto.
Inicie a aplicação ao executar dotnet run -- create-connection.
Aguarde vários minutos para que a ligação e o esquema sejam criados.

Exercício – Configurar uma ligação externa e implementar o esquema

Criar um novo projeto de conector do Graph

Registar um novo registo de aplicações Microsoft Entra

Definir a ligação externa e a configuração do esquema

Rever o código de criação da ligação

Testar o código

Comentários