Criar, atualizar e excluir itens adicionados por seu aplicativo via conectores do Microsoft Graph

Os conectores do Microsoft Graph oferecem uma maneira intuitiva de trazer dados externos para o Microsoft Graph. Os itens que seu aplicativo adiciona ao Microsoft serviço Pesquisa são representados pelo recurso externalItem no Microsoft Graph.

Depois de criar uma conexão, você pode adicionar seu conteúdo. Cada item da fonte de dados deve ser representado como um externalItem no Microsoft Graph com uma ID de item exclusiva. Essa ID é usada para criar, atualizar ou excluir o item do Microsoft Graph. Você pode usar a chave primária de sua fonte de dados como a ID do item ou derivá-la de um ou mais campos.

Componentes principais

Um externalItem possui três componentes principais: lista de controle de acesso, propriedades e conteúdo.

Lista de controle de acesso

A lista de controle de acesso (ACL) é usada para especificar se as funções fornecidas têm acesso concedido ou negado para exibir itens nas experiências da Microsoft. A ACL é uma matriz de entradas de controle de acesso que representa um Microsoft Entra usuário ou grupo. Um terceiro tipo de entrada de controle de acesso Everyone representa todos os usuários no locatário.

Um exemplo de lista de controle de acesso.

O valor accessTypedeny tem precedência sobre grant. Por exemplo, no item mostrado acima, enquanto Everyone recebe o acesso e um usuário específico tem negado o acesso, a permissão efetiva desse usuário é deny.

Se sua fonte de dados tiver grupos do AD não Azure (como equipes em seu sistema de suporte técnico) usados para definir permissões para o item, você poderá criar grupos externos no Microsoft Graph usando as APIs de sincronização de grupo para replicar as permissões allow ou deny. Evite expandir a associação de seus grupos externos diretamente nas ACLs de itens individuais, pois cada associação de grupo pode levar a um alto volume de atualizações de itens.

Grupos externos incluem outro grupo, Microsoft Entra usuários e grupos de Microsoft Entra. Se você tiver usuários não Azure AD, você deve traduzi-los para usuários Microsoft Entra em sua ACL.

Propriedades

O componente propriedades é usado para adicionar metadados de itens que são úteis nas experiências do Microsoft Graph. Você deve registrar o esquema para a conexão antes de adicionar itens a ele e converter os tipos de dados em tipos de dados com suporte.

Um componente de propriedade de exemplo.

Conteúdo

O componente de conteúdo adiciona a maior parte do item que precisa ser indexado em texto completo. Os exemplos incluem uma descrição de tíquete, texto analisado de um corpo de arquivo ou um corpo de página wiki.

O conteúdo é um dos principais campos que influenciam na relevância nas experiências da Microsoft. Os tipos de conteúdo text e html são suportados. Se sua fonte de dados tiver outros tipos de conteúdo, como arquivos binários, vídeos ou imagens, você poderá analisá-los em texto antes de adicioná-los ao Microsoft Graph. Por exemplo, o reconhecimento óptico de caracteres pode extrair texto pesquisável de imagens.

Importante

A solução de conformidade só dá text suporte para o tipo de conteúdo. Se você habilitar a conexão para conformidade definindo a propriedade enableedContentExperience como compliance, você deverá ingerir conteúdo em formato de texto simples e definir o tipo de conteúdo como text.

Um exemplo de um componente de conteúdo.

O conteúdo não pode ser adicionado diretamente a um modelo de resultado de pesquisa, mas você pode usar um snippet de resultado gerado, que é uma visualização gerada dinamicamente das seções relevantes dentro do conteúdo.

Um modelo de resultado de pesquisa.

Quando o conteúdo da fonte de dados é alterado, você deve sincronizá-lo com seus itens de conexão. Você pode atualizar o item inteiro ou um ou mais componentes. Depois de adicionar seu conteúdo ao Microsoft Graph, você pode pesquisá-lo por meio da experiência do Microsoft Pesquisa depois de configurar verticais de pesquisa e tipos de resultado ou usando o Microsoft Graph Pesquisa API.

Atividades

O componente de atividades é uma propriedade transitória que envia atividades no item. Você só pode gravar nesta propriedade.

