Filtrar resultados com Scopes

Os Scopes no Microsoft Web IQ permitem-lhe ajustar finamente pedidos de API de grounding ao incluir ou excluir URLs, sites e domínios dos resultados Web Search, News Search e Auto.

Desenvolvedores e administradores empresariais podem usar Scopes para fundamentar experiências de IA em fontes web aprovadas e desejadas. Defina listas de inclusão e exclusão reutilizáveis para URLs, domínios e caminhos para controlar quais as fontes que as suas pesquisas de grounding podem devolver.

Um âmbito é uma configuração nomeada de regras de inclusão e exclusão. Crie-a no portal Web IQ ou na API de Gestão de Clientes para uma conta de faturação, depois selecione-a pelo nome nos pedidos Web Search, News Search ou Auto. Ambas as opções de gestão funcionam com os mesmos âmbitos nomeados. Estes escopos de pesquisa não são escopos de permissão Microsoft Entra OAuth.

Warning

Para Auto, os âmbitos restringem apenas os resultados Web e Notícias. Outros tipos de resposta não são filtrados pelo âmbito e podem conter resultados fora dele, mesmo quando scopeApplied é true.

Cenários empresariais e casos de uso comuns

Scenario Exemplo de caso de uso Como usar Scopes
Investigação selecionada Baseie um assistente de investigação em fontes analisadas pela sua organização, como publicações médicas aprovadas. Inclua os domínios aprovados, subdomínios ou páginas individuais.
Políticas organizativas de fontes Exclua os domínios restringidos pela sua organização dos resultados de fundamentação da Pesquisa na Web e da Pesquisa de Notícias. Mantenha uma lista de exclusão e selecione o âmbito em cada pedido.
Pesquisa em propriedades próprias Limite a experiência de pesquisa de um assistente de suporte ou destinada a colaboradores aos sites públicos do seu produto, ajuda ou sites da empresa. Inclua os domínios que possui e os caminhos de documentação relevantes.
Monitorização de notícias selecionadas Resumos de notícias baseados num conjunto selecionado de publicações. Inclua os domínios dos editores e selecione o âmbito nos pedidos de Pesquisa de Notícias.

Os escopos filtram o conteúdo disponível para o endpoint de pesquisa selecionado. Uma fonte incluída não garante que o conteúdo correspondente seja indexado ou devolvido.

Prerequisites

  • Uma conta de faturação Web IQ ativa.
  • Para criar escopos com a API, uma aplicação Microsoft Entra existente, o seu ID de inquilino e ID da aplicação (cliente), e credenciais para o fluxo de credenciais do cliente OAuth 2.0. A sua identidade de carga de trabalho deve estar ativa e ter CustomerApiAccess na conta de faturação Web IQ pretendida.

Important

O acesso às APIs de pesquisa e à API de gestão do Web IQ é concedido separadamente. Uma chave API de pesquisa funcional ou uma aplicação Entra vinculada a um perfil de execução Web IQ não concede permissão para criar escopos. A carga de trabalho necessita de uma permissão separada para gestão de contas de faturação.

Para verificar o acesso ao portal, abra Scopes e procure a conta de faturação pretendida e o controlo New scope. Se a página, conta ou controlo de criação não estiver disponível, peça ao administrador da sua conta para verificar o seu acesso, ou contacte o Suporte Web IQ.

Dê um nome ao seu âmbito e escolha as fontes

Escolha um nome do âmbito com até 128 caracteres após eliminar os espaços em branco. Os caracteres suportados são letras ASCII, dígitos, pontos (.), sublinhados (_) e hífens (-). Espaços e barras não são suportados. Os nomes são únicos sem distinção entre maiúsculas e minúsculas dentro da coleção de escopo.

Os scopes são partilhados pelos AppIDs Web IQ numa conta de faturação Web IQ, através da coleção de escopos atribuída a essa conta. Não são configurações separadas para cada AppID. Se as contas de faturação partilham uma coleção, partilham os mesmos âmbitos e nomes.

  • A inclusão limita os resultados a fontes que correspondam a pelo menos uma entrada na lista de inclusões do escopo. Se a lista estiver vazia, todas as fontes não excluídas são elegíveis.
  • A exclusão remove resultados que correspondam a qualquer entrada na lista de excluídos do âmbito, mesmo que também correspondam a uma regra de inclusão. A exclusão tem sempre prioridade.

