Filtrowanie wyników za pomocą zakresów

Zakresy w usłudze Microsoft Web IQ umożliwiają dostosowywanie żądań interfejsu API uziemienia przez uwzględnienie lub wykluczenie adresów URL, witryn i domen z wyników wyszukiwania w sieci Web i wyszukiwania wiadomości.

Deweloperzy i administratorzy przedsiębiorstw mogą używać Scopes do opierania środowisk AI na zatwierdzonych i pożądanych źródłach internetowych. Zdefiniuj listy dołączania i wykluczania wielokrotnego użytku dla adresów URL, domen i ścieżek w celu kontrolowania, które źródła mogą być zwracane przez wyszukiwania oparte na źródłach.

Zakres to nazwana konfiguracja reguł dołączania i wykluczania. Utwórz go w internetowym portalu IQ lub interfejsie API zarządzania klientami dla konta rozliczeniowego, a następnie wybierz go według nazwy w żądaniach wyszukiwania w sieci Web lub wyszukiwania wiadomości. Obie opcje zarządzania działają z tymi samymi nazwanymi zakresami. Te zakresy wyszukiwania nie są Microsoft Entra zakresami uprawnień OAuth.

Scenariusze biznesowe i typowe przypadki użycia

Scenario Przykładowy przypadek użycia Jak używać Scopes
Wyselekcjonowane badania Oprzyj działanie asystenta badawczego na źródłach zweryfikowanych przez organizację, takich jak zatwierdzone publikacje medyczne. Uwzględnij zatwierdzone domeny, poddomeny lub poszczególne strony.
Zasady dotyczące źródeł organizacyjnych Wyklucz domeny objęte ograniczeniami nałożonymi przez Twoją organizację z wyników wyszukiwania w sieci Web i wyszukiwania wiadomości. Zachowaj listę wykluczeń i wybierz zakres dla każdego żądania.
Wyszukiwanie w zasobach własnych Ogranicz asystenta pomocy technicznej lub wyszukiwanie dostępne dla pracowników do publicznych witryn produktu, pomocy lub firmy. Uwzględnij domeny należące do Użytkownika i odpowiednie ścieżki dokumentacji.
Monitorowanie wybranych wiadomości Oprzyj podsumowania wiadomości na wybranym zestawie wydawców. Uwzględnij domeny wydawcy i wybierz zakres w żądaniach wyszukiwania wiadomości.

Zakresy filtrują zawartość dostępną dla wybranego punktu końcowego wyszukiwania. Dołączone źródło nie gwarantuje, że pasująca zawartość jest indeksowana lub zwracana.

Prerequisites

  • Aktywne konto rozliczeniowe Web IQ.
  • Aby utworzyć zakresy za pomocą interfejsu API, istniejąca aplikacja Microsoft Entra, identyfikator dzierżawy i identyfikator aplikacji (klienta) oraz poświadczenia przepływu poświadczeń klienta OAuth 2.0 są wymagane. Tożsamość obciążenia roboczego musi być aktywna i musi mieć CustomerApiAccess na docelowym koncie rozliczeniowym Web IQ.

Important

Dostęp do interfejsów API wyszukiwania i interfejsu API zarządzania Web IQ jest udzielany oddzielnie. Działający klucz interfejsu API wyszukiwania lub aplikacja Entra powiązana z profilem środowiska uruchomieniowego Web IQ nie udziela uprawnień do tworzenia zakresów. Obciążenie robocze wymaga oddzielnego uprawnienia do zarządzania kontem rozliczeniowym.

Aby sprawdzić dostęp do portalu, otwórz pozycję Zakresy i poszukaj odpowiedniego konta rozliczeniowego i przycisku Nowy zakres. Jeśli strona, konto lub kontrola tworzenia jest niedostępna, poproś administratora konta o sprawdzenie dostępu lub skontaktuj się z Web IQ Support.

Nadaj zakresowi nazwę i wybierz źródła

Wybierz nazwę zakresu z maksymalnie 128 znakami po usunięciu zbędnych spacji. Obsługiwane znaki to litery ASCII, cyfry, kropki (.), podkreślenia (_) i łączniki (-). Spacje i ukośniki nie są obsługiwane. Nazwy są unikalne niezależnie od wielkości liter w kolekcji zakresów.

Zakresy są współużytkowane przez identyfikatory AppID Web IQ na koncie rozliczeniowym Web IQ za pośrednictwem przypisanej kolekcji zakresów tego konta. Nie są one oddzielnymi konfiguracjami dla każdego identyfikatora AppID. Jeśli konta rozliczeniowe współużytkują kolekcję, mają te same zakresy i nazwy.

  • Uwzględnianie ogranicza wyniki do źródeł, które pasują do co najmniej jednego wpisu na liście uwzględnień zakresu. Jeśli lista jest pusta, wszystkie nie wykluczone źródła kwalifikują się.
  • Wykluczenie usuwa wyniki zgodne z dowolnym wpisem na liście wykluczeń zakresu, nawet jeśli są one również zgodne z regułą dołączania. Wykluczenie zawsze ma pierwszeństwo.

