Filtrar resultados com escopos

Os escopos no Microsoft Web IQ permitem ajustar solicitações à API de grounding incluindo ou excluindo URLs, sites e domínios da Pesquisa na Web, Pesquisa de Notícias e resultados do Auto.

Desenvolvedores e administradores corporativos podem usar Escopos para basear experiências de IA em fontes da Web aprovadas e desejadas. Defina listas de inclusão e exclusão reutilizáveis para URLs, domínios e caminhos para controlar quais fontes suas pesquisas de grounding podem retornar.

Um escopo é uma configuração nomeada de regras de inclusão e exclusão. Crie-o no portal Web IQ ou na Customer Management API para uma conta de cobrança e selecione-o pelo nome em suas solicitações de Web Search, News Search ou Auto. Ambas as opções de gerenciamento funcionam com os mesmos escopos nomeados. Esses escopos de pesquisa não são Microsoft Entra escopos de permissão OAuth.

Warning

Para o Auto, os escopos restringem apenas os resultados da Web e do News. Outros tipos de resposta não são filtrados pelo escopo e podem conter resultados fora dele, mesmo quando scopeApplied é true.

Cenários de negócios e casos de uso comuns

Scenario Exemplo de caso de uso Como usar Scopes
Pesquisa selecionada Baseie um assistente de pesquisa em fontes revisadas por sua organização, como publicações médicas aprovadas. Inclua os domínios aprovados, subdomínios ou páginas individuais.
Políticas de origem da organização Exclua domínios restritos por 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 escopo em cada solicitação.
Pesquisa em propriedades próprias Limite um assistente de suporte ou uma experiência de pesquisa voltada para funcionários ao seu produto público, sites de ajuda ou sites da empresa. Inclua seus domínios próprios e caminhos de documentação relevantes.
Monitoramento de notícias com curadoria Baseie os resumos de notícias em um conjunto selecionado de publicadores. Inclua os domínios dos veículos e selecione o escopo em solicitações de Pesquisa de Notícias.

Escopos filtram o conteúdo disponível para o ponto de extremidade de pesquisa selecionado. Uma fonte incluída não garante que o conteúdo correspondente seja indexado ou retornado.

Prerequisites

  • Uma conta de cobrança ativa do Web IQ.
  • Para criar escopos com a API, são necessários um aplicativo Microsoft Entra existente, sua ID de locatário e a ID do aplicativo (cliente), além de credenciais para o fluxo de credenciais do cliente OAuth 2.0. Sua identidade de carga de trabalho deve estar ativa e ter CustomerApiAccess na conta de cobrança pretendida do Web IQ.

Importante

O acesso às APIs de pesquisa e à API de gerenciamento do Web IQ é concedido separadamente. Uma chave de API de pesquisa funcional ou um aplicativo Entra associado a um perfil de runtime de IQ da Web não concede permissão para criar escopos. A carga de trabalho precisa de uma concessão de gerenciamento de conta de cobrança separada.

Para verificar o acesso ao portal, abra Escopos e procure a conta de cobrança pretendida e o controle Novo escopo. Se a página, a conta ou o controle de criação não estiverem disponíveis, peça ao administrador da conta para verificar o acesso ou entre em contato com o Suporte de Perguntas Frequentes da Web.

Nomeie seu escopo e escolha origens

Escolha um nome de escopo com até 128 caracteres após remover espaços. Os caracteres com suporte são letras ASCII, dígitos, períodos (.), sublinhados (_) e hifens (-). Não há suporte para espaços e barras. Os nomes são exclusivos na coleção de escopo, sem diferenciar maiúsculas de minúsculas.

Os escopos são compartilhados pelos AppIDs do Web IQ em uma conta de cobrança do Web IQ, por meio da coleção de escopo atribuída a essa conta. Elas não são configurações separadas para cada AppID. Se as contas de cobrança compartilharem uma coleção, elas compartilharão os mesmos escopos e nomes.

  • A inclusão limita os resultados a fontes que correspondem a pelo menos uma entrada na lista de inclusões do escopo. Se a lista estiver vazia, todas as fontes não excluídas serão qualificadas.
  • A exclusão remove resultados que correspondem a qualquer entrada na lista excluída do escopo, mesmo que eles também correspondam a uma regra de inclusão. A exclusão sempre tem precedência.

Você pode incluir ou excluir domínios, caminhos de URL ou páginas da Web individuais. Cada entrada é chamada de seletor:

Seletor Example Partidas
Domínio example.com O domínio e seus subdomínios descendentes
Prefixo do caminho docs.example.org/products O caminho especificado e seus subcaminhos nesse host, mas não caminhos como /products-old
URL exata https://docs.example.org/products/guide Essa URL HTTPS exata, não todas as páginas sob esse caminho

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

A API normaliza, classifica e elimina entradas duplicadas. Um seletor aceito não garante que o conteúdo correspondente seja indexado ou retornado.