Pode incluir ou excluir domínios, caminhos de URL ou páginas web individuais. Cada entrada é chamada seletor:

Selector Example Resultados
Domain example.com O domínio e os seus subdomínios descendentes
Prefixo do caminho docs.example.org/products O caminho especificado e os seus subcaminhos nesse hospedeiro, mas não caminhos como /products-old
URL exata https://docs.example.org/products/guide Esse URL HTTPS exato, não todas as páginas sob o caminho

Adicionar https:// faz com que um seletor corresponda a uma URL exata em vez de um prefixo de domínio ou caminho. Curingas como *.example.com, portas explícitas, cadeias de consulta e fragmentos não são suportadas. A capitalização do caminho é preservada. Os seletores de âmbito nomeado não têm limite separado para a profundidade do subdiretório, mas cada seletor deve caber dentro de 2.048 caracteres antes do corte e após a normalização.

A API normaliza, ordena e elimina duplicados nas entradas. Um seletor aceite não garante que o conteúdo correspondente seja indexado ou devolvido.

Crie um escopo no portal

  1. Abra Âmbitos no portal Web IQ.
  2. Selecione a conta de faturação pretendida.
  3. Selecione Novo âmbito. Em Criar novo âmbito, insira um nome do âmbito, como ProductDocs, e crie o âmbito.
  4. Na página de detalhes do escopo, use Adicionar sítios no separador Incluídos para adicionar fontes a incluir. Utilize o mesmo botão no separador Excluído para adicionar fontes a excluir, como ads.example.com.
  5. Revê ambas as listas, seleciona Publish e confirma Publicar alterações?.

Após a publicação, a propagação para pesquisa normalmente demora cerca de 10 minutos, mas pode demorar até 30 minutos em alguns casos. Verifique o âmbito de pesquisa antes de confiar nele na sua aplicação.

Selecione o escopo nos pedidos de pesquisa

Configura a autenticação de pesquisa em runtime separadamente. O perfil escolhido da aplicação Web IQ deve pertencer à conta de faturação Web IQ cuja coleção contém o seu escopo.

Defina os seguintes campos opcionais no corpo do pedido JSON para POST https://api.microsoft.ai/v3/search/web, POST https://api.microsoft.ai/v3/search/news, ou POST https://api.microsoft.ai/v3/auto. Os três endpoints usam as mesmas definições de escopo nomeado.

Parameter Tipo Behavior
scopeName cadeia (de caracteres) O nome de um scope existente, como ProductDocs. As regras de inclusão e exclusão filtram os resultados da solicitação. Para Auto, os âmbitos restringem apenas resultados Web e Notícias. Outros tipos de resposta não são filtrados pelo âmbito e podem conter resultados fora dele, mesmo quando scopeApplied é true. Se omitido ou null, não é solicitado nenhum âmbito nomeado.
failOnMissingScope boolean Por defeito, é true, incluindo quando omitido ou null. Quando true, uma falha reportada na aplicação do âmbito devolve um erro em vez de resultados sem âmbito. Quando false, a pesquisa pode prosseguir sem o escopo se este não puder ser aplicado. Use false apenas se os resultados sem âmbito forem aceitáveis. Não tem efeito sem scopeName.

Use uma chave API de runtime configurada separadamente nos exemplos seguintes.

Filtrar resultados de pesquisa web

Para pesquisar páginas web permitidas por ProductDocs, envie:

POST /v3/search/web HTTP/1.1
Host: api.microsoft.ai
x-apikey: <runtime-api-key>
Content-Type: application/json

{
  "query": "product setup guide",
  "scopeName": "ProductDocs",
  "failOnMissingScope": true,
  "maxResults": 10,
  "contentFormat": "passage",
  "maxLength": 3000
}

Filtrar Resultados de Pesquisa de Notícias

Para pesquisar artigos de notícias abrangidos pelo mesmo âmbito, use o endpoint de Pesquisa de Notícias. Escolha as fontes incluídas com conteúdo de notícias indexado; uma página web incluída não está necessariamente disponível através do News Search.

POST /v3/search/news HTTP/1.1
Host: api.microsoft.ai
x-apikey: <runtime-api-key>
Content-Type: application/json