Można dołączać lub wykluczać domeny, ścieżki url lub poszczególne strony sieci Web. Każdy wpis jest nazywany selektorem:

Selector Example Dopasowania
Domain example.com Domena i jej poddomeny podrzędne
Prefiks ścieżki docs.example.org/products Określona ścieżka i jej ścieżki podrzędne na tym hoście, ale nie ścieżki, takie jak /products-old
Dokładny adres URL https://docs.example.org/products/guide Ten dokładny adres URL HTTPS, nie wszystkie strony w tej ścieżce

Dodanie https:// powoduje, że selektor dopasowuje dokładny adres URL, a nie prefiks domeny lub ścieżki. Symbole wieloznaczne, takie jak *.example.com, jawne porty, ciągi zapytania i fragmenty nie są obsługiwane. Wielkość liter ścieżki jest zachowywana. Selektory nazwanych zakresów nie mają oddzielnego limitu głębokości podkatalogu, ale każdy selektor nie może przekraczać 2048 znaków przed przycinaniem i po normalizacji.

Interfejs API normalizuje, sortuje i deduplikuje wpisy. Zaakceptowany selektor nie gwarantuje, że zgodna zawartość jest indeksowana lub zwracana.

Utwórz zakres w portalu

  1. Otwórz Scopes w portalu Web IQ.
  2. Wybierz właściwe konto rozliczeniowe.
  3. Wybierz Nowy zakres. W oknie Utwórz nowy zakres wprowadź nazwę zakresu, taką jak ProductDocs, i utwórz zakres.
  4. Na stronie szczegółów zakresu użyj opcji Dodaj witryny na karcie Uwzględnione, aby dodać źródła do uwzględnienia. Użyj tego samego przycisku na karcie Wykluczone , aby dodać źródła do wykluczenia, takie jak ads.example.com.
  5. Przejrzyj obie listy, wybierz pozycję Publikuj i potwierdź Opublikować zmiany?.

Po opublikowaniu propagacja wyszukiwania zwykle trwa około 10 minut, ale w niektórych przypadkach może upłynąć do 30 minut. Sprawdź zakres przed poleganiem na nim w aplikacji.

Wybieranie zakresu w żądaniach wyszukiwania

Oddzielnie skonfiguruj uwierzytelnianie wyszukiwania w czasie wykonywania . Wybrany profil aplikacji Web IQ musi należeć do konta rozliczeniowego Web IQ, którego kolekcja zawiera Twój zakres uprawnień.

Ustaw następujące opcjonalne pola w treści żądania JSON dla POST https://api.microsoft.ai/v3/search/web lub POST https://api.microsoft.ai/v3/search/news. Oba punkty końcowe używają tych samych ustawień nazwanych zakresów.

Parametr Typ Behavior
scopeName ciąg Nazwa istniejącego zakresu, na przykład ProductDocs. Reguły dołączania i wykluczania filtrują wyniki żądania. Jeśli pominięto lub null, żaden nazwany zakres nie jest żądany.
failOnMissingScope boolean Wartość domyślna to true, w tym w przypadku pominięcia lub null. Gdy true, zgłoszony błąd zastosowania zakresu powoduje zwrócenie błędu zamiast wyników bez zakresu. Jeśli falsenie można zastosować zakresu, wyszukiwanie może być kontynuowane bez zakresu. Użyj false tylko wtedy, gdy wyniki bez zakresu są akceptowalne. Nie ma żadnego efektu bez scopeName.

W poniższych przykładach użyj oddzielnego skonfigurowanego klucza interfejsu API środowiska uruchomieniowego.

Filtrowanie wyników wyszukiwania w Internecie

Aby wyszukać strony internetowe dozwolone przez usługę ProductDocs, wyślij:

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
}

Filtrowanie wyników wyszukiwania wiadomości

Aby wyszukać artykuły prasowe dozwolone w tym samym zakresie, użyj punktu końcowego wyszukiwania wiadomości. Wybierz uwzględnione źródła z indeksowaną zawartością wiadomości; uwzględniona strona internetowa nie musi być dostępna za pośrednictwem funkcji wyszukiwania wiadomości.

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
}

Interpretacja wyników

