Informazioni di riferimento sulle API REST di gestione degli ambiti

L'API Gestione clienti IQ Web Microsoft crea, legge, aggiorna ed elimina ambiti di ricerca denominati per un account di fatturazione IQ Web. Per una procedura dettagliata dell'API o del portale end-to-end, vedere Filtrare i risultati con ambiti.

URL di base:https://api.microsoft.ai

Route di raccolta:/v1/customer/billing-accounts/{billingAccountId}/scopes

Autenticazione e intestazioni

I carichi di lavoro necessitano di un'identità Microsoft Entra attiva e CustomerApiAccess nell'account di fatturazione di destinazione. Richiedere un token solo app con https://api.microsoft.ai/.default. Usare l'individuazione di risorse autorizzate per selezionare billingAccountId; non sostituire un ID cliente, Azure ID sottoscrizione, ID app IQ Web o ID applicazione Entra (client).

Header	Utilizza
Authorization: Bearer <access-token>	Obbligatorio per ogni richiesta di gestione. Le chiavi API di ricerca non sono supportate per queste chiamate.
Content-Type: application/json	Obbligatorio quando si invia un corpo JSON.
Accept: application/json	Richiede risposte JSON.
If-Match: "<current-etag>"	Obbligatorio per la sostituzione, le modifiche incrementali e l'eliminazione. Copiare l'ETag sicuro completo, incluse le virgolette, da un ambito letto o scritto.

Operations

I percorsi seguenti sono relativi alla route di raccolta.

Method	Percorso	Success	Descrzione
POST	Route di raccolta	201, definizione, ETag, Location	Creare un ambito denominato.
GET	Route di raccolta	200, pagina dei metadati	Elencare nomi di ambito, conteggi e timestamp, senza matrici di selettori.
GET	/{name}	200, definizione, ETag	Leggere sia matrici di selettori completi che metadati.
GET	/{name}/summary	200, metadati, ETag	Legge conteggi e timestamp senza matrici di selettori.
GET	/{name}/includeSites o /{name}/excludeSites	200, pagina del sito, ETag	Elenco di selettori di pagina 1.
PUT	/{name}	200, definizione, ETag	Sostituire entrambe le matrici; richiede If-Match.
POST	/{name}/includeSites:add o /{name}/excludeSites:add	204, ETag	Aggiungere selettori a un elenco; richiede If-Match.
POST	/{name}/includeSites:remove o /{name}/excludeSites:remove	204, ETag	Rimuovere i selettori da un elenco; richiede If-Match.
DELETE	/{name}	204	Eliminare definitivamente un ambito; richiede If-Match.

I nomi degli ambiti identificano le risorse nella raccolta di ambiti assegnata dall'account. Gli ID app IQ Web nell'account usano tale raccolta. Account assegnati agli stessi nomi, definizioni e modifiche delle condivisioni raccolte.

Creare un ambito

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 richiesta	Required	Type	Descrzione
name	Yes	Stringa	1-128 caratteri dopo il taglio; Lettere ASCII, cifre, ., _e -. Senza distinzione tra maiuscole e minuscole all'interno della raccolta.
includeSites	Yes	matrice di stringhe	Selettori inclusi. Usare [] per l'inclusione intenzionalmente vuota, che consente tutte le origini non escluse.
excludeSites	Yes	matrice di stringhe	Selettori esclusi. L'esclusione ha la precedenza sull'inclusione indipendentemente dalla specificità.

Entrambe le matrici devono essere presenti. L'omissione di proprietà o l'invio null non equivale a [].

HTTP 201 Created restituisce la definizione normalizzata e le intestazioni di risposta seguenti. La creazione non è un aggiornamento o una ridenominazione: un nome senza distinzione tra maiuscole e minuscole duplicato restituisce 409 Conflict.

Intestazione della risposta	Descrzione
ETag	Token di concorrenza sicuro e racchiuso tra virgolette. Mantenere il valore esatto per le richieste future If-Match . Non è un token di disponibilità o di versione di servizio.
Location	URI relativo alla radice dell'ambito creato nella route dell'account di fatturazione richiesta.

Campi di risposta

Una definizione completa contiene tutti i campi seguenti. Una risposta di metadati includeSites omette e excludeSites.

