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.
Una vez creada una conexión, puede agregar el contenido desde cualquier origen de datos externo, como un origen de contenido local o un servicio de software como 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:
- Crear una conexión con un identificador, un nombre para mostrar y una descripción únicos.
-
Registre un esquema para definir los campos que se incluirán en el índice.
Nota: Para obtener más información sobre cómo actualizar el esquema para 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 Búsqueda de Microsoft 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.