Ergebnisse mit Scopes filtern

Scopes in Microsoft Web IQ ermöglichen es Ihnen, Grounding-API-Anfragen zu optimieren, indem Sie URLs, Websites und Domänen in der Websuche, der Nachrichtensuche und den automatischen Ergebnissen ein- oder ausschließen.

Entwickler und Unternehmensadministratoren können Scopes verwenden, um KI-Erlebnisse mit genehmigten und gewünschten Webquellen zu verankern. Definieren Sie wiederverwendbare Einschluss- und Ausschlusslisten für URLs, Domänen und Pfade, um zu steuern, welche Quellen Ihre Grundsuchen zurückgeben können.

Ein Scope ist eine benannte Konfiguration von Inklusions- und Ausschlussregeln. Erstellen Sie es im Web IQ-Portal oder der Kundenverwaltungs-API für ein Abrechnungskonto, und wählen Sie es dann nach Namen in Ihrer Websuche, News Search oder Auto-Anfragen aus. Beide Verwaltungsoptionen funktionieren mit denselben benannten Scopes. Diese Suchbereiche sind nicht Microsoft Entra OAuth-Berechtigungsbereiche.

Warning

Bei Auto schränken Scopes nur Web- und Nachrichtenergebnisse ein. Andere Antworttypen werden nicht nach dem Bereich gefiltert und enthalten möglicherweise Ergebnisse außerhalb des Bereichs, auch wenn scopeAppliedtrue ist.

Geschäftsszenarien und häufige Anwendungsfälle

Scenario Exemplarischer Anwendungsfall Verwenden von Scopes
Kuratierte Forschung Stützen Sie einen Forschungsassistenten auf Quellen, die von Ihrer Organisation überprüft wurden, z. B. genehmigte medizinische Publikationen. Schließen Sie die genehmigten Domänen, Unterdomänen oder einzelne Seiten ein.
Richtlinien für Organisationsquellen Schließen Sie Domänen, die von Ihrer Organisation eingeschränkt werden, von den Grounding-Ergebnissen der Websuche und der Nachrichtensuche aus. Verwalten Sie eine Ausschlussliste, und wählen Sie den Bereich für jede Anforderung aus.
Suche in eigenen Ressourcen Beschränken Sie einen Supportassistenten oder eine mitarbeiterorientierte Sucherfahrung auf Ihre öffentlichen Produkt-, Hilfe- oder Unternehmenswebsites. Schließen Sie Ihre eigenen Domänen und relevante Dokumentationspfade ein.
Kuratierte Nachrichtenüberwachung Stützen Sie Nachrichtenzusammenfassungen auf eine ausgewählte Gruppe von Herausgebern. Schließen Sie die Publisher-Domänen ein, und wählen Sie den Gültigkeitsbereich in Nachrichtensuchanforderungen aus.

Scopes filtern Inhalte, die für den ausgewählten Suchendpunkt verfügbar sind. Eine eingeschlossene Quelle garantiert nicht, dass übereinstimmende Inhalte indiziert oder zurückgegeben werden.

Prerequisites

  • Ein aktives Web IQ-Abrechnungskonto.
  • Zum Erstellen von Bereichen mit der API benötigen Sie eine vorhandene Microsoft Entra-Anwendung, ihre Mandanten-ID und Anwendungs-ID (Client-ID) sowie Anmeldeinformationen für den OAuth 2.0-Clientanmeldeinformationsfluss. Ihre Workloadidentität muss aktiv sein und auf dem vorgesehenen Web IQ-Abrechnungskonto über CustomerApiAccess verfügen.

Von Bedeutung

Der Zugriff auf die Such-APIs und die Web IQ-Verwaltungs-API wird separat gewährt. Ein funktionierender Such-API-Schlüssel oder eine an ein Web IQ-Laufzeitprofil gebundene Entra-Anwendung gewährt keine Berechtigung zum Erstellen von Bereichen. Die Workload benötigt eine separate Berechtigung zur Verwaltung des Abrechnungskontos.

Um den Portalzugriff zu überprüfen, öffnen Sie Bereiche und suchen Sie nach dem vorgesehenen Abrechnungskonto und dem Steuerelement Neuer Bereich. Wenn die Seite, das Konto oder die Erstellungssteuerung nicht verfügbar ist, bitten Sie Ihren Kontoadministrator, Ihren Zugriff zu überprüfen, oder wenden Sie sich an den Web IQ-Support.

