Crear, actualizar y eliminar elementos en una conexión Microsoft Graph
Los conectores de Microsoft Graph ofrecen una manera intuitiva de incorporar datos externos en Microsoft Graph. Los elementos que la aplicación agrega a microsoft servicio Search se representan mediante el recurso externalItem de Microsoft Graph.
Después de crear una conexión, puede agregar el contenido. Cada elemento del origen de datos debe representarse como un elemento externalItem en Microsoft Graph con un ID de elemento único. Este ID se usa para crear, actualizar o eliminar el elemento de Microsoft Graph. Puede usar la clave principal del origen de datos como el id. de elemento o derivarla de uno o varios campos.
Componentes clave
Un externalItem tiene tres componentes clave: lista de control de acceso, propiedades y contenido.
Lista de control de acceso
La lista de control de acceso (ACL) se usa para especificar si se concede o deniega a los roles el acceso para ver los elementos de las experiencias de Microsoft. La ACL es una matriz de entradas de control de acceso que representa un usuario o grupo Microsoft Entra. Un tercer tipo de entrada de control Everyone representa a todos los usuarios del espacio empresarial.
Ejemplo de lista de control de acceso.
El valor deny de tipo accessType tiene prioridad sobre grant. Por ejemplo, en el elemento mostrado anteriormente, mientras se concede el acceso a Everyone y se niega el acceso a un usuario específico, el permiso efectivo para este usuario es deny.
Si el origen de datos tiene grupos que no son de Azure AD (como los equipos del sistema de soporte técnico) y que se usan para establecer permisos para el elemento, puede crear grupos externos en Microsoft Graph con las API de sincronización de grupos para replicar los permisos de allow o deny. Evite expandir la pertenencia de los grupos externos directamente a las ALC de elementos individuales, ya que cada pertenencia a grupos puede producir un gran volumen de actualizaciones de elementos.
Los grupos externos incluyen otro grupo, usuarios Microsoft Entra y grupos de Microsoft Entra. Si tiene usuarios que no son de Azure AD, debe traducirlos a Microsoft Entra usuarios de la ACL.
Propiedades
El componente propiedades se usa para agregar metadatos de elementos útiles en las experiencias de Microsoft Graph. Debe registrar el esquema para la conexión antes de agregar elementos a esta, y convertir los tipos de contenido en tipos de contenido compatibles.
Ejemplo de un componente de propiedad.
Contenido
El componente de contenido agrega la mayor parte del elemento que debe indizarse con texto completo. Los ejemplos incluyen una descripción de vale, texto analizado de un cuerpo de archivo o un cuerpo de una página wiki.
El contenido es uno de los campos clave que influyen en la relevancia entre las experiencias de Microsoft. Los tipos de contenido text y html son compatibles. Si el origen de datos tiene otros tipos de contenido, como archivos binarios, vídeos o imágenes, puede analizarlos en texto antes de agregarlos a Microsoft Graph. Por ejemplo, el reconocimiento óptico de caracteres puede extraer texto que permite búsquedas de imágenes.
Importante
La solución de cumplimiento solo admite text el tipo de contenido. Si habilita la conexión para el cumplimiento estableciendo la propiedad complianceenabledContentExperience en , debe ingerir contenido en formato de texto sin formato y establecer el tipo textde contenido en .
Ejemplo de un componente de contenido.
El contenido no se puede agregar directamente a una plantilla de resultado de búsqueda, pero puede usar un fragmento de código de resultados generado, que es una vista previa generada dinámicamente de las secciones pertinentes dentro del contenido.
Plantilla de resultados de búsqueda.
Cuando el contenido del origen de datos cambie, debe sincronizarlo con los elementos de conexión. Puede actualizar todo el elemento o uno o varios componentes. Después de agregar el contenido a Microsoft Graph, puede buscarlo a través de la experiencia de Búsqueda de Microsoft después de configurar los tiposde resultados y verticales de búsqueda o mediante La API de búsqueda de Microsoft Graph.
Actividades
El componente activities es una propiedad transitoria que envía actividades al elemento. Solo puede escribir en esta propiedad.
Una actividad consta de un actor (que realizó la actividad), una hora (cuando se realizó la actividad) y un tipo de actividad (qué tipo de actividad se realizó). Los tipos de actividad que se admiten actualmente se pueden encontrar en la sección Descripción de la propiedad type de una externalActivity.
El envío de actividades en el elemento potencia las experiencias de recomendaciones inteligentes en Microsoft 365. Los usuarios finales pueden recibir contenido adaptado a ellos en función de las actividades que se envían.
Agregar una elemento
Para agregar un elemento al índice, cree un externalItem. Al crear un elemento, asigne un identificador único en la dirección URL.
Por ejemplo, es posible que la aplicación indexe las incidencias de soporte técnico mediante el número de incidencia. Si un vale tiene el número de vale SR00145, la solicitud podría ser similar a la siguiente:
PUT /external/connections/contosohelpdesk/items/SR00145
Content-Type: application/json
"properties": {
"title": "WiFi outage in Conference Room A",
"priority": 1,
"assignee": "meganb@contoso.com"
}
Nota:
Para poder encontrar elementos indexados en la interfaz de usuario de Búsqueda de Microsoft, un administrador debe personalizar la página de resultados de búsqueda para la correspondiente conexión.
Agregar actividades a un elemento
Para agregar actividades a un elemento, llame al punto de conexión addActivities , con el mismo identificador único para ese elemento en la dirección URL.
Por ejemplo, si alguien con Microsoft Entra ID 18948b93-d3ed-4307-9981-10fc36a08a52 ha comentado el vale del departamento de soporte técnico con el número SR00145 de incidencia el 11 de abril de 2022, a las 4:25 p. m., la solicitud para enviar esa actividad podría ser similar a la siguiente.
POST /external/connections/contosohelpdesk/items/SR00145/addActivities
Content-Type: application/json
"activities": [
{
"type": "commented",
"startDateTime": "2022-04-11T16:25:34.3202005Z",
"performedBy": {
"id": "18948b93-d3ed-4307-9981-10fc36a08a52",
"type": "user"
}
}
]
También puede agregar una actividad a un elemento en la misma solicitud que crea el elemento. Agregue la actividad como otra entidad, como acl y content. Si agrega una actividad de esta manera, incluya para @odata.type la actividad o se produce un error en la solicitud. Las actividades con marcas de tiempo de más de siete días no aparecen en la aplicación de Microsoft 365. Los usuarios finales solo pueden ver actividades en la aplicación de Microsoft 365 para los elementos a los que pueden acceder y tener una actividad (por ejemplo, compartidas con ellos, creadas y editadas).
Actualizar un elemento
Cuando se actualiza un elemento en el servicio externo (se vuelve a asignar el vale de soporte técnico o se actualiza una descripción de producto), puede actualizar su entrada en el índice si actualiza el elemento externalItem con el identificador único que se haya asignado al elemento al crearlo.
PATCH /external/connections/contosohelpdesk/items/SR00145
Content-Type: application/json
{
"assignee": "alexw@contoso.com"
}
Eliminar un elemento
Puede quitar elementos del índice si elimina el elemento externalItem con el identificador único que se haya asignado al elemento al crearlo.
DELETE /external/connections/contosohelpdesk/items/SR00145
Mantener los datos sincronizados
Tenga en cuenta la siguiente información al elegir cómo mantener los datos sincronizados:
Mecanismo de rastreo:
- Rastreo incremental: detecta e inserta adiciones en los datos de origen; menos rendimiento intensivo que un rastreo completo.
- Rastreo completo: Novedades todo el elemento de los datos de origen (volver a rastrear), capturando todas las adiciones y eliminaciones; garantiza una mejor precisión, pero consume más tiempo y consume más rendimiento que un rastreo incremental.
Intervalo de sincronización:
- Basado en eventos: inserta actualizaciones de elementos en función de eventos. Se recomienda usar este intervalo de sincronización para datos dinámicos o confidenciales, como el estado del elemento.
- Programado: inserta actualizaciones de elementos a intervalos regulares (cada N minutos). Se recomienda usar este intervalo de sincronización para datos enriquecidos en contenido o no confidenciales que se actualizan con menos frecuencia, como wikis o páginas web.
En última instancia, la elección de la estrategia de actualización de datos depende del tipo de datos y las funcionalidades informáticas.