Creación, actualización y eliminación de conexiones en Microsoft Graph

La plataforma de conectores de Microsoft Graph ofrece una manera intuitiva de agregar datos externos a Microsoft Graph. Una conexión es un contenedor lógico para los datos externos que un administrador puede administrar como una sola unidad.

Después de crear una conexión, puede agregar el contenido desde cualquier origen de datos externo, como un origen de contenido local o un servicio SaaS externo. Solo puede ver y administrar las conexiones que haya creado o que haya sido autorizado explícitamente a administrar. Un administrador de búsqueda puede ver y administrar todas las conexiones en el espacio empresarial desde el Centro de administración moderno.

Estructura de conector de ejemplo de un sistema personalizado de vales de servicio de asistencia.

Vista de administración de las conexiones, incluido el conector de entradas personalizado.

Puede modelar una conexión de la forma que quiera, sin embargo, crear una conexión para cada instancia del conector es el modelo más común. Por ejemplo, cada vez que configure el conector de archivos compartidos de Microsoft Windows, se crea una nueva conexión. También puede crear una única conexión para agregar todos los elementos del origen de datos. Por ejemplo, puede crear una sola conexión para agregar todos los vales e incidencias de varios equipos del sistema de servicio de asistencia.

Estados y operaciones

La conexión puede existir en uno de los siguientes estados.

Estado	Descripción
Borrador	Se aprovisionó una conexión vacía. No se configura ningún origen de datos, esquema o configuración.
Listo	La conexión se aprovisiona con el esquema registrado y está lista para la ingesta.
Obsoleto	Esto sucede cuando alguna característica dependiente, como una API, ha caído en desuso. La única operación válida en este caso es eliminar la conexión.
LimitExceeded	Si alcanza el límite máximo de una única conexión o la cuota de nivel de inquilino en todas las conexiones, no podrá agregar más elementos hasta que salga del estado.

En la siguiente tabla se especifican las operaciones disponibles para cada estado.

Operación	Borrador	Listo	Obsoleto	LimitExceeded
Crear conexión	❌	✔️	❌	✔️
Leer conexión	✔️	✔️	✔️	✔️
Actualizar conexión	✔️	✔️	❌	✔️
Eliminar conexión	✔️	✔️	✔️	✔️
Crear esquema	✔️	❌	❌	❌
Leer esquema	❌	✔️	✔️	✔️
Actualizar esquema	❌	❌	❌	❌
Eliminar esquema	❌	❌	❌	❌
Crear elemento	❌	✔️	❌	❌
Leer elemento	❌	✔️	✔️	✔️
Actualizar elemento	❌	✔️	❌	✔️
Eliminar elemento	❌	✔️	❌	✔️

Una conexión le permite a la aplicación definir un esquema de los elementos que se van a indexar y proporciona un punto de conexión para que el servicio agregue, actualice o elimine elementos del índice.

El primer paso para que una aplicación agregue elementos al índice de búsqueda es crear una conexión.

Crear una conexión

Para que una aplicación pueda agregar elementos al índice de búsqueda, debe crear y configurar una conexión:

1. Crear una conexión con un identificador, un nombre para mostrar y una descripción únicos.
2. Registre un esquema para definir los campos que se incluirán en el índice.

   Nota: Para obtener información sobre cómo actualizar el esquema de una conexión existente, vea Funcionalidades de actualización de esquema.

Configuración de conexión

Puede configurar los valores de conexión predeterminados para cada experiencia de contenido habilitada. Cuando se habilita, esta configuración afecta a las experiencias de contenido.

Configuración de búsqueda

Puede definir cómo se muestran los resultados de búsqueda en la página de resultados de Microsoft Búsqueda proporcionando las plantillas de visualización de búsqueda predeterminadas para el contenido en searchSettings. Se puede usar un conjunto de plantillas de visualización de búsqueda para mostrar distintos tipos de resultados de búsqueda de forma diferente. Una plantilla de visualización de búsqueda tiene un diseño de resultados creado mediante tarjetas adaptables y reglas que especifican una o varias condiciones. Cuando se cumplen estas condiciones, el diseño se aplica al resultado de la búsqueda y se muestra en la página de resultados.