Uma atividade consiste em um ator (que realizou a atividade), um tempo (quando a atividade foi executada) e um tipo de atividade (que tipo de atividade foi executada). Os tipos de atividade com suporte no momento podem ser encontrados na seção Descrição da propriedade type para uma externalActivity.

O envio de atividades no item alimenta experiências de recomendação inteligentes no Microsoft 365. Os usuários finais podem receber conteúdo personalizado para eles com base nas atividades enviadas.

Adicionar um item

Para adicionar um item ao índice, você cria um externalItem. Ao criar um item, você atribui um identificador exclusivo na URL.

Por exemplo, seu aplicativo pode indexar tíquetes de assistência técnica usando o número do tíquete. Se um ticket tiver o número do tíqueteSR00145, a solicitação poderá ter a seguinte aparência:

PUT /external/connections/contosohelpdesk/items/SR00145
Content-Type: application/json

"properties": {
  "title": "WiFi outage in Conference Room A",
  "priority": 1,
  "assignee": "meganb@contoso.com"
}

Observação

Antes que os itens indexados possam ser encontrados na interface do usuário do Microsoft Search, um administrador deve personalizar a página de resultados da pesquisa para a conexão correspondente.

Adicionar atividades a um item

Para adicionar atividades a um item, você chama o ponto de extremidade addActivities , com o mesmo identificador exclusivo para esse item na URL.

Por exemplo, se alguém com Microsoft Entra ID 18948b93-d3ed-4307-9981-10fc36a08a52 comentou sobre o tíquete auxiliar com o número SR00145 do tíquete em 11 de abril de 2022, às 16h25, a solicitação para enviar essa atividade poderá se parecer com a seguinte.

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"
    }
  }
]

Você também pode adicionar uma atividade a um item na mesma solicitação que cria o item. Adicione a atividade como outra entidade, como acl e content. Se você adicionar uma atividade dessa forma, inclua a @odata.type para a atividade ou a solicitação falhará. Atividades com carimbos de data/hora com mais de sete dias não aparecem no aplicativo Microsoft 365. Os usuários finais só podem ver atividades no aplicativo Microsoft 365 para itens que podem acessar e ter uma atividade (por exemplo, compartilhada com eles, criada, editada e assim por diante).

Atualizar um item

Quando um item é atualizado no serviço externo (o tíquete de assistência técnica é reatribuído ou uma descrição do produto é atualizada), você pode atualizar sua entrada no índice atualizando o externalItem, usando o identificador exclusivo atribuído ao item quando você o criou.

PATCH /external/connections/contosohelpdesk/items/SR00145
Content-Type: application/json

{
  "assignee": "alexw@contoso.com"
}

Excluir um item

Para remover itens do índice, exclua o externalItem, usando o identificador exclusivo atribuído ao item quando você o criou.

DELETE /external/connections/contosohelpdesk/items/SR00145

Manter seus dados em sincronização

Considere as seguintes informações ao escolher como manter seus dados em sincronização:

Mecanismo de rastreamento:

• Rastreamento incremental: detecta e empurra adições nos dados de origem; menos intensivo em desempenho do que um rastreamento completo.
• Rastreamento completo: Atualizações o item inteiro dos dados de origem (reatualização), capturando todas as adições e exclusões; garante melhor precisão, mas é mais demorado e intensivo em desempenho do que um rastreamento incremental.

Intervalo de sincronização:

• Baseado em eventos: empurra atualizações de item em uma base de evento. Recomendamos que você use esse intervalo de sincronização para dados dinâmicos ou confidenciais, como status de item.
• Agendado: empurra atualizações de item em intervalos regulares (a cada N minutos). Recomendamos que você use esse intervalo de sincronização para dados ricos em conteúdo ou não confidenciais que são atualizados com menos frequência, como wikis ou páginas da Web.

Em última análise, a escolha da estratégia de atualização de dados depende do tipo de dados e dos recursos de computação.

Próximos passos

• Usar grupos externos para gerenciar permissões
• Consulta usando a API de Pesquisa da Microsoft
• Revisar a referência da API do conectores do Microsoft Graph
• Pesquisar tipos personalizados (externalItem)
• Baixar o conector de pesquisa de exemplo do GitHub