{
  "query": "product announcements",
  "scopeName": "ProductDocs",
  "failOnMissingScope": true,
  "maxResults": 10,
  "contentFormat": "passage",
  "maxLength": 3000
}

Filtrar resultados Auto

Para Auto, os âmbitos restringem apenas resultados Web e Notícias. Outros tipos de resposta não são filtrados pelo âmbito e podem conter resultados fora dele, mesmo quando scopeApplied é true. Inclua responseFilter: ["web", "news"] se quiser apenas evidências da Web e das Notícias no âmbito definido:

POST /v3/auto HTTP/1.1
Host: api.microsoft.ai
x-apikey: <runtime-api-key>
Content-Type: application/json

{
  "query": "product setup guide",
  "scopeName": "ProductDocs",
  "failOnMissingScope": true,
  "mode": "lite",
  "responseFilter": ["web", "news"]
}

Interpretar os resultados

A Pesquisa Web devolve resultados em webResults, A Pesquisa de Notícias devolve resultados em newsResults, e o Auto devolve itens de evidência em results (AutoEvidenceResponse). Um âmbito válido não pode devolver resultados correspondentes, por exemplo, quando nenhum conteúdo indexado corresponde tanto à consulta como às regras do escopo.

Com failOnMissingScope: true (o predefinido), uma falha reportada na aplicação de âmbito devolve um erro em vez de resultados sem âmbito. Um âmbito cuja ausência foi confirmada devolve HTTP 400 (HandlerInvalidInput); outras falhas de aplicação de âmbito devolvem HTTP 500 (ScopeFailedToApply). Consulte erros de âmbito nomeado para orientações de recuperação.

Se definir failOnMissingScope para false e o âmbito não for encontrado, a pesquisa corre contra todo o índice sem o escopo, e a resposta contém "scopeApplied": false. Isto pode acontecer quando o nome está incorreto ou o âmbito ainda não foi propagado para a partição ou réplica que está a tratar do pedido.

Quando o âmbito solicitado é encontrado e aplicado, a resposta contém "scopeApplied": true, mesmo que failOnMissingScope seja false. Isto confirma a aplicação do âmbito desse pedido, não que a sua definição mais recente tenha sido usada ou que a alteração tenha chegado a todas as partições ou réplicas. A resposta omite scopeApplied quando não é reportado o resultado da candidatura; não trate uma propriedade ausente como prova de que o âmbito foi aplicado.

Se omitir scopeName ou definir para null, não é solicitado nenhum âmbito nomeado e failOnMissingScope não tem efeito. Não espere scopeApplied estar sempre presente com um valor de false para pedidos sem um âmbito nomeado.

Utilize false apenas se a sua aplicação puder aceitar resultados sem âmbito e verifique scopeApplied na resposta. Quando um escopo for necessário, não implemente uma alternativa que o remova e tente novamente um pedido sem restrições. Consulte as referências Web Search, News Search e Auto para os parâmetros do pedido e os campos de resposta.

Crie um âmbito com a API

Todos os pedidos de gestão usam https://api.microsoft.ai com os caminhos a começar por /v1/customer/. Substitua <billingAccountId> e <access-token> nos exemplos pelo ID da conta pretendido e um token de acesso apenas para aplicação. A referência de recursos autorizados e a referência de gestão do âmbito descrevem os contratos de endpoint.

Conceder acesso à API de gestão à aplicação

Um administrador de conta de faturação ou do cliente concede acesso:

  1. Utilize um registo de aplicação Microsoft Entra existente ou registe uma aplicação no portal do Azure.
  2. Abrir as definições da conta no portal Web IQ.
  3. Selecione a conta de faturação pretendida.
  4. Na secção de acesso à API de gestão, selecione Conceder acesso a uma aplicação Entra.
  5. No diálogo Conceder uma aplicação Entra aceder a esta conta de faturação , confirme o nome e o ID da conta de faturação. Insira o ID do inquilino da aplicação e o ID da Aplicação (cliente), e um valor não vazio para o nome de exibição necessário.
  6. Selecione Conceder a esta aplicação acesso à API de gestão, depois selecione Conceder acesso.

Conceder acesso autoriza uma identidade existente. Não cria uma aplicação Entra, segredo, certificado ou chave API de pesquisa. A concessão aplica-se à conta de faturação selecionada.