Funkcja wyszukiwania w sieci Web zwraca wyniki w webResults; Funkcja Wyszukiwania wiadomości zwraca wyniki w newsResults. Prawidłowy zakres może nie zwracać pasujących wyników, na przykład gdy żadna indeksowana zawartość nie pasuje zarówno do zapytania, jak i reguł zakresu.

W przypadku failOnMissingScope: true (wartość domyślna) zgłoszony błąd podczas stosowania zakresu zwraca błąd zamiast wyników bez zastosowanego zakresu. Potwierdzony brak zakresu zwraca błąd HTTP 400 (HandlerInvalidInput); inne błędy aplikacji zakresu zwracają błąd HTTP 500 (ScopeFailedToApply). Aby uzyskać wskazówki dotyczące odzyskiwania, zobacz błędy dotyczące nazwanych zakresów.

Jeśli ustawisz failOnMissingScope na false, a zakresu nie można odnaleźć, wyszukiwanie zostanie uruchomione względem całego indeksu bez zakresu, a odpowiedź zawiera "scopeApplied": false. Może się tak zdarzyć, gdy nazwa jest nieprawidłowa lub zakres nie został jeszcze rozpropagowany do partycji lub repliki obsługującej żądanie.

Po znalezieniu żądanego zakresu i zastosowaniu go odpowiedź zawiera "scopeApplied": true, nawet jeśli failOnMissingScope ma wartość false. Potwierdza to zastosowanie zakresu dla tego żądania, a nie, że została użyta jego najnowsza definicja lub że zmiana osiągnęła każdą partycję lub replikę. Odpowiedź pomija scopeApplied , gdy nie jest zgłaszany żaden wynik aplikacji; nie traktuj nieobecnej właściwości jako dowód, że zakres został zastosowany.

Jeśli pominiesz scopeName lub ustawisz je na null, nie zostanie zażądany nazwany zakres i failOnMissingScope nie ma żadnego wpływu. Nie należy oczekiwać, że scopeApplied będzie zawsze obecne z wartością false dla żądań bez nazwanego zakresu.

Użyj false tylko wtedy, gdy aplikacja może akceptować niezakresowe wyniki, i sprawdź scopeApplied w odpowiedzi. Jeśli zakres jest wymagany, nie implementuj mechanizmu awaryjnego, który go usuwa i ponawia próbę nieograniczonego żądania. Zapoznaj się z odwołaniami wyszukiwania w sieci Web i wyszukiwania wiadomości, aby uzyskać informacje o parametrach żądania i polach odpowiedzi.

Tworzenie zakresu za pomocą interfejsu API

Wszystkie żądania zarządzania używają https://api.microsoft.ai ze ścieżkami rozpoczynającymi się od /v1/customer/. Zastąp w przykładach <billingAccountId> i <access-token> docelowym identyfikatorem konta i tokenem dostępu tylko do aplikacji. dokument referencyjny dotyczący autoryzowanych zasobów i dokument referencyjny dotyczący zarządzania zakresem opisują kontrakty punktów końcowych.

Przyznawanie aplikacji dostępu do interfejsu API zarządzania

Administrator konta rozliczeniowego lub administrator klienta udziela dostępu:

  1. Użyj istniejącej rejestracji aplikacji Microsoft Entra lub zarejestruj aplikację w portalu Azure.
  2. Otwórz ustawienia konta w portalu Web IQ.
  3. Wybierz zamierzone konto rozliczeniowe.
  4. W obszarze Dostęp do interfejsu API zarządzania wybierz pozycję Udziel dostępu do aplikacji Entra.
  5. W oknie dialogowym Udzielanie aplikacji Entra dostępu do tego konta rozliczeniowego potwierdź nazwę i identyfikator konta rozliczeniowego. Wprowadź identyfikator dzierżawy i identyfikator aplikacji (klienta) oraz niepustą wartość dla wymaganego pola Nazwa wyświetlana.
  6. Wybierz pozycję Udziel tej aplikacji dostępu do interfejsu API zarządzania, a następnie wybierz pozycję Udziel dostępu.

Udzielanie dostępu autoryzuje istniejącą tożsamość. Nie tworzy aplikacji Entra, klucza tajnego, certyfikatu ani klucza interfejsu API wyszukiwania. Grant ma zastosowanie do wybranego konta rozliczeniowego.

To uprawnienie przypisuje rolę CustomerApiAccess. Nie jest to uprawnienie tylko do zakresów ani tylko do odczytu: umożliwia odnajdywanie kont, odczyt i zapis zakresów oraz zarządzanie profilem środowiska uruchomieniowego Entra ID. Nie zezwala aplikacji na udzielanie dostępu innym aplikacjom. Ogranicz przyznanie do aplikacji, które potrzebują tych funkcji zarządzania.