Scope benennen und Quellen auswählen

Wählen Sie nach dem Kürzen einen Bereichsnamen mit bis zu 128 Zeichen aus. Unterstützte Zeichen sind ASCII-Buchstaben, Ziffern, Punkte (.), Unterstriche (_) und Bindestriche (-). Leerzeichen und Schrägstriche werden nicht unterstützt. Namen sind innerhalb der Bereichssammlung ohne Unterscheidung von Groß- und Kleinschreibung eindeutig.

Scopes werden von den Web IQ AppIDs in einem Web IQ-Abrechnungskonto über die zugewiesene Scope-Sammlung dieses Kontos geteilt. Sie sind keine separaten Konfigurationen für jede AppID. Wenn Abrechnungskonten eine Sammlung gemeinsam nutzen, verwenden sie dieselben Geltungsbereiche und Namen.

  • Einschluss schränkt Ergebnisse auf Quellen ein, die mindestens einem Eintrag in der Einschlussliste des Bereichs entsprechen. Wenn die Liste leer ist, sind alle nicht ausgeschlossenen Quellen berechtigt.
  • Ausschluss entfernt Ergebnisse, die einem Eintrag in der ausgeschlossenen Liste des Bereichs entsprechen, auch wenn sie auch mit einer Inklusionsregel übereinstimmen. Ausschluss hat immer Vorrang.

Sie können Domänen, URL-Pfade oder einzelne Webseiten einschließen oder ausschließen. Jeder Eintrag wird als Selektor bezeichnet:

Selektor Example Übereinstimmungen
Domäne example.com Die Domäne und die untergeordneten Unterdomänen
Pfadpräfix docs.example.org/products Der angegebene Pfad und seine Unterpfade auf diesem Host, aber keine Pfade wie /products-old
Genaue URL https://docs.example.org/products/guide Genau diese HTTPS-URL, nicht jede Seite unter dem Pfad

Durch das Hinzufügen von https:// wird bewirkt, dass ein Selektor mit einer exakten URL statt mit einer Domain oder einem Pfadpräfix übereinstimmt. Wildcards wie *.example.comexplizite Ports, Abfragezeichenfolgen und Fragmente werden nicht unterstützt. Die Pfad-Groß-/Kleinschreibung wird beibehalten. Selektoren mit benanntem Geltungsbereich haben keinen separaten Grenzwert für die Unterverzeichnistiefe, aber jeder Selektor muss vor dem Kürzen und nach der Normalisierung innerhalb von 2.048 Zeichen liegen.

Die API normalisiert, sortiert und dedupliziert Einträge. Ein akzeptierter Selektor garantiert nicht, dass übereinstimmende Inhalte indiziert oder zurückgegeben werden.

Bereich im Portal erstellen

  1. Öffnen Sie Scopes im Web IQ portal.
  2. Wählen Sie das gewünschte Abrechnungskonto aus.
  3. Wählen Sie Neuer Bereich aus. Geben Sie in Neuen Bereich erstellen einen Bereichsnamen ein, z. B. ProductDocs, und erstellen Sie den Bereich.
  4. Verwenden Sie auf der Bereichsdetailseite „Websites hinzufügen“ auf der Registerkarte „Einbezogen“, um einzubeziehende Quellen hinzuzufügen. Verwenden Sie dieselbe Schaltfläche auf der Registerkarte Ausgeschlossen, um auszuschließende Quellen hinzuzufügen, z. B. ads.example.com.
  5. Überprüfen Sie beide Listen, wählen Sie Veröffentlichen aus, und bestätigen Sie Änderungen veröffentlichen?.

Nach der Veröffentlichung dauert die Verteilung in der Regel etwa 10 Minuten, kann jedoch in einigen Fällen bis zu 30 Minuten dauern. Überprüfen Sie den Bereich , bevor Sie ihn in Ihrer Anwendung verwenden.

Wählen Sie den Scope in Suchanfragen aus

Konfigurieren Sie die Laufzeitsuchauthentifizierung separat. Das ausgewählte Web IQ App-Profil muss zum Web IQ-Abrechnungskonto gehören, dessen Sammlung Ihren Scope enthält.