A concessão atribui a função CustomerApiAccess. Não é uma permissão apenas para scopes ou só leitura: permite a descoberta de contas, leituras e escritas de escopo, e gestão do Entra ID do perfil em tempo de execução. Não permite que a aplicação conceda acesso a outras aplicações. Limite a concessão a aplicações que necessitem destas capacidades de gestão.

Adquira um token exclusivo para aplicação

Use as credenciais existentes da sua aplicação e o fluxo de credenciais do cliente para solicitar um token de acesso Microsoft Entra:

Setting Value
Autoridade https://login.microsoftonline.com/<tenant-id>
Âmbito do pedido do token https://api.microsoft.ai/.default

Utilize o âmbito exato .default, não o nome do âmbito de pesquisa que está a criar. Envie o token em cada pedido de administração:

Authorization: Bearer <access-token>

Não utilize uma chave API de pesquisa para estas chamadas de gestão. Mantenha tokens de acesso e credenciais de aplicação fora do controlo de versões e dos relatórios de diagnóstico.

Descubra a conta de faturação

Faça a chamada a GET https://api.microsoft.ai/v1/customer/authorized-resources com o seu token exclusivo da aplicação. Selecione o billingAccounts[].billingAccountId da conta pretendida para o pedido de criação; não escolha automaticamente a primeira conta.

Utilize a referência de recursos autorizados para o esquema de resposta, definições de ID e interpretação do campo de permissões.

Envie o pedido de criação

Usando o ID de conta de faturação selecionado, envie POST /v1/customer/billing-accounts/{billingAccountId}/scopes com o nome do seu âmbito e regras. Por exemplo:

{
  "name": "ProductDocs",
  "includeSites": ["example.com", "docs.example.org/products"],
  "excludeSites": ["ads.example.com"]
}

Forneça ambos os arrays, usando [] para uma lista intencionalmente vazia. Em 201 Created, guarde a definição devolvida e ETag para alterações posteriores.

Para cabeçalhos, regras de validação e detalhes de resposta, consulte o contrato create-scope. Para alterar um escopo existente em vez de criar um novo, utilize as operações de atualização.

Verifica o âmbito antes de o usar

  1. Leia o escopo guardado e confirme se as suas regras correspondem às suas fontes pretendidas.
  2. Execute pedidos representativos de Web Search, News Search ou Auto com failOnMissingScope: true. Verifique os casos incluídos e excluídos antes de ativar o tráfego dependente.

Important

A propagação normalmente demora cerca de 10 minutos, mas pode demorar até 30 minutos em alguns casos. Não existe SLA de propagação, e estes tempos não são garantidos. Uma operação de escrita ou leitura de gestão bem-sucedida, Publicar ou scopeApplied: true não prova que a definição mais recente está ativa. Não use o tempo decorrido sozinho como teste de prontidão. Consulte search propagation para detalhes.

Implementar uma definição alterada

Se o uso temporário de uma definição anterior for inaceitável, crie um âmbito com um novo nome, como ProductDocs-v2. Conclua os passos de verificação acima antes de mudar de chamador e mantenha o âmbito anterior até que os chamadores deixem de depender dele.

Isto mantém o significado do nome antigo inalterado durante a validação; não fornece um comutador global atómico.

Preservar a proteção de concorrência para alterações futuras

Leia o escopo atual antes de o editar ou eliminar, e envie o seu ETag citado em If-Match. Siga orientações de concorrência e de resultados incertos ao conciliar edições simultâneas ou ao tentar novamente uma gravação. Mantém as definições revistas na tua própria fonte de verdade se precisares do histórico de alterações.

Resolução de problemas na criação

Se a conta pretendida estiver ausente da descoberta, peça ao administrador para verificar a identidade da carga de trabalho, a subvenção de gestão e a elegibilidade da conta. Para outras falhas, utilize a referência de estado de descoberta ou a referência de erro de gestão do âmbito.

Para falhas persistentes, contacte o Suporte Web IQ com o ID da conta de faturação, nome do âmbito, tempo de operação em UTC, estado HTTP e IDs de pedido disponíveis. Inclua comportamentos esperados e reais higienizados, nunca tokens, chaves API ou credenciais de aplicação.