Criar, atualizar e excluir itens em uma conexão do Microsoft Graph
Os conectores do Microsoft Graph oferecem uma maneira intuitiva de trazer dados externos para o Microsoft Graph. Os itens que a sua aplicação 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 controlo de acesso que representam um utilizador ou grupo 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, Microsoft Entra utilizadores e grupos de Microsoft Entra. Se tiver utilizadores não Azure AD, tem de os traduzir para Microsoft Entra utilizadores na 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 tem de 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 ótico de carateres pode extrair texto pesquisável de imagens.
Importante
A solução de conformidade só suporta text o tipo de conteúdo. Se ativar a ligação para conformidade ao definir a propriedade enabledContentExperience como compliance, deve 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.
Os conteúdos não podem ser adicionados diretamente a um modelo de resultados de pesquisa, mas pode utilizar um fragmento de resultado gerado, que é uma pré-visualização gerada dinamicamente das secções relevantes no 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. Pode atualizar todo o item ou um ou mais componentes. Depois de adicionar os seus conteúdos ao Microsoft Graph, pode procurá-lo através da experiência microsoft Search depois de configurar verticais de pesquisa e tipos de resultados ou através da API de Pesquisa do Microsoft Graph.
Atividades
O componente atividades é uma propriedade transitória que envia atividades no item. Só pode escrever nesta propriedade.
Uma atividade consiste num ator (que realizou a atividade), numa hora (em que a atividade foi realizada) e num tipo de atividade (que tipo de atividade foi realizada). Os tipos de atividade atualmente suportados podem ser encontrados na secção Descrição da propriedade do tipo para uma externalActivity.
O envio de atividades no item alimenta as experiências de recomendação inteligentes no Microsoft 365. Os utilizadores finais podem receber conteúdo adaptado aos mesmos com base nas atividades que são 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, chame o ponto final addActivities , com o mesmo identificador exclusivo desse item no URL.
Por exemplo, se alguém com Microsoft Entra ID 18948b93-d3ed-4307-9981-10fc36a08a52 comentou o pedido de suporte técnico com o número SR00145 do pedido no dia 11 de abril de 2022, às 16:25, o pedido para enviar essa atividade poderá ter o seguinte aspeto.
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"
}
}
]
Também pode adicionar uma atividade a um item no mesmo pedido que cria o item. Adicione a atividade como outra entidade, como acl e content. Se adicionar uma atividade desta forma, inclua o @odata.type para a atividade ou o pedido falhar. As atividades com carimbos de data/hora com mais de sete dias não aparecem na aplicação Microsoft 365. Os utilizadores finais só podem ver atividades na aplicação Microsoft 365 para itens aos quais podem aceder e ter uma atividade ativada (por exemplo, partilhadas com eles, criadas e editadas).
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 os seus dados sincronizados
Considere as seguintes informações quando escolher como manter os seus dados sincronizados:
Mecanismo de pesquisa:
- Pesquisa incremental: deteta e envia adições nos dados de origem; menos desempenho intensivo do que uma pesquisa completa.
- Pesquisa completa: Atualizações todo o item a partir dos dados de origem (pesquisa nova), capturando todas as adições e eliminações; garante uma maior precisão, mas é mais morosa e intensiva em termos de desempenho do que uma pesquisa incremental.
Intervalo de sincronização:
- Baseado em eventos: envia atualizações de itens numa base de evento. Recomendamos que utilize este intervalo de sincronização para dados dinâmicos ou confidenciais, como status de itens.
- Agendado: envia atualizações de itens em intervalos regulares (a cada N minutos). Recomendamos que utilize este 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 Web.
Em última análise, a escolha da estratégia de atualização de dados depende do tipo de dados e das capacidades de computação.