Criar, atualizar e excluir conexões no Microsoft Graph

A plataforma de conectores do Microsoft Graph oferece uma maneira intuitiva de adicionar seus dados externos ao Microsoft Graph. Uma conexão é um contêiner lógico de dados externos que um administrador pode gerenciar como uma única unidade.

Após uma conexão ter sido criada, você pode adicionar seu conteúdo de qualquer fonte de dados externa, como uma fonte de conteúdo local ou um serviço SaaS externo. Só é possível exibir e gerenciar as conexões que você criou ou que foram explicitamente autorizadas para gerenciamento. Um administrador de pesquisa pode exibir e gerenciar todas as conexões no locatário no Centro de Administração Moderna.

Amostra de um sistema de assistência técnica personalizado da Estrutura de Conector de Tíquetes.

Modo de exibição de administrador das conexões, incluindo o Conector de Tíquetes personalizado.

Você pode modelar uma conexão da maneira que quiser mas criar uma conexão para cada instância do seu conector é o modelo mais comum. Por exemplo, cada vez que você configurar o conector de compartilhamento de arquivos do Microsoft Windows, uma nova conexão é criada. Você também pode criar uma única conexão para adicionar todos os itens da fonte de dados. Por exemplo, v pode criar uma única conexão para adicionar todos os tíquetes e incidentes em várias equipes a partir de seu sistema de assistência técnica.

Estados e operações

A conexão pode existir em um dos seguintes estados.

Estado	Descrição
Rascunho	É fornecida uma conexão vazia. Nenhuma fonte de dados, esquema ou configurações está configurada.
Pronto	A conexão é fornecida com o esquema registrado e está pronta para inclusão.
Obsoleto	Isso ocorre quando um recurso dependente, como uma API, foi preterido. A exclusão da conexão é a única operação válida.
LimitExceeded	Se você atingir o limite máximo de uma única conexão ou a cota de nível de locatário em todas as conexões, não poderá adicionar mais itens até sair do estado.

A tabela a seguir especifica quais operações estão disponíveis em cada Estado.

Operação	Rascunho	Pronto	Obsoleto	LimitExceeded
Criar conexão	❌	✔️	❌	✔️
Ler conexão	✔️	✔️	✔️	✔️
Atualizar conexão	✔️	✔️	❌	✔️
Excluir conexão	✔️	✔️	✔️	✔️
Criar esquema	✔️	❌	❌	❌
Ler esquema	❌	✔️	✔️	✔️
Atualizar esquema	❌	❌	❌	❌
Excluir esquema	❌	❌	❌	❌
Criar item	❌	✔️	❌	❌
Ler item	❌	✔️	✔️	✔️
Atualizar item	❌	✔️	❌	✔️
Excluir item	❌	✔️	❌	✔️

Uma conexão permite que seu aplicativo defina um esquema para os itens que serão indexados, e que ele forneça um ponto de extremidade para o seu serviço adicionar, atualizar ou excluir itens do índice.

Criar uma conexão é a primeira etapa para um aplicativo para adicionar itens ao índice de pesquisa.

Criar uma conexão

Antes que um aplicativo possa adicionar itens ao índice de pesquisa, ele deve criar e configurar uma conexão:

1. Criar uma conexão com ID exclusiva, nome de exibição e descrição.
2. Registre um esquema para definir os campos que serão incluídos no índice.

   Nota: Para obter informações sobre como atualizar o esquema para uma conexão existente, consulte Funcionalidades de atualização de esquema.

Configurações de conexão

Você pode configurar as configurações de conexão padrão para cada experiência de conteúdo habilitada. Quando habilitadas, essas configurações afetam as experiências de conteúdo.

Configurações de pesquisa

Você pode definir como os resultados da pesquisa são exibidos na página de resultados do Microsoft Pesquisa fornecendo os modelos de exibição de pesquisa padrão para seu conteúdo em searchSettings. Um conjunto de modelos de exibição de pesquisa pode ser usado para exibir diferentes tipos de resultados de pesquisa. Um modelo de exibição de pesquisa tem um layout de resultado criado usando Cartões Adaptáveis e regras que especificam uma ou mais condições. Quando essas condições são atendidas, o layout é aplicado ao resultado da pesquisa e exibido na página de resultados.

Configurações de atividade

Nas configurações de atividade, você pode fornecer uma maneira de os aplicativos do Microsoft 365 detectarem a atividade de compartilhamento, o que permite que seu conteúdo seja recomendado para usuários que interagem mais com esse conteúdo. Para fazer isso, adicione um urlToItemResolver. Isso permite que uma URL da conexão detectada nos aplicativos do Microsoft 365 seja resolvida para sua respectiva ID de item no externalItem.

A imagem a seguir mostra como seu item pode aparecer em experiências de recomendação no Microsoft 365.

O exemplo a seguir mostra a carga activitySettings com uma seção urlToItemResolvers completa. Por exemplo, quando alguém compartilha o link https://contoso.com/items/39483948/, ele representa um externalItem que foi ingerido por meio de uma conexão do Microsoft Graph. Neste exemplo, o link compartilhado representa um externalItem com um itemId de id_39483948. Essa conexão especifica como mapear da URL para o itemId desse externalItem. Neste exemplo, essa conexão tem uma ID de contosohr.

Atualize as configurações de atividade enviando uma solicitação de patch na conexão.

PATCH https://graph.microsoft.com/v1.0/external/connections/contosohr

A carga de atividades a seguirSettings é enviada com a solicitação de patch.

{
  "@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]+)"
          }
    }
  ]
}

Neste exemplo, o campo itemId especificou como formar a ID do item externo que a URL representa. O itemId é referenciado em urlPattern (que está dentro de urlMatchInfo) para extrair 39483948 como a ID do externalItem.

Você pode fornecer uma lista de até oito recursos itemIdResolver no recurso urlToItemResolvers para o conteúdo das configurações de atividade. Para cada um desses recursos urlMatchInfo , especifique um valor do #microsoft.graph.externalConnectors.itemIdResolver@odata.type, um inteiro de um a oito para a propriedade prioritária e um objeto urlMatchInfo que contém uma lista de URLs base e uma expressão regular.

Quando um link é compartilhado, os objetos urlMatchInfo que pertencem aos resolvedores são aplicados na ordem especificada pelos valores de prioridade . Em ordem de prioridade crescente, a URL é primeiramente comparada às URLs na lista baseUrls na propriedade urlMatchInfo . Em seguida, se a base da URL do link estiver na lista baseUrls , a expressão regular urlPattern será aplicada à URL. Se esse padrão corresponder, nenhum resolvedor adicional será aplicado. Se a base da URL de link não estiver na lista baseUrls ou a urlPattern não corresponder, o próximo urlToItemResolver será avaliado até que uma correspondência seja encontrada ou não haja mais recursos urltoItemResolver a serem aplicados.

Para saber mais sobre os recursos urlMatchInfo , consulte tipo urlMatchInfo.

Atualizar uma conexão

Para alterar o nome de exibição, a descrição ou as experiências de conteúdo habilitadas para uma conexão existente, você pode atualizar a conexão.

Excluir uma conexão

Para remover todos os itens que foram indexados por meio de uma conexão, você pode excluir uma conexão.

Próximas etapas

• Registrar o esquema de conexão
• Revisar a referência da API do conectores do Microsoft Graph
• Baixar o modelo do conector de pesquisa do GitHub