Legen Sie die folgenden optionalen Felder im JSON-Anforderungstext für POST https://api.microsoft.ai/v3/search/web, POST https://api.microsoft.ai/v3/search/news oder POST https://api.microsoft.ai/v3/auto fest. Alle drei Endpunkte verwenden dieselben Einstellungen für den benannten Bereich.

Parameter Type Behavior
scopeName string Der Name eines vorhandenen Scope, z. B. ProductDocs. Die Einschluss- und Ausschlussregeln filtern die Ergebnisse der Anfrage. Für „Auto“ schränken Scopes nur Web- und Newsergebnisse ein. Andere Antworttypen werden nicht nach dem Bereich gefiltert und können Ergebnisse außerhalb des Bereichs enthalten, auch wenn scopeApplied auf true festgelegt ist. Wenn dies weggelassen wird oder null, wird kein benannter Bereich angefordert.
failOnMissingScope boolean Der Standardwert ist null, auch wenn er ausgelassen oder true ist. Wenn true, wird bei einem gemeldeten Fehler bei der Bereichsanwendung ein Fehler statt nicht bereichsbezogener Ergebnisse zurückgegeben. Wenn false, kann die Suche ohne den Geltungsbereich fortgesetzt werden, wenn der Geltungsbereich nicht angewendet werden kann. Verwenden Sie false nur, wenn bereichslose Ergebnisse zulässig sind. Hat keine Wirkung ohne scopeName.

Verwenden Sie in den folgenden Beispielen einen separat konfigurierten Laufzeit-API-Schlüssel.

Websuchergebnisse filtern

Um von ProductDocs zugelassene Webseiten zu durchsuchen, senden Sie:

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
}

News-Suchergebnisse filtern

Verwenden Sie den News Search-Endpunkt, um Nachrichtenartikel zu durchsuchen, die durch denselben Gültigkeitsbereich zugelassen sind. Wählen Sie eingeschlossene Quellen mit indizierten Nachrichteninhalten aus. Eine enthaltene Webseite ist nicht unbedingt über die Nachrichtensuche verfügbar.

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
}

Automatische Ergebnisse filtern

Für Auto werden nur Web- und Nachrichtenergebnisse durch Bereiche eingeschränkt. Andere Antworttypen werden nicht nach dem Bereich gefiltert und enthalten möglicherweise Ergebnisse außerhalb des Bereichs, auch wenn scopeAppliedtrue gesetzt ist. Schließen Sie responseFilter: ["web", "news"] ein, wenn Sie nur bereichsbezogene Web- und News-Belege verwenden möchten:

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

Interpretieren der Ergebnisse

Die Websuche gibt Ergebnisse in webResults zurück, News Search gibt Ergebnisse in newsResults zurück, und Auto gibt Nachweiselemente in results (AutoEvidenceResponse) zurück. Ein gültiger Bereich kann keine übereinstimmenden Ergebnisse zurückgeben, z. B. wenn kein indizierter Inhalt sowohl mit der Abfrage als auch mit den Regeln des Bereichs übereinstimmt.

Bei failOnMissingScope: true (Standardeinstellung) gibt ein gemeldeter Fehler bei der Bereichsanwendung einen Fehler anstelle von nicht bereichsbezogenen Ergebnissen zurück. Ein bestätigter fehlender Scope gibt HTTP 400 (HandlerInvalidInput) zurück; andere Fehler bei der Anwendung des Scope geben HTTP 500 (ScopeFailedToApply) zurück. Anweisungen zur Wiederherstellung finden Sie unter Fehler bei benannten Bereichen.

Wenn Sie failOnMissingScope auf "scopeApplied": false festlegen und der Bereich nicht gefunden werden kann, wird die Suche mit dem gesamten Index ohne den Bereich ausgeführt, und die Antwort enthält false. Dies kann passieren, wenn der Name falsch ist oder der Bereich noch nicht an die Partition oder das Replikat weitergegeben wurde, die die Anforderung verarbeitet.

Wenn der angeforderte Gültigkeitsbereich gefunden und angewendet wird, enthält die Antwort "scopeApplied": true, auch wenn failOnMissingScopefalse ist. Dadurch wird die Anwendung des Bereichs für diese Anfrage bestätigt, nicht dass die neueste Definition verwendet wurde oder dass die Änderung jede Partition oder jedes Replikat erreicht hat. In der Antwort wird scopeApplied weggelassen, wenn kein Anwendungsergebnis gemeldet wird; behandeln Sie eine fehlende Eigenschaft nicht als Nachweis dafür, dass der Scope angewendet wurde.

