Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
A API de Gerenciamento de Clientes do Microsoft Web IQ cria, lê, atualiza e exclui escopos de pesquisa nomeados para uma conta de cobrança de Qi da Web. Para obter um passo a passo do portal de ponta a ponta ou da API, consulte Os resultados do filtro com escopos.
URL base:https://api.microsoft.ai
Rota da coleção:/v1/customer/billing-accounts/{billingAccountId}/scopes
Autenticação e cabeçalhos
As cargas de trabalho precisam de uma identidade Microsoft Entra ativa e CustomerApiAccess na conta de cobrança de destino. Solicitar um token somente de aplicativo com https://api.microsoft.ai/.default. Use a descoberta de recursos autorizados para selecionarbillingAccountId; não substitua uma ID do cliente, Azure ID da assinatura, ID do Aplicativo web IQ ou ID do aplicativo Entra (cliente).
| Cabeçalho | Usar |
|---|---|
Authorization: Bearer <access-token> |
Necessário para cada solicitação de gerenciamento. Não há suporte para chaves de API de pesquisa para essas chamadas. |
Content-Type: application/json |
Necessário ao enviar um corpo JSON. |
Accept: application/json |
Solicita respostas JSON. |
If-Match: "<current-etag>" |
Necessário para substituição, edições incrementais e exclusão. Copie a ETag forte completa, incluindo aspas, de uma leitura ou gravação de escopo. |
Operations
Os caminhos abaixo são relativos à rota da coleção.
| Method | Caminho | Êxito | Description |
|---|---|---|---|
POST |
Rota da coleção |
201, definição, ETag, Location |
Crie um escopo nomeado. |
GET |
Rota da coleção |
200, página de metadados |
Listar nomes de escopo, contagens e carimbos de data/hora, sem matrizes de seletor. |
GET |
/{name} |
200, definição, ETag |
Leia as matrizes de seletores completas e os metadados. |
GET |
/{name}/summary |
200, metadados, ETag |
Contagens de leitura e carimbos de data/hora sem matrizes de seletores. |
GET |
/{name}/includeSites ou /{name}/excludeSites |
200, página do site, ETag |
Lista de seletores da página um. |
PUT |
/{name} |
200, definição, ETag |
Substitua ambas as matrizes; requer If-Match. |
POST |
/{name}/includeSites:add ou /{name}/excludeSites:add |
204, ETag |
Adicionar seletores a uma lista; requer If-Match. |
POST |
/{name}/includeSites:remove ou /{name}/excludeSites:remove |
204, ETag |
Remover seletores de uma lista; requer If-Match. |
DELETE |
/{name} |
204 |
Excluir permanentemente um escopo; requer If-Match. |
Os nomes de escopo identificam recursos na coleção de escopo atribuída da conta. Os AppIDs do IQ da Web na conta usam essa coleção. Contas atribuídas aos mesmos nomes de compartilhamento de coleção, definições e alterações.
Criar um escopo
POST /v1/customer/billing-accounts/<billingAccountId>/scopes HTTP/1.1
Host: api.microsoft.ai
Authorization: Bearer <access-token>
Content-Type: application/json
{
"name": "ProductDocs",
"includeSites": ["example.com", "docs.example.org/products"],
"excludeSites": ["ads.example.com"]
}
| Campo solicitação | Required | Tipo | Description |
|---|---|---|---|
name |
Yes | cadeia | 1 a 128 caracteres após o corte; Letras ASCII, dígitos e ._-. Não diferencia maiúsculas de minúsculas e exclusivas dentro da coleção. |
includeSites |
Yes | Matriz de cadeias de caracteres | Seletores incluídos. Use [] para inclusão intencionalmente vazia, o que permite todas as fontes não excluídas. |
excludeSites |
Yes | Matriz de cadeias de caracteres | Seletores excluídos. A exclusão tem precedência sobre a inclusão, independentemente da especificidade. |
Ambas as matrizes devem estar presentes. Omitir uma propriedade ou enviar null não é equivalente a [].
HTTP 201 Created retorna a definição normalizada e os cabeçalhos de resposta abaixo. A criação não é uma atualização ou renomeação: um nome que não diferencia maiúsculas de minúsculas duplicada retorna 409 Conflict.
| Cabeçalho de resposta | Description |
|---|---|
ETag |
Token de simultaneidade de criação forte e entre aspas. Preserve o valor exato para solicitações futuras If-Match . Não é um token de preparação de serviço ou de versão de serviço. |
Location |
URI relativo à raiz do escopo criado na rota de conta de cobrança solicitada. |
Campos de resposta
Uma definição completa contém todos os campos abaixo. Uma resposta de metadados omite includeSites e excludeSites.
| Field | Tipo | Description |
|---|---|---|
billingAccountId |
cadeia de caracteres (UUID) | A conta de cobrança usada na solicitação. |
name |
cadeia | Nome do escopo, com a maiúscula de exibição preservada. A pesquisa não diferencia maiúsculas de minúsculas. |
includeSites |
Matriz de cadeias de caracteres | Seletores incluídos completos e normalizados. |
excludeSites |
Matriz de cadeias de caracteres | Seletores excluídos completos e normalizados. |
includedSiteCount |
inteiro | Número de seletores incluídos exclusivos normalizados. |
excludedSiteCount |
inteiro | Número de seletores exclusivos excluídos normalizados. |
createdAt |
cadeia de caracteres (data e hora) | Hora de criação em UTC. |
updatedAt |
cadeia de caracteres (data e hora) | Hora da última atualização em UTC. |
Listar e ler escopos
Use GET /v1/customer/billing-accounts/{billingAccountId}/scopes/{name} para a definição completa e sua ETag atual. Acrescente /summary para ler apenas metadados e contagens.
Use GET /v1/customer/billing-accounts/{billingAccountId}/scopes?pageSize=50 para listar escopos. A resposta contém objetos items de metadados e um opcional nextContinuationToken.
| Parâmetro de consulta | Aplica-se a | Values |
|---|---|---|
pageSize |
Lista de escopo | 1-100; padrão 50. |
pageSize |
Lista de seletores incluídos ou excluídos | 1-1,000; padrão 100. |
continuationToken |
Qualquer tipo de lista | Token opaco da página anterior da lista. Passe-o inalterado e deixe a URL do cliente HTTP codificar. |
Continue até nextContinuationToken que esteja ausente ou null. Os metadados de escopo são listados em ordem de nome normalizado, não como um instantâneo garantido durante edições simultâneas.
Para seletores de página, chamada GET .../scopes/{name}/includeSites ou GET .../scopes/{name}/excludeSites. Cada resposta contémsites, nextContinuationTokentotalCounte um cabeçalho ETag. As páginas do seletor seguem a ordem do seletor canônico. Mantenha os tokens com o mesmo escopo e lista. Se uma edição tornar um token de seletor obsoleto, a solicitação retornará 412; descarte a enumeração parcial e reinicie da primeira página.
Atualizar ou excluir um escopo
PUT substitui as matrizes completas e não renomeia o escopo:
PUT /v1/customer/billing-accounts/<billingAccountId>/scopes/ProductDocs HTTP/1.1
Host: api.microsoft.ai
Authorization: Bearer <access-token>
Content-Type: application/json
If-Match: "<current-etag>"
{
"includeSites": ["example.com"],
"excludeSites": ["ads.example.com", "example.com/archive"]
}
Para alterar uma lista sem substituir a outra, use a correspondente :add ou :remove a rota por uma sites matriz:
POST /v1/customer/billing-accounts/<billingAccountId>/scopes/ProductDocs/excludeSites:add HTTP/1.1
Host: api.microsoft.ai
Authorization: Bearer <access-token>
Content-Type: application/json
If-Match: "<current-etag>"
{
"sites": ["example.com/archive"]
}
Forneça de 1 a 10.000 entradas enviadas. A lista resultante ainda deve satisfazer seus limites de tamanho de definição e seletor exclusivo. Adicionar um seletor canônico já presente ou remover um seletor ausente é um no-op. Uma solicitação totalmente no-op preserva a ETag. Mutações incrementais bem-sucedidas retornam 204 com a ETag atual e nenhum corpo JSON.
Use DELETE .../scopes/{name} com If-Match para excluir permanentemente o escopo. Remova as dependências dos chamadores primeiro. Não há ponto de extremidade de exclusão temporária ou restauração e a exclusão é propagada de forma assíncrona. Para uma coleção compartilhada, a exclusão afeta todas as contas atribuídas.
Simultaneidade e resultados incertos
Substituir, edições incrementais e excluir exigem a ETag forte atual. Não remova suas aspas, construa-as de carimbos de data/hora ou use marcas fracas, curingas ou várias marcas.
On 412 Precondition Failed, read the latest definition, reconcile the intended change with other writers's changes, and retry with the latest ETag. Não substitua cegamente a definição mais recente.
428 Precondition Required significa que If-Match estava faltando.
Se uma gravação atingir o tempo limite ou a conexão for descartada, leia o recurso antes de tentar novamente. Uma criação pode ter sido bem-sucedida antes de um tempo limite, fazendo com que a repetição retorne 409; uma edição pode ter alterado a ETag, fazendo com que a repetição retorne 412. Ao verificar uma exclusão, distingue a ausência genuína de uma falha de autorização.
Limites e validação de seletor
| Constraint | Limite ou comportamento |
|---|---|
| Name | 1 a 128 caracteres após o corte; Letras ASCII, dígitos e ._-. |
| Cada lista de seletores | Até 10.000 seletores exclusivos normalizados. Envie no máximo 10.000 entradas distintas por matriz. |
| Cada seletor | Até 2.048 caracteres antes de cortar e após a normalização. |
| Profundidade do caminho | Nenhum subdiretório ou limite de contagem de segmentos separado, sujeito ao tamanho do seletor e ao tamanho combinado da definição. |
| Definição combinada | Padrão 3.670.016 bytes (3,5 MiB), estimados a partir da definição de serviço serializada, incluindo listas e metadados. Não o tamanho bruto do corpo da solicitação HTTP. |
| Adicionar/remover corpo incremental | 1 a 10.000 entradas enviadas em sites. |
A coleção também tem um limite de contagem de escopo.
409 pode indicar a capacidade esgotada, bem como um nome duplicado; verifique o erro e o inventário existente. Entre em contato com o Suporte de Perguntas Frequentes da Web para obter a capacidade efetiva da sua conta.
Os seletores com suporte incluem domínios DNS (example.com e todos os subdomínios descendentes), hosts IPv4 (192.0.2.10), prefixos de caminho (example.com/products/guides em limites de segmento de caminho para esse host) e URLs HTTPS exatas (https://example.com/products/guide). Adicionar um esquema altera um prefixo de caminho em uma URL exata.
Curingas, portas explícitas, cadeias de caracteres de consulta, fragmentos, informações do usuário, IPv6, segmentos de pontos e separadores de caminho codificados são rejeitados. Caracteres de caminho não ASCII brutos devem ser codificados em UTF-8 por cento.
A normalização corta o espaço em branco ao redor, hospeda minúsculas, preserva a invólucro de caminho, classifica seletores canônicos e elimina duplicações de cada lista de forma independente. Uma entrada pode aparecer em ambas as listas; a exclusão sempre vence. A inclusão vazia permite todas as fontes não excluídas. Ambas as matrizes vazias significam que o próprio escopo não impõe nenhuma restrição de site.
Códigos de status e erros
Os erros de gerenciamento usam um contrato diferente da resposta de erro de pesquisa v3.
| Status | Meaning | Action |
|---|---|---|
400 |
Nome, corpo, seletores, paginação, tamanho da definição ou formato inválidos If-Match . |
Corrija a entrada; não tente novamente inalterado. |
401 |
Autenticação ausente ou inválida. | Verifique a expiração do token e o https://api.microsoft.ai/.default escopo da solicitação de token. |
403 |
Entidade de segurança ou autorização de conta negada. | Verifique a identidade ativa da carga de trabalho e CustomerApiAccess na conta. |
404 |
Escopo solicitado ou conta de cobrança não encontrada. | Verifique a conta e o nome. A autorização pode negar uma solicitação antes que a existência seja divulgada. |
409 |
Nome duplicado ou capacidade de coleta esgotada. | Leia os detalhes de inventário e erro existentes; não tente novamente a criação às cegas. |
412 |
ETag obsoleta ou token de página de seletor obsoleto. | Leia novamente e reconcilie a paginação do seletor de edição ou reinicie. |
428 |
Necessário ausente If-Match . |
Leia o recurso e envie sua ETag forte entre aspas atuais. |
500 |
Falha de dependência ou serviço. | Usar novas tentativas limitadas para leituras; reconciliar gravações incertas primeiro. |
Erros de validação de escopo, não encontrados, conflitos e simultaneidade usam esta forma JSON:
{
"code": "NotFound",
"message": "The requested scope was not found."
}
Os valores estáveis incluem , , , Conflicte PreconditionRequiredPreconditionFailed. NotFoundInvalidRequestcode Um subCode também pode estar presente. Ramificar no status HTTP e code, não no diagnóstico message, e aceitar códigos e campos desconhecidos. Os corpos de solicitação malformados ou inválidos podem retornar application/problem+json detalhes de validação.
401 e 403 não têm corpo; falhas de dependência podem usar uma forma diferente.
Propagação de pesquisa
Uma gravação ou leitura de gerenciamento bem-sucedida não prova que a definição mais recente está ativa na pesquisa. A propagação é assíncrona. A propagação global completa geralmente leva cerca de 10 minutos, mas pode levar até 30 minutos em alguns casos. No momento, não há nenhum SLA de propagação e esses intervalos não são garantidos. Ainda não há nenhum ponto de extremidade de preparação ou controle de versão de escopo. O ETag de criação e o runtime scopeApplied: true não identificam a versão atendida no momento.
Para verificações de preparação e uma estratégia de substituição de novo nome, consulte Verificar o escopo antes de usá-lo.