Campo	Type	Descrzione
billingAccountId	string (UUID)	Account di fatturazione usato nella richiesta.
name	Stringa	Nome ambito, con maiuscole e minuscole visualizzate mantenute. La ricerca non fa distinzione tra maiuscole e minuscole.
includeSites	matrice di stringhe	Selettori inclusi normalizzati e completi.
excludeSites	matrice di stringhe	Selettori esclusi normalizzati e completi.
includedSiteCount	Intero	Numero di selettori univoci normalizzati inclusi.
excludedSiteCount	Intero	Numero di selettori esclusi univoci normalizzati.
createdAt	string (date-time)	Ora di creazione in formato UTC.
updatedAt	string (date-time)	Ora dell'ultimo aggiornamento in formato UTC.

Elencare e leggere gli ambiti

Usare GET /v1/customer/billing-accounts/{billingAccountId}/scopes/{name} per la definizione completa e il relativo ETag corrente. Accodare /summary a metadati e conteggi di sola lettura.

Usare GET /v1/customer/billing-accounts/{billingAccountId}/scopes?pageSize=50 per elencare gli ambiti. La risposta contiene oggetti metadati in items e un oggetto facoltativo nextContinuationToken.

Query parameter (Parametro di query)	Si applica a	Values
pageSize	Elenco ambiti	1-100; valore predefinito 50.
pageSize	Elenco di selettori inclusi o esclusi	1-1,000; valore predefinito 100.
continuationToken	Entrambi i tipi di elenco	Token opaco dalla pagina precedente dell'elenco. Passarlo invariato e lasciare che l'URL del client HTTP lo codifica.

Continuare fino a quando nextContinuationToken non è assente o null. I metadati dell'ambito sono elencati nell'ordine normalizzato dei nomi, non come snapshot garantito durante le modifiche simultanee.

Per i selettori di pagina, chiamare GET .../scopes/{name}/includeSites o GET .../scopes/{name}/excludeSites. Ogni risposta contiene sites, totalCount, nextContinuationTokene un'intestazione ETag. Le pagine del selettore seguono l'ordine del selettore canonico. Mantenere i token con lo stesso ambito ed elenco. Se una modifica imposta un token del selettore non aggiornato, la richiesta restituisce 412; ignora l'enumerazione parziale e riavvia dalla prima pagina.

Aggiornare o eliminare un ambito

PUT sostituisce entrambe le matrici complete e non rinomina l'ambito:

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"]
}

Per modificare un elenco senza sostituire l'altro, usare la route o :remove corrispondente :add con una sites matrice:

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"]
}

Fornire 1-10.000 voci inviate. L'elenco risultante deve comunque soddisfare i limiti univoci per il selettore e le dimensioni delle definizioni. L'aggiunta di un selettore canonico già presente o la rimozione di un selettore assente è un no-op. Una richiesta interamente no-op mantiene l'ETag. Le mutazioni incrementali riuscite restituiscono 204 l'ETag corrente e nessun corpo JSON.

Usare DELETE .../scopes/{name} con If-Match per eliminare definitivamente l'ambito. Rimuovere prima le dipendenze dai chiamanti. Non esiste un endpoint di eliminazione temporanea o ripristino e l'eliminazione viene propagata in modo asincrono. Per una raccolta condivisa, l'eliminazione influisce su tutti gli account assegnati.

Concorrenza e risultati incerti

La sostituzione, le modifiche incrementali e l'eliminazione richiedono l'ETag sicuro corrente. Non rimuovere le virgolette, crearla dai timestamp o usare tag deboli, jolly o più tag.

In 412 Precondition Failedleggere la definizione più recente, riconciliare la modifica prevista con le modifiche di altri writer e riprovare con l'ETag più recente. Non sovrascrivere in modo cieco la definizione più recente. 428 Precondition Required significa If-Match che mancava.

Se si verifica un timeout di scrittura o la connessione viene eliminata, leggere la risorsa prima di riprovare. È possibile che una creazione abbia avuto esito positivo prima di un timeout, rendendo il nuovo tentativo restituito 409. Una modifica potrebbe aver modificato l'ETag, rendendo il nuovo tentativo restituito 412. Quando si controlla un'eliminazione, distinguere l'assenza autentica da un errore di autorizzazione.

Limiti e convalida del selettore