Wenn Sie null weglassen oder auf scopeName festlegen, wird kein benannter Bereich angefordert und failOnMissingScope hat keine Auswirkung. Erwarten Sie nicht, dass scopeApplied bei Anfragen ohne benannten Scope immer mit dem Wert false vorhanden ist.

Verwenden Sie false nur, wenn Ihre Anwendung nicht eingeschränkte Ergebnisse akzeptieren kann und scopeApplied in der Antwort überprüft. Wenn ein Geltungsbereich erforderlich ist, implementieren Sie keinen Fallback, der ihn entfernt und eine uneingeschränkte Anfrage erneut sendet. Informationen zu den Anforderungsparametern und Antwortfeldern finden Sie unter "Websuche", "Nachrichtensuche" und "Auto-Referenz".

Einen Bereich mit der API erstellen

Alle Verwaltungsanforderungen verwenden https://api.microsoft.ai mit Pfaden, die mit /v1/customer/ beginnen. Ersetzen Sie <billingAccountId> und <access-token> in den Beispielen durch die gewünschte Konto-ID und ein Nur-App-Zugriffstoken. Die Referenz zu autorisierten Ressourcen und Referenz zur Bereichsverwaltung beschreiben die Endpunktverträge.

Verwaltungs-API-Zugriff für die Anwendung gewähren

Ein Administrator für Abrechnungskonten oder Kunden gewährt Zugriff:

  1. Verwenden Sie eine vorhandene Microsoft Entra App-Registrierung oder registrieren Sie eine Anwendung im Azure-Portal.
  2. Öffnen Sie die Kontoeinstellungen im Web IQ-Portal.
  3. Wählen Sie das beabsichtigte Abrechnungskonto aus.
  4. Wählen Sie unter Verwaltungs-API-Zugriffdie Option "Zugriff auf eine Entra-App gewähren" aus.
  5. Bestätigen Sie im Dialogfeld Einer Entra-Anwendung Zugriff auf dieses Abrechnungskonto gewähren den Namen und die ID des Abrechnungskontos. Geben Sie die Mandanten-ID und die Anwendungs-ID (Client-ID) der Anwendung und einen Wert für den erforderlichen Anzeigenamen ein.
  6. Wählen Sie Verwaltungs-API-Zugriff für diese Anwendung gewähren und dann Zugriff gewähren aus.

Das Erteilen von Zugriff autorisiert eine vorhandene Identität. Es erstellt keine Entra-Anwendung, keinen geheimen Schlüssel, kein Zertifikat oder einen Such-API-Schlüssel. Die Zuweisung gilt für das ausgewählte Abrechnungskonto.

Die Berechtigung weist die CustomerApiAccess Rolle zu. Es handelt sich nicht um eine Berechtigung nur für Bereiche oder nur mit Lesezugriff: sie ermöglicht die Kontenermittlung, das Lesen und Schreiben von Bereichen sowie die Entra ID-Verwaltung des Laufzeitprofils. Sie erlaubt der Anwendung nicht, anderen Anwendungen Zugriff zu gewähren. Beschränken Sie das Gewähren auf Anwendungen, die diese Verwaltungsfunktionen benötigen.

Abrufen eines App-Only-Tokens

Verwenden Sie die vorhandenen Anmeldeinformationen Ihrer Anwendung und den Clientanmeldeinformationsfluss, um ein Microsoft Entra Zugriffstoken anzufordern:

Setting Wert
Autorität https://login.microsoftonline.com/<tenant-id>
Bereich für Tokenanforderungen https://api.microsoft.ai/.default

Verwenden Sie den exakten .default Scope, nicht den Namen des Such-Scopes, den Sie erstellen. Senden Sie das Token für jede Verwaltungsanforderung:

Authorization: Bearer <access-token>

Verwenden Sie keinen Such-API-Schlüssel für diese Verwaltungsaufrufe. Halten Sie Zugriffstoken und Anwendungsanmeldeinformationen von der Quellcodeverwaltung und aus Diagnoseberichten fern.

Abrechnungskonto ermitteln