Criar um escopo no portal

  1. Abra Escopos no portal Web IQ.
  2. Selecione a conta de cobrança pretendida.
  3. Selecione Novo escopo. Em Criar novo escopo, insira um nome de escopo, como ProductDocs, e crie o escopo.
  4. Na página de detalhes do escopo, use Adicionar sites na guia Incluídos para adicionar fontes a serem incluídas. Use o mesmo botão na guia Excluído para adicionar fontes a serem excluídas, como ads.example.com.
  5. Revise ambas as listas, selecione Publicar e confirme Publicar alterações?.

Após a publicação, a propagação para pesquisa geralmente leva cerca de 10 minutos, mas pode levar até 30 minutos em alguns casos. Verifique o escopo antes de confiar nele em seu aplicativo.

Selecione o escopo em solicitações de pesquisa

Configure autenticação de pesquisa de runtime separadamente. O perfil de aplicativo web IQ escolhido deve pertencer à conta de cobrança de Qi da Web cuja coleção contém seu escopo.

Defina os seguintes campos opcionais no corpo da solicitação JSON para POST https://api.microsoft.ai/v3/search/web, POST https://api.microsoft.ai/v3/search/newsou POST https://api.microsoft.ai/v3/auto. Todos os três pontos de extremidade usam as mesmas configurações de escopo nomeado.

Parameter Tipo Behavior
scopeName cadeia O nome de um escopo existente, como ProductDocs. Suas regras de inclusão e exclusão filtram os resultados da solicitação. Para o Auto, os escopos restringem apenas os resultados da Web e do News. Outros tipos de resposta não são filtrados pelo escopo e podem conter resultados fora dele, mesmo quando scopeApplied é true. Se omitido ou null, nenhum escopo nomeado é solicitado.
failOnMissingScope boolean O padrão é true, incluindo quando omitido ou null. Quando true, uma falha relatada na aplicação do escopo retorna um erro em vez de resultados sem escopo. Quando false, a pesquisa poderá continuar sem o escopo se ele não puder ser aplicado. Use false somente se os resultados sem escopo forem aceitáveis. Não tem efeito sem scopeName.

Use uma chave de API de runtime configurada separadamente nos exemplos a seguir.

Filtrar resultados da Pesquisa na Web

Para pesquisar páginas da 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 da Pesquisa de Notícias

Para pesquisar artigos de notícias permitidos pelo mesmo escopo, use o endpoint do News Search. Escolha fontes incluídas com conteúdo de notícias indexado; uma página da Web incluída não está necessariamente disponível por meio da Pesquisa de Notícias.

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 o Auto, os escopos restringem apenas os resultados da Web e do News. Outros tipos de resposta não são filtrados pelo escopo e podem conter resultados fora dele, mesmo quando scopeApplied é true. Inclua responseFilter: ["web", "news"] se você quiser apenas as evidências da Web e do News no escopo:

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 na Web retorna resultados em webResults, a Pesquisa de Notícias retorna resultados em newsResults, e o Auto retorna itens de evidência em results (AutoEvidenceResponse). Um escopo válido não pode retornar resultados correspondentes, por exemplo, quando nenhum conteúdo indexado corresponde à consulta e às regras do escopo.

Com failOnMissingScope: true (o padrão), uma falha relatada na aplicação do escopo retorna um erro em vez de resultados sem escopo. Um escopo ausente confirmado retorna HTTP 400 (HandlerInvalidInput); outras falhas na aplicação do escopo retornam HTTP 500 (ScopeFailedToApply). Consulte erros de escopo nomeado para obter diretrizes de recuperação.

Se você definir failOnMissingScopefalse e o escopo não puder ser encontrado, a pesquisa será executada em todo o índice sem o escopo e a resposta conterá "scopeApplied": false. Isso pode acontecer quando o nome está incorreto ou o escopo ainda não foi propagado para a partição ou réplica que está tratando a solicitação.

Quando o escopo solicitado é encontrado e aplicado, a resposta contém "scopeApplied": true, mesmo que failOnMissingScope seja false. Isso confirma a aplicação do escopo dessa solicitação, não que sua definição mais recente tenha sido usada ou que a alteração atingiu todas as partições ou réplicas. A resposta omite scopeApplied quando nenhum resultado do aplicativo é relatado; não trate uma propriedade ausente como prova de que o escopo foi aplicado.

Se você omitir scopeName ou defini-lo como null, nenhum escopo nomeado será solicitado e failOnMissingScope não terá efeito. Não espere que scopeApplied esteja sempre presente com um valor de false em solicitações sem um escopo nomeado.

Use somente false se o aplicativo puder aceitar resultados sem escopo e verificar scopeApplied na resposta. Quando um escopo for necessário, não implemente um fallback que o remova e tente novamente uma solicitação irrestrita. Consulte as referências de Pesquisa na Web, Pesquisa de Notícias e Auto para os parâmetros de solicitação e campos de resposta.

Criar um escopo com a API