Constraint	Limitare o comportamento
Name	1-128 caratteri dopo il taglio; Lettere ASCII, cifre, ., _e -.
Ogni elenco di selettori	Fino a 10.000 selettori univoci normalizzati. Inviare al massimo 10.000 voci distinte per matrice.
Ogni selettore	Fino a 2.048 caratteri prima di tagliare e dopo la normalizzazione.
Profondità percorso	Nessun limite di sottodirectory o di conteggio dei segmenti separato, soggetto alla lunghezza del selettore e alle dimensioni di definizione combinate.
Definizione combinata	Valore predefinito di 3.670.016 byte (3,5 MiB), stimato dalla definizione di servizio serializzata, inclusi elenchi e metadati. Non le dimensioni non elaborate del corpo della richiesta HTTP.
Aggiunta/rimozione incrementale del corpo	1-10.000 voci inviate in sites.

La raccolta ha anche un limite di conteggio degli ambiti. 409 può indicare capacità esaurita, nonché un nome duplicato; controllare l'errore e l'inventario esistente. Contattare il supporto di IQ Web per ottenere la capacità effettiva dell'account.

I selettori supportati includono i domini DNS (example.com e tutti i sottodomini discendenti), gli host IPv4 (192.0.2.10), i prefissi di percorso (example.com/products/guides nei limiti del segmento di percorso per tale host) e gli URL HTTPS esatti (https://example.com/products/guide). L'aggiunta di uno schema modifica un prefisso di percorso in un URL esatto.

I caratteri jolly, le porte esplicite, le stringhe di query, i frammenti, le informazioni utente, IPv6, i segmenti di punti e i separatori di percorso codificati vengono rifiutati. I caratteri di percorso non ASCII non elaborati devono essere codificati con UTF-8%.

La normalizzazione riduce gli spazi vuoti, gli host minuscoli, mantiene la combinazione di maiuscole e minuscole, ordina i selettori canonici e deduplica ogni elenco in modo indipendente. Una voce può essere visualizzata in entrambi gli elenchi; l'esclusione vince sempre. L'inclusione vuota consente tutte le origini non escluse. Entrambe le matrici vuote indicano che l'ambito stesso non impone alcuna restrizione del sito.

Codici di stato ed errori

Gli errori di gestione usano un contratto diverso dalla risposta all'errore di ricerca v3.

Status	Meaning	Action
400	Nome, corpo, selettori, paginazione, dimensioni della definizione o If-Match formato non validi.	Correggere l'input; non rieseguire un nuovo tentativo.
401	Autenticazione mancante o non valida.	Controllare la scadenza del token e l'ambito della https://api.microsoft.ai/.default richiesta di token.
403	Autorizzazione dell'entità o dell'account negata.	Verificare l'identità attiva del carico di lavoro e CustomerApiAccess l'account.
404	Ambito richiesto o account di fatturazione non trovato.	Controllare l'account e il nome. L'autorizzazione può negare una richiesta prima che venga divulgata l'esistenza.
409	Nome duplicato o capacità di raccolta esaurita.	Leggere i dettagli dell'inventario e dell'errore esistenti; non riprovare accecamente la creazione.
412	Token ETag non aggiornato o selettori non aggiornati.	Rileggere e riconciliare la modifica o riavviare la paginazione del selettore.
428	Obbligatorio If-Match mancante.	Leggere la risorsa e inviare l'ETag sicuro tra virgolette corrente.
500	Errore di servizio o dipendenza.	Usare i tentativi delimitati per le letture; riconciliare prima scritture incerte.

Gli errori di convalida dell'ambito, non trovati, in conflitto e concorrenza usano questa forma JSON:

{
  "code": "NotFound",
  "message": "The requested scope was not found."
}

I valori stabili code includono InvalidRequest, NotFound, PreconditionFailedConflict, e PreconditionRequired. Può essere presente anche un oggetto subCode . Ramo in stato HTTP e code, non nella diagnostica messagee accettare codici e campi sconosciuti. I corpi di richiesta non validi o non validi possono invece restituire application/problem+json i dettagli di convalida. 401 e 403 non hanno corpo; gli errori di dipendenza possono usare una forma diversa.

Propagazione della ricerca

Una corretta scrittura o lettura di gestione non dimostra che la definizione più recente è attiva nella ricerca. La propagazione è asincrona. La propagazione globale completa richiede in genere circa 10 minuti, ma può richiedere fino a 30 minuti in alcuni casi. Attualmente non esiste alcun SLA di propagazione e questi tempi non sono garantiti. Non esiste ancora alcun endpoint di readiness o controllo delle versioni dello scope. La creazione di ETag e il runtime scopeApplied: true non identificano la versione attualmente servita.

Per i controlli di conformità e una strategia di sostituzione del nuovo nome, vedere Verificare l'ambito prima di usarlo.