Rufen Sie GET https://api.microsoft.ai/v1/customer/authorized-resources mit Ihrem Nur-App-Token auf. Wählen Sie für die Erstellungsanfrage die billingAccounts[].billingAccountId des beabsichtigten Kontos aus. Wählen Sie nicht automatisch das erste Konto aus.

Verwenden Sie die authorized-resources-Referenz für das Antwortschema, ID-Definitionen und die Interpretation von Berechtigungsfeldern.

Senden Sie die Erstellungsanforderung

Senden Sie mithilfe der ausgewählten Abrechnungskonto-ID POST /v1/customer/billing-accounts/{billingAccountId}/scopes Ihren Scope-Namen und -regeln. Beispiele:

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

Stellen Sie beide Arrays bereit und verwenden Sie [] für eine absichtlich leere Liste. Unter 201 Created speichern Sie die zurückgegebene Definition und das ETag für spätere Änderungen.

Informationen zu Kopfzeilen, Validierungsregeln und Antwortdetails finden Sie im Create-Scope-Vertrag. Um einen vorhandenen Bereich zu ändern, anstatt einen neuen zu erstellen, verwenden Sie die Aktualisierungsvorgänge.

Überprüfen Sie den Geltungsbereich vor der Verwendung

  1. Lesen Sie den gespeicherten Scope und vergewissern Sie sich, dass seine Regeln den von Ihnen beabsichtigten Quellen entsprechen.
  2. Führen Sie repräsentative Websuche-, Nachrichtensuche- oder automatische Anfragen mit failOnMissingScope: true aus. Überprüfen Sie eingeschlossene und ausgeschlossene Fälle, bevor Sie abhängigen Traffic aktivieren.

Von Bedeutung

Die Verteilung dauert in der Regel etwa 10 Minuten, kann aber in einigen Fällen bis zu 30 Minuten dauern. Es gibt keine SLA für die Verteilung, und diese Anzeigedauern sind nicht garantiert. Eine erfolgreiche Verwaltung schreibt oder liest, veröffentlicht oder scopeApplied: true beweist nicht, dass die neueste Definition aktiv ist. Verwenden Sie die verstrichene Zeit nicht allein als Prüfung der Einsatzbereitschaft. Siehe Suchverteilung für Details.

Bereitstellen einer geänderten Definition

Wenn die Verwendung einer vorherigen Definition vorübergehend inakzeptabel ist, erstellen Sie einen Bereich mit einem neuen Namen, wie ProductDocs-v2. Führen Sie die oben genannten Überprüfungsschritte aus, bevor Sie aufrufende Funktionen wechseln, und behalten Sie den vorherigen Gültigkeitsbereich bei, bis aufrufende Funktionen nicht mehr davon abhängig sind.

Dadurch bleibt die Bedeutung des alten Namens während der Überprüfung unverändert; es bietet keinen atom-globalen Switch.

Parallelitätsschutz für spätere Änderungen beibehalten

Lesen Sie den aktuellen Scope, bevor Sie ihn bearbeiten oder löschen, und senden Sie das in Anführungszeichen gesetzte ETag in If-Match. Befolgen Sie Hinweise zu Parallelität und ungewissem Ergebnis, wenn Sie gleichzeitige Bearbeitungen abgleichen oder einen Schreibvorgang wiederholen. Behalten Sie überprüfte Definitionen in Ihrer eigenen maßgeblichen Quelle bei, wenn Sie den Änderungsverlauf benötigen.

Problembehandlung bei der Erstellung

Wenn das beabsichtigte Konto in Discovery nicht vorhanden ist, bitten Sie den Administrator, die Identität, die Verwaltungsberechtigung und die Kontoberechtigung der Workload zu überprüfen. Verwenden Sie bei anderen Fehlern die Referenz zum Discovery-Status oder die Fehlerreferenz für die Bereichsverwaltung.

Wenden Sie sich bei dauerhaften Fehlern an den Web IQ-Support mit der Abrechnungskonto-ID, dem Scope-Namen, dem Zeitpunkt des Vorgangs in UTC, dem HTTP-Status und den verfügbaren Anforderungs-IDs. Geben Sie bereinigtes erwartetes und tatsächliches Verhalten an, niemals Token, API-Schlüssel oder Anwendungsanmeldeinformationen.