Todas as solicitações de gerenciamento usam https://api.microsoft.ai com caminhos começando com /v1/customer/. Substitua <billingAccountId> e <access-token> , nos exemplos, pela ID da conta pretendida e por um token de acesso somente aplicativo. A referência de recursos autorizados e a referência de gerenciamento de escopo descrevem os contratos de endpoint.

Conceder acesso à API de gerenciamento ao aplicativo

Um administrador de conta de cobrança ou cliente concede acesso:

  1. Use um registro de aplicativo Microsoft Entra existente ou registre um aplicativo no portal Azure.
  2. Abra as configurações da conta no portal Web IQ.
  3. Selecione a conta de cobrança pretendida.
  4. Em Acesso à API de Gerenciamento, selecione Conceder acesso a um aplicativo Entra.
  5. Na caixa de diálogo Conceder acesso deste aplicativo Entra a esta conta de cobrança, confirme o nome e o ID da conta de cobrança. Insira o ID do locatário e o ID do Aplicativo (cliente) do aplicativo, e um valor não vazio para o nome de exibição necessário.
  6. Selecione Conceder acesso à API de gerenciamento a este aplicativo e, em seguida, selecione Conceder acesso.

A concessão de acesso autoriza uma identidade existente. Ele não cria um aplicativo Entra, um segredo, um certificado ou uma chave de API de pesquisa. A concessão se aplica à conta de cobrança selecionada.

A concessão atribui a CustomerApiAccess função. Não é uma permissão somente para escopos ou somente leitura: permite a descoberta da conta, leituras e gravações de escopo e o gerenciamento de Entra ID de perfil de runtime. Ele não permite que o aplicativo conceda acesso a outros aplicativos. Limite a concessão a aplicativos que precisam desses recursos de gerenciamento.

Adquirir um token somente do aplicativo

Use as credenciais existentes do aplicativo e o fluxo de credenciais do cliente para solicitar um token de acesso do Microsoft Entra:

Configuração Valor
Autoridade https://login.microsoftonline.com/<tenant-id>
Escopo da solicitação de token https://api.microsoft.ai/.default

Use o escopo exato .default, não o nome do escopo de pesquisa que você está criando. Envie o token em cada solicitação de gerenciamento:

Authorization: Bearer <access-token>

Não use uma chave de API de pesquisa para essas chamadas de gerenciamento. Mantenha os tokens de acesso e as credenciais do aplicativo fora do controle de versão e dos relatórios de diagnóstico.

Descobrir a conta de cobrança

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

Use a referência authorized-resources para o esquema de resposta, definições de ID e interpretação do campo de permissão.

Enviar a solicitação de criação

Usando a ID da conta de cobrança selecionada, envie POST /v1/customer/billing-accounts/{billingAccountId}/scopes com seu nome de escopo e regras. Por exemplo:

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

Forneça ambas as matrizes, usando [] para uma lista intencionalmente vazia. Em 201 Created, salve a definição retornada e a ETag para alterações posteriores.

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

Verificar o escopo antes de usá-lo

  1. Leia o escopo salvo e confirme se suas regras correspondem às fontes pretendidas.
  2. Execute solicitações representativas de Pesquisa na Web, Pesquisa de Notícias ou Auto com failOnMissingScope: true. Verifique os casos incluídos e excluídos antes de habilitar o tráfego dependente.

Importante

A propagação geralmente leva cerca de 10 minutos, mas pode levar até 30 minutos em alguns casos. Não há nenhum SLA de propagação e esses intervalos não são garantidos. Uma gravação ou leitura de gerenciamento bem-sucedida, publicar ou scopeApplied: true não prova que a definição mais recente está ativa. Não use apenas o tempo decorrido como uma verificação de prontidão. Consulte search propagation para obter detalhes.

Implantar uma definição alterada

Se usar temporariamente uma definição anterior for inaceitável, crie um escopo com um novo nome, como ProductDocs-v2. Conclua as etapas de verificação acima antes de alternar os chamadores e mantenha o escopo anterior até que os chamadores não dependam mais dele.

Isso 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 posteriores

Leia o escopo atual antes de editá-lo ou excluí-lo e envie sua ETag If-Matchentre aspas. Siga as diretrizes de concorrência e de resultado incerto ao reconciliar edições simultâneas ou tentar novamente uma gravação. Mantenha as definições revisadas em sua própria fonte de verdade caso precise de histórico de alterações.

Solucionar problemas de criação

Se a conta pretendida estiver ausente da descoberta, peça ao administrador para verificar a identidade da carga de trabalho, a concessão de gerenciamento e a qualificação da conta. Para outras falhas, use a referência de status de descoberta ou a referência de erro de gerenciamento de escopo.

Para falhas persistentes, entre em contato com o Suporte do Web IQ com a ID da conta de cobrança, o nome do escopo, o tempo da operação em UTC, o status HTTP e as IDs de solicitação disponíveis. Inclua comportamentos esperados e reais higienizados; nunca inclua tokens, chaves de API ou credenciais de aplicativo.