Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
A API de Gestão de Clientes Web IQ da Microsoft cria, lê, atualiza e elimina escopos de pesquisa nomeados para uma conta de faturação Web IQ. Para um portal de ponta a ponta ou guia da API, consulte Filtrar resultados com Scopes.
URL base:https://api.microsoft.ai
Rota de recolha:/v1/customer/billing-accounts/{billingAccountId}/scopes
Autenticação e cabeçalhos
As cargas de trabalho precisam de uma identidade Microsoft Entra ativa e CustomerApiAccess da conta de faturação alvo. Solicite um token apenas para aplicação com https://api.microsoft.ai/.default. Use descoberta de recursos autorizados para selecionar billingAccountId; não substitua um ID de cliente, ID de subscrição Azure, ID de aplicação Web IQ ou ID de aplicação Entra (cliente).
| Header | Use |
|---|---|
Authorization: Bearer <access-token> |
Obrigatório para todos os pedidos da gestão. As chaves da API de pesquisa não são suportadas para estas chamadas. |
Content-Type: application/json |
É obrigató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 eliminação. Copie o ETag completo e forte, incluindo as citações, a partir de uma leitura ou escrita de escopo. |
Operations
Os caminhos abaixo são relativos à rota de recolha.
| Method | Path | Success | Description |
|---|---|---|---|
POST |
Rota de recolha |
201, definição, ETag, Location |
Crie um escopo nomeado. |
GET |
Rota de recolha |
200, página de metadados |
Liste nomes de escopos, contagens e carimbos temporais, sem matrizes de seletor. |
GET |
/{name} |
200, definição, ETag |
Leia tanto os arrays completos dos seletores como os metadados. |
GET |
/{name}/summary |
200, metadados, ETag |
Contagens de leitura e carimbos temporais sem matrizes de seletor. |
GET |
/{name}/includeSites ou /{name}/excludeSites |
200, página do site, ETag |
Página um, lista de seletores. |
PUT |
/{name} |
200, definição, ETag |
Substituir ambos os arrays; 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 |
Eliminar permanentemente um telescópio; requer If-Match. |
Nomes de âmbito identificam recursos na coleção de âmbito atribuída à conta. Os AppIDs do Web IQ na conta usam essa coleção. As contas atribuídas à mesma coleção partilham nomes, definições e alterações.
Criar um âmbito
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 de pedido | Required | Tipo | Description |
|---|---|---|---|
name |
Yes | cadeia (de caracteres) | 1-128 caracteres após o corte; Letras, dígitos, ., _, e -ASCII. Indistintamente ao caso único dentro da coleção. |
includeSites |
Yes | matriz de strings | Incluía os selecionadores. Use [] para inclusão intencionalmente vazia, que permite todas as fontes não excluídas. |
excludeSites |
Yes | matriz de strings | Exclui os selecionadores. A exclusão tem prioridade sobre a inclusão, independentemente da especificidade. |
Ambos os arrays devem estar presentes. Omitir qualquer propriedade ou enviar null não é equivalente a [].
O HTTP 201 Created devolve a definição normalizada e os cabeçalhos de resposta abaixo. A criação não é uma atualização ou renomeação: um nome duplicado insensível a maiúsculas e minúsculas devolve 409 Conflict.
| Cabeçalho da resposta | Description |
|---|---|
ETag |
Token forte e citado de concorrência de autoria. Mantém o valor exato para pedidos futuros If-Match . Não é um token de prontidão de serviço ou de versão de serviço. |
Location |
URI relativo raiz do âmbito criado na rota da conta de faturação 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 |
string (UUID) | A conta de faturação utilizada no pedido. |
name |
cadeia (de caracteres) | Nome do telescópio, com a caixa do ecrã preservada. A pesquisa é indistinta a maiúsculas e minúsculas. |
includeSites |
matriz de strings | Selecionadores completos e normalizados incluídos. |
excludeSites |
matriz de strings | Selecionadores completos e normalizados excluídos. |
includedSiteCount |
número inteiro | Número de seletores únicos normalizados incluídos. |
excludedSiteCount |
número inteiro | Número de seletores únicos excluídos normalizados. |
createdAt |
string (data-hora) | Hora de criação em UTC. |
updatedAt |
string (data-hora) | Última atualização no UTC. |
Lista e mira de leitura
Use GET /v1/customer/billing-accounts/{billingAccountId}/scopes/{name} para a definição completa e o seu ETag atual. Adicionar /summary para apenas leitura metadados e contagens.
Use GET /v1/customer/billing-accounts/{billingAccountId}/scopes?pageSize=50 para listar telescópios. A resposta contém objetos de metadados em items e um opcional nextContinuationToken.
| Parâmetro de consulta | Aplica-se a | Values |
|---|---|---|
pageSize |
Lista de âmbito | 1-100; Padrão 50. |
pageSize |
Lista de selecionadores incluídos ou excluídos | 1-1,000; Padrão 100. |
continuationToken |
Qualquer tipo de lista | Token opaco da página anterior dessa lista. Passa-o sem alterações e deixa o cliente HTTP codificar o URL. |
Continue até nextContinuationToken que esteja ausente ou null. Os metadados do âmbito são listados por ordem de nomes normalizados, não como um snapshot garantido durante edições simultâneas.
Para paginar os seletores, chame GET .../scopes/{name}/includeSites ou GET .../scopes/{name}/excludeSites. Cada resposta contém sites, totalCount, nextContinuationToken, , e um cabeçalho ETag. As páginas do seletor seguem a ordem canónica do seletor. Mantém tokens com o mesmo alcance e lista. Se uma edição tornar um token seletor obsoleto, o pedido devolve 412; descarte a enumeração parcial e reinicie a partir da primeira página.
Atualizar ou eliminar um telescópio
PUT substitui ambos os arrays completos 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 rota com um sites array:
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"]
}
Fornecer 1-10.000 entradas submetidas. A lista resultante deve ainda assim satisfazer os seus limites de seletor único e tamanho de definição. Adicionar um seletor canónico já presente ou remover um seletor ausente é um no-op. Um pedido totalmente no-op preserva o ETag. Mutações incrementais bem-sucedidas regressam 204 com o ETag atual e sem corpo JSON.
Use DELETE .../scopes/{name} com If-Match com para apagar permanentemente o telescópio. Remova primeiro as dependências dos chamadores. Não existe um endpoint de soft delete ou restore endpoint, e a eliminação propaga-se de forma assíncrona. Para uma coleção partilhada, a eliminação afeta todas as contas atribuídas.
Concorrência e resultados incertos
Substituir, edições incrementais e eliminar requerem o ETag forte atual. Não remova as suas cotações, não as construa a partir de carimbos temporais, nem use etiquetas fracas, coringa ou múltiplas.
Em 412 Precondition Failed, leia a definição mais recente, reconcilie a alteração pretendida com as alterações de outros autores e tente novamente com o ETag mais recente. Não sobrescreva cegamente a definição mais recente.
428 Precondition Required Means If-Match estava desaparecido.
Se uma escrita expirar ou a ligação falhar, leia o recurso antes de tentar novamente. Uma criação pode ter tido sucesso antes de um timeout, fazendo com que a retentativa retorne 409; uma edição pode ter alterado o ETag, fazendo com que a retentativa retorne 412. Ao verificar uma eliminação, distingua a ausência genuína de uma falha na autorização.
Limites e validação do seletor
| Restrição | Limite ou comportamento |
|---|---|
| Name | 1-128 caracteres após o corte; Letras, dígitos, ., _, e -ASCII. |
| Cada lista de selecionadores | Até 10.000 seletores únicos normalizados. Envie no máximo 10.000 entradas distintas por array. |
| Cada seletor | Até 2.048 caracteres antes de cortar e depois da normalização. |
| Profundidade do percurso | Não existe subdiretório separado ou limite de número de segmentos, sujeito ao comprimento do seletor e ao tamanho combinado da definição. |
| Definição combinada | Predefinido 3.670.016 bytes (3,5 MiB), estimado a partir da definição de serviço serializado, incluindo tanto listas como metadados. Não o tamanho bruto do corpo do pedido HTTP. |
| Adicionar/remover corpo incremental | 1-10.000 entradas submetidas em sites. |
A coleção também tem um limite de escopo.
409 pode indicar capacidade esgotada, bem como um nome duplicado; verificar o erro e o inventário existente. Contacte o Suporte Web IQ para saber a capacidade eficaz da sua conta.
Os seletores suportados 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 nos limites dos segmentos de caminho desse host) e URLs HTTPS exatos (https://example.com/products/guide). Adicionar um esquema altera um prefixo path para uma URL exata.
Curingas, portas explícitas, cadeias de consulta, fragmentos, informação do utilizador, IPv6, segmentos de pontos e separadores de caminho codificados são rejeitados. Os caracteres de caminho brutos não ASCII devem estar codificados em UTF-8 por cento.
A normalização corta o espaço em branco circundante, os hosts em minúsculas, preserva o path casing, ordena os seletores canónicos e deduplica cada lista de forma independente. Uma entrada pode aparecer em ambas as listas; a exclusão vence sempre. A inclusão vazia permite todas as fontes não excluídas. Ambos os arrays vazios significam que o próprio escopo não impõe restrição ao local.
Códigos de estado e erros
Os erros de gestão utilizam um contrato diferente da resposta de erro de pesquisa v3.
| Status | Meaning | Action |
|---|---|---|
400 |
Nome, corpo, seletores, paginação, tamanho de definição ou If-Match formato inválidos. |
Corrigir a entrada; não tentar novamente sem alterações. |
401 |
Autenticação em falta ou inválida. | Verifique a expiração do token e o https://api.microsoft.ai/.default âmbito do pedido de token. |
403 |
Autorização principal ou de conta negada. | Verifique a identidade ativa da carga de trabalho e CustomerApiAccess a sua conta. |
404 |
Escopo ou conta de faturação solicitados não encontrados. | Verifica a conta e o nome. A autorização pode negar um pedido antes de a existência ser divulgada. |
409 |
Nome duplicado ou capacidade de recolha esgotada. | Leia o inventário existente e os detalhes do erro; não tente a criação às cegas. |
412 |
ETag obsoleto ou token de página seletora obsoleto. | Releia e reconcilie a edição, ou reinicie a paginação do seletor. |
428 |
Era obrigatório If-Match faltar. |
Leia o recurso e envie o seu ETag forte atualmente cotado. |
500 |
Falha de serviço ou dependência. | Use retentativas limitadas para leituras; reconcilie primeiro escritas incertas. |
Erros de validação de escopo, não encontrados, conflito e concorrência utilizam esta forma JSON:
{
"code": "NotFound",
"message": "The requested scope was not found."
}
Os valores estáveis code incluem InvalidRequest, NotFound, Conflict, PreconditionFailed, e PreconditionRequired. A subCode também pode estar presente. Faça ramificação no estado HTTP e code, não no diagnóstico message, e aceite códigos e campos desconhecidos. Os órgãos de pedido mal formados ou inválidos podem, em vez disso, devolver application/problem+json detalhes de validação.
401 e 403 não têm corpo; falhas de dependência podem ter uma forma diferente.
Propagação da pesquisa
Uma escrita ou leitura bem-sucedida da gestão não prova que a definição mais recente está ativa na pesquisa. A propagação é assíncrona. A propagação global completa normalmente demora cerca de 10 minutos, mas pode demorar até 30 minutos em alguns casos. Atualmente não existe SLA de propagação, e estes tempos não são garantidos. Ainda não existe versionamento de endpoint ou scope de prontidão. O ETag de autoria e o runtime scopeApplied: true não identificam a versão atualmente servida.
Para verificações de prontidão e uma estratégia de substituição de novo nome, consulte Verificar o âmbito antes de o utilizar.