Uzyskiwanie tokenu tylko dla aplikacji

Użyj istniejących poświadczeń aplikacji i przepływu poświadczeń klienta, aby zażądać tokenu dostępu Microsoft Entra:

Setting Value
Władza https://login.microsoftonline.com/<tenant-id>
Zakres żądania tokenu https://api.microsoft.ai/.default

Użyj zakresu .default dokładnie takiego, a nie nazwy tworzonego zakresu wyszukiwania. Wyślij token na każde żądanie zarządzania:

Authorization: Bearer <access-token>

Nie używaj klucza interfejsu API wyszukiwania dla tych wywołań zarządzania. Nie umieszczaj tokenów dostępu ani poświadczeń aplikacji w kontroli źródła ani w raportach diagnostycznych.

Odnajdowanie konta rozliczeniowego

Wywołaj metodę GET https://api.microsoft.ai/v1/customer/authorized-resources za pomocą tokenu tylko dla aplikacji. Wybierz odpowiednie konto billingAccounts[].billingAccountId dla żądania utworzenia. Nie wybieraj automatycznie pierwszego konta.

Użyj referencji authorized-resources jako odniesienia do schematu odpowiedzi, definicji identyfikatorów i interpretacji pola uprawnień.

Wyślij żądanie utworzenia

Przy użyciu wybranego identyfikatora konta rozliczeniowego wyślij POST /v1/customer/billing-accounts/{billingAccountId}/scopes z nazwą zakresu i regułami. Na przykład:

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

Podaj obie tablice, używając [] dla celowo pustej listy. W 201 Created zapisz zwróconą definicję i element ETag, aby później wprowadzić zmiany.

Informacje o nagłówkach, regułach walidacji i szczegółach odpowiedzi znajdziesz w kontrakcie tworzenia zakresu. Aby zmienić istniejący zakres, a nie utworzyć nowego, użyj operacji aktualizacji.

Zweryfikuj zakres przed użyciem

  1. Odczytaj zapisany zakres wyszukiwania i upewnij się, że jego reguły są zgodne z zamierzonymi źródłami.
  2. Uruchom reprezentatywne żądania wyszukiwania w sieci Web i wyszukiwania wiadomości za pomocą polecenia failOnMissingScope: true. Przed włączeniem ruchu zależnego sprawdź uwzględnione i wykluczone przypadki.

Important

Propagacja zwykle trwa około 10 minut, ale w niektórych przypadkach może potrwać do 30 minut. Nie ma SLA dla propagacji i te terminy nie są gwarantowane. Pomyślna operacja zapisu lub odczytu zarządzania, Publish lub scopeApplied: true nie dowodzi, że najnowsza definicja jest aktywna. Nie używaj samego czasu, który upłynął, jako sprawdzenia gotowości. Szczegółowe informacje znajdziesz w propagacji wyszukiwania.

Wdróż zmienioną definicję

Jeśli tymczasowe użycie poprzedniej definicji jest niedopuszczalne, utwórz zakres z nową nazwą, taką jak ProductDocs-v2. Wykonaj powyższe kroki weryfikacji przed przełączeniem modułów wywołujących i zachowaj poprzedni zakres, dopóki moduły wywołujące nie będą już od niego zależeć.

Zachowuje to znaczenie starej nazwy bez zmian podczas walidacji; nie zapewnia atomowego globalnego przełączenia.

Zachowywanie ochrony współbieżności na potrzeby późniejszych zmian

Przeczytaj bieżący zakres przed jego edytowaniem lub usunięciem i wyślij cytowany element ETag w pliku If-Match. Postępuj zgodnie ze wskazówkami dotyczącymi współbieżności i niepewnego wyniku podczas uzgadniania współbieżnych edycji lub ponawiania próby zapisu. Przejrzyj definicje we własnym źródle prawdy, jeśli potrzebujesz historii zmian.

Rozwiązywanie problemów z tworzeniem

Jeśli zamierzone konto nie występuje w wynikach odnajdywania, poproś administratora o sprawdzenie tożsamości obciążenia roboczego, uprawnień do zarządzania i kwalifikowania się konta. W przypadku innych niepowodzeń użyj informacji o stanie wykrywania lub informacji o błędach zarządzania zakresem.

W przypadku trwałych niepowodzeń skontaktuj się z pomocą techniczną internetowego IQ przy użyciu identyfikatora konta rozliczeniowego, nazwy zakresu, czasu operacji w formacie UTC, stanu HTTP i dostępnych identyfikatorów żądań. Uwzględnij oczekiwane i rzeczywiste zachowanie, nigdy nie tokeny, klucze interfejsu API lub poświadczenia aplikacji.

  • Ostatnia aktualizacja o