Ejercicio: Configuración de una conexión externa e implementación del esquema

Completado

En este ejercicio, creará un conector personalizado de Microsoft Graph como una aplicación de consola. Registre un nuevo registro de aplicación Microsoft Entra y agregue el código para crear una conexión externa e implementar su esquema.

Creación de un nuevo proyecto de conector de Graph

Para empezar, cree un nuevo proyecto de conector de Graph. Aunque podría crear el proyecto y todos los archivos necesarios manualmente, en este ejemplo se usa el repositorio de GitHub de plantilla para los conectores de Graph. La ventaja de usar el repositorio de plantillas es que crea un proyecto sencillo con los archivos y dependencias necesarios, lo que le ahorra tiempo.

En una línea de comandos:

1. Clonación del repositorio de plantillas mediante la ejecución de git clone https://github.com/microsoft/learn-microsoft-graph-connectors-dotnet.git

   Sugerencia

   Si no tiene instalado Git o no tiene una cuenta de GitHub, puede descargar el repositorio como un archivo ZIP. Extraiga el archivo ZIP en una carpeta del equipo para continuar con el ejercicio.

2. Cambie el directorio de trabajo al repositorio clonado.

3. Abra el proyecto recién creado en el editor de código.

En el editor de código:

1. Abra el archivo ConnectionConfiguration.cs . En el objeto devuelto por el ExternalConnection captador:
   1. Cambie el valor de la propiedad Id a msgraphdocs.
   2. Cambie el valor de la propiedad Name a Microsoft Graph documentation.
   3. Cambie el valor de la propiedad Description a Documentation for Microsoft Graph API which explains what Microsoft Graph is and how to use it.
2. Guarde los cambios.

Sugerencia

El README.md archivo del proyecto generado contiene más información sobre los diferentes archivos y carpetas del proyecto. Tómese un momento para leerlo y familiarizarse con la estructura del proyecto.

Registro de un nuevo registro de aplicación Microsoft Entra

El proyecto que ha creado contiene un script de instalación que crea y configura un nuevo registro Microsoft Entra aplicación. El conector de Graph usa este registro de aplicaciones para autenticarse con Microsoft 365.

En una línea de comandos:

1. Cambie el directorio de trabajo a la carpeta del proyecto.
2. Ejecute el script de instalación: .\setup.ps1
3. Cuando se le solicite, inicie sesión en el inquilino de Microsoft 365 con su cuenta profesional.
4. Espere a que el script termine de crear el registro de la aplicación. El script crea un registro de aplicación Entra denominado documentación de Microsoft Graph.
5. Cuando finaliza el script, almacena de forma segura la información de registro de la aplicación en secretos de usuario.

El script de instalación usa el SDK de PowerShell de Microsoft Graph para crear un nuevo registro Microsoft Entra aplicación en el inquilino. Configura el registro de la aplicación con los permisos de Microsoft Graph API necesarios para crear una conexión externa e ingerir contenido. También configura el registro de la aplicación con un secreto para permitir la autenticación sin interacción del usuario.

Sugerencia

Para explorar la configuración de registro de aplicaciones, en un explorador web:

1. Vaya a Azure Portal en https://portal.azure.com.
2. En la navegación, seleccione Microsoft Entra ID.
3. En la navegación lateral, seleccione Registros de aplicaciones.
4. En la lista de registros de aplicaciones, seleccione el registro de aplicación creado por el script de instalación.
5. Explore las distintas propiedades, como permisos de API, certificados & secretos y autenticación.

Definición de la configuración de esquema y conexión externa

El siguiente paso es definir la conexión externa y el esquema que debe usar el conector de Graph. Dado que el código del conector necesita acceso al identificador de la conexión externa en varios lugares, guárdalo en un lugar central del código.

En el editor de código:

1. Abra el archivo ConnectionConfiguration.cs .

2. Del objeto devuelto por la ExternalConnection propiedad , quite las ActivitySettings propiedades y SearchSettings . No los necesita para este ejercicio.

3. Observe las propiedades de esquema devueltas por la Schema propiedad .

   La primera propiedad es title, que almacena el título del elemento externo importado a Microsoft 365. El título del elemento forma parte del índice de texto completo (IsSearchable = true). Los usuarios también pueden consultar explícitamente su contenido en consultas de palabras clave (IsQueryable = true). El título también se puede recuperar y mostrar en los resultados de búsqueda (IsRetrievable = true). La title propiedad representa el título del elemento, que se indica mediante la Title etiqueta semántica.

   A continuación, está la url propiedad , que almacena la dirección URL original del elemento externo. Los usuarios usan esta dirección URL para navegar al elemento externo desde los resultados de la búsqueda o Copilot desde Microsoft 365. La dirección URL es una de las propiedades que Microsoft 365 Copilot requiere, por lo que se asigna mediante la Url etiqueta semántica.

   Por último, hay la iconUrl propiedad que almacena la dirección URL del icono para cada elemento. Microsoft 365 Copilot requiere esta propiedad y debe asignarse mediante la IconUrl etiqueta semántica.

   Microsoft 365 Copilot requiere que los conectores de Graph definan al menos estas tres propiedades y las designen con las etiquetas semánticas adecuadas.

4. A la Properties matriz, agregue una nueva propiedad denominada description:

   new Property
   {
     Name = "description",
     Type = PropertyType.String,
     IsQueryable = true,
     IsSearchable = true,
     IsRetrievable = true
   }
   

   La description propiedad almacena el resumen del contenido del elemento externo. Su definición es similar al título. Sin embargo, no hay ninguna etiqueta semántica para la descripción, por lo que no la define.

5. El código completo tiene el siguiente aspecto:

   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
             }
           }
         };
       }
     }
   }
   

6. Save your changes

Revisión del código de creación de conexiones

El generador de proyectos del conector de Graph crea código que crea la conexión externa y aprovisiona su esquema. Puede usarlo sin cambios. Antes de hacerlo, fíjese en él para comprender cómo funciona. El código está en el archivo ConnectionService.cs .

En el editor de código:

1. Abra el archivo ConnectionService.cs .
2. El archivo contiene dos métodos: CreateConnection y CreateSchema. El CreateConnection método crea la conexión externa y el CreateSchema método aprovisiona el esquema.

Si recuerda, el aprovisionamiento del esquema de conexión externa es una operación de larga duración. Sin embargo, el código del CreateSchema método no parece estar esperando a que se aprovisione el esquema. El cliente de Microsoft Graph de este proyecto usa un middleware personalizado que espera a que se complete la operación. Dado que este middleware controla la espera de que se complete la operación, la CreateSchema función no necesita incluir ningún otro código y solo debe esperar a la solicitud de API. El middleware está en el archivo CompleteJobWithDelayHandler.cs .

Comprobación del código

El último paso a la izquierda es comprobar que el código funciona correctamente. El archivo Program.cs contiene el punto de entrada de la aplicación. Usa el paquete System.CommandLine para definir un comando que se invoca iniciando la aplicación desde la línea de comandos.

En una línea de comandos:

1. Abra un terminal
2. Cambie el directorio de trabajo a la carpeta del proyecto.
3. Ejecute dotnet build para compilar el proyecto.
4. Inicie la aplicación ejecutando dotnet run -- create-connection.
5. Espere varios minutos a que se cree la conexión y el esquema.