Criar, atualizar e excluir itens em uma conexão do Microsoft Graph

Os conectores do Microsoft 365 Copilot (anteriormente conectores do Microsoft Graph) oferecem uma maneira intuitiva de trazer dados externos para o Microsoft Graph. Os itens que seu aplicativo adiciona ao serviço Pesquisa da Microsoft 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 usuário ou grupo do Microsoft Entra. 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.

Os grupos externos incluem outro grupo, usuários do Microsoft Entra e grupos do Microsoft Entra. Se você tiver usuários que não são do Azure AD, deverá convertê-los para usuários do 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 como 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.

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 trecho 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 de Pesquisa da Microsoft depois de configurar as verticais de pesquisa e os tipos deresultados ou usando a API de Pesquisa do Microsoft Graph.

Atividades

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

Uma atividade consiste em um ator (que executou a atividade), uma hora (em que 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 de uma externalActivity.

O envio de atividades no item potencializa experiências de recomendação inteligente 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"
}

Adicionar atividades a um item

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

Por exemplo, se alguém com o Microsoft Entra ID 18948b93-d3ed-4307-9981-10fc36a08a52 comentou no tíquete do suporte técnico com o número SR00145 do tíquete em 11 de abril de 2022, às 16h25, a solicitação para enviar essa atividade pode ser semelhante à 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 maiores que sete dias não são exibidas no aplicativo Microsoft 365. Os usuários finais só podem ver atividades no aplicativo Microsoft 365 para itens que podem acessar e nos quais têm atividade (por exemplo, compartilhados com eles, criados e editados).

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

Mantenha seus dados em sincronia

Considere as seguintes informações ao escolher como manter os dados em sincronia:

Mecanismo de rastreamento:

• Rastreamento incremental: detecta e envia adições nos dados de origem; Menos desempenho intensivo do que um rastreamento completo.
• Rastreamento completo: Atualizações todo o item dos dados de origem (rastreamento novamente), 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: envia atualizações de itens com base em eventos. Recomendamos que você use esse intervalo de sincronização para dados dinâmicos ou confidenciais, como o status do item.
• Agendado: envia atualizações de itens 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 seu tipo de dados e 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 de conectores do Copilot
• Pesquisar tipos personalizados (externalItem)
• Baixar o conector de pesquisa de exemplo do GitHub