Configuración de la actividad

En la configuración de actividad, puede proporcionar una manera para que las aplicaciones de Microsoft 365 detecten la actividad de recurso compartido, lo que permite recomendar el contenido a los usuarios que interactúan más con ese contenido. Para ello, agregue una urlToItemResolver. Esto permite que una dirección URL de la conexión detectada en las aplicaciones de Microsoft 365 se resuelva en su identificador de elemento correspondiente en externalItem.

En la imagen siguiente se muestra cómo puede aparecer el elemento dentro de las experiencias de recomendación en Microsoft 365.

En el ejemplo siguiente se muestra la carga de activitySettings con una sección urlToItemResolvers completa. Por ejemplo, cuando alguien comparte el vínculo https://contoso.com/items/39483948/, representa un externalItem que se ingerió a través de una conexión de Microsoft Graph. En este ejemplo, el vínculo compartido representa un externalItem con un itemId de id_39483948. Esta conexión especifica cómo asignar desde la dirección URL al itemId de ese externalItem. En este ejemplo, esta conexión tiene un identificador de contosohr.

Actualice la configuración de la actividad mediante el envío de una solicitud de revisión en la conexión.

PATCH https://graph.microsoft.com/v1.0/external/connections/contosohr

La siguiente carga activitySettings se envía con la solicitud de revisión.

{
  "@odata.type": "#microsoft.graph.externalConnectors.activitySettings",
  "urlToItemResolvers": [
    {
        "@odata.type": "#microsoft.graph.externalConnectors.itemIdResolver",
          "itemId": "id_{myItemId}",  
          "priority": 1,
          "urlMatchInfo": {
            "@odata.type": "microsoft.graph.externalConnectors.urlMatchInfo",
            "baseUrls": [
              "https://contoso.com"
            ],
            "urlPattern": "/items/(?<myItemId>[0-9]+)"
          }
    }
  ]
}

En este ejemplo, el campo itemId especificó cómo formar el identificador del elemento externo que representa la dirección URL. Se hace referencia al itemId en urlPattern (que está dentro de urlMatchInfo) para extraerlo 39483948 como el identificador del externalItem.

Puede proporcionar una lista de hasta ocho recursos itemIdResolver en el recurso urlToItemResolvers para la carga de la configuración de actividad. Para cada uno de estos recursos urlMatchInfo , especifique un valor de #microsoft.graph.externalConnectors.itemIdResolver para , @odata.typeun entero de uno a ocho para la propiedad priority y un objeto urlMatchInfo que contenga una lista de direcciones URL base y una expresión regular.

Cuando se comparte un vínculo, los objetos urlMatchInfo que pertenecen a los solucionadores se aplican en el orden especificado por los valores de prioridad . En orden de prioridad ascendente, la dirección URL se compara primero con las direcciones URL de la lista baseUrls de la propiedad urlMatchInfo . A continuación, si la base de la dirección URL del vínculo está en la lista baseUrls , la expresión regular urlPattern se aplica a la dirección URL. Si este patrón coincide, no se aplican más solucionadores. Si la base de la dirección URL del vínculo no está en la lista baseUrls o el urlPattern no coincide, la siguiente urlToItemResolver se evalúa hasta que se encuentra una coincidencia o no hay más recursos urltoItemResolver para aplicar.

Para obtener más información sobre los recursos urlMatchInfo , consulte tipo urlMatchInfo.

Actualizar una conexión

Para cambiar el nombre para mostrar, la descripción o las experiencias de contenido habilitadas para una conexión existente, puede actualizar la conexión.

Eliminar una conexión

Para quitar todos los elementos que se indizaron a través de una conexión, puede eliminar una conexión.

Pasos siguientes

• Registrar el esquema de conexión
• Revisar la referencia de la API de conectores de Microsoft Graph
• Descarga del conector de búsqueda de ejemplo desde GitHub