Criar, atualizar e excluir conexões no Microsoft Graph

Os conectores do Microsoft 365 Copilot oferecem 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.

Depois que uma conexão é criada, você pode adicionar seu conteúdo de qualquer fonte de dados externa, como uma fonte de conteúdo local ou um serviço externo de software como serviço (SaaS). 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 por meio da seçãoAgentes e conectores do Copilot> no Centro de administração do Microsoft 365.

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.

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

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.

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

Configurações da conexão

Você pode definir 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 na Pesquisa da Microsoft e no Microsoft 365 Copilot.

Configurações de atividade

Activity settings](/graph/api/resources/externalconnectors-activitysettings)rovide os metadados de mapeamento de URL para ExternalItem que permitem ao Microsoft 365 reconhecer que um URL corresponde a um item indexado específico em uma conexão de conector do Copilot.

• Resolução de URL em experiências do Microsoft 365

  • Quando um usuário pesquisa, cola ou compartilha uma URL em experiências do Microsoft 365, como a Pesquisa da Microsoft ou o Microsoft 365 Copilot, o Microsoft 365 pode usar o configurado urlToItemResolvers para resolver a URL para o arquivo .externalItem Isso permite que o Microsoft 365 identifique o item indexado representado pela URL e associe as interações detectadas ao item externo correto.

• Captura de Sinal de Atividade por meio da Extensão do Microsoft 365 Copilot

  • Os sinais de atividade podem ser capturados usando a extensão do Microsoft 365 Copilot, uma extensão baseada em navegador para o Microsoft 365 Copilot. Quando as configurações de atividade são definidas e a extensão está habilitada, a extensão pode capturar automaticamente sinais de atividade e associá-los a itens de conector indexados. Esses sinais ajudam a melhorar a personalização e a relevância no Microsoft 365 Copilot priorizando o conteúdo com o qual os usuários se envolvem em sistemas conectados.

As configurações de atividade fornecem o mapeamento de URL para item necessário para que esses sinais sejam associados ao item indexado correto. 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 nas experiências de recomendação no Microsoft 365.

O exemplo a seguir mostra o conteúdo 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, esta 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

O conteúdo activitySettings a seguir é enviado com a solicitação do 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 de configurações de atividade. Para cada um desses recursos urlMatchInfo , especifique um valor de #microsoft.graph.externalConnectors.itemIdResolver para , @odata.typeum inteiro de um a oito para a propriedade priority e um objeto urlMatchInfo que contenha 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 crescente de prioridade , a URL é primeiro 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 outro resolvedor será aplicado. Se a base da URL do link não estiver na lista baseUrls ou o 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 urlMatchInfo type.

Configurações de pesquisa

Você pode definir como os resultados da pesquisa são exibidos na página de resultados da Pesquisa da Microsoft, fornecendo os modelos de exibição de pesquisa padrão para o seu conteúdo em searchSettings. Um conjunto de modelos de exibição de pesquisa pode ser usado para exibir tipos distintos de resultados de pesquisa de maneira diferente. Um modelo de exibição de pesquisa tem um layout de resultados 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.

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.

Conteúdo relacionado

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