Behandeln von Problemen mit freigegebenen privaten Links in Foundry IQ (Azure KI-Suche)

Note

Foundry IQ (Azure KI-Suche) bietet direkte Indizierungs- und Abfrage-APIs zusammen mit Wissensquellen- und Knowledge Base-APIs auf höherer Ebene für den verwalteten Abruf. Verwenden Sie das Azure Portal, REST-APIs oder Azure SDKs, um diese Funktionen zu konfigurieren, oder verbinden Sie Agents mit Wissensdatenbanken im Microsoft Foundry-Portal.

Mit einem freigegebenen privaten Link kann Foundry IQ (Azure KI-Suche) sichere ausgehende Verbindungen über einen privaten Endpunkt herstellen, wenn sie auf Kundenressourcen in einem virtuellen Netzwerk zugreifen. Dieser Artikel hilft Ihnen beim Beheben von Fehlern, die auftreten können.

Das Erstellen eines freigegebenen privaten Links ist ein Vorgang der Foundry IQ-Servicekontrollebene. Eine freigegebene private Verbindung kann entweder über das Azure-Portal oder eine Verwaltungs-REST-API erstellt werden. Während der Bereitstellung ist der Status der Anforderung Updating. Nachdem der Vorgang erfolgreich abgeschlossen wurde, lautet Succeededder Status . Es wird ein privater Endpunkt für die Ressource zusammen mit allen DNS-Zonen und -Zuordnungen erstellt. Dieser Endpunkt wird ausschließlich von Ihrer Foundry IQ-Dienstinstanz verwendet und über Foundry IQ verwaltet.

Schritte zum Erstellen freigegebener privater Linkressourcen

Im Folgenden finden Sie häufige Fehler, die während der Erstellungsphase auftreten.

Anforderungsüberprüfungsfehler

  • Nicht unterstützte SKU oder Konfiguration: Überprüfen Sie die Workloadvoraussetzungen und die Wissensquellenkonfiguration und -ebenenmatrix. Generische Indexeranforderungen variieren je nach Skillset, Region und Diensterstellungsdatum und begründen keine Berechtigung für verwaltete Wissensquellen. Überprüfen Sie außerdem die Ziel- und Gruppen-ID anhand der unterstützten Ressourcentypen.

  • Ungültiger Name: Benennungsregeln für eine freigegebene private Verbindung sind:

    • Länge zwischen 1 und 60 Zeichen
    • Alphanumerische Zeichen
    • Namen dürfen Unterstriche (_), Punkte (.) und Bindestriche (-) enthalten, sofern diese nicht das erste Zeichen im Namen sind.
  • Ungültige Gruppen-ID: Bei Gruppen-IDs wird die Groß-/Kleinschreibung beachtet, und es muss einer der folgenden Werte sein.

    Azure-Ressource Gruppen-ID Erste verfügbare API-Version
    Azure Storage: Blob (oder) ADLS Gen2 blob 2020-08-01
    Azure Storage: Tabellen table 2020-08-01
    Azure Cosmos DB für NoSQL-Datenbanklösungen Sql 2020-08-01
    Azure SQL-Datenbank sqlServer 2020-08-01
    Azure Database for MySQL (Vorschau) mysqlServer 2020-08-01-Preview
    Azure Key Vault (ein Dienst zur sicheren Verwaltung kryptografischer Schlüssel) vault 2020-08-01
    Azure Functions (Vorschau) sites 2020-08-01-Preview

    Ressourcen, die mit „(preview)“ gekennzeichnet sind, müssen mit einer Vorschauversion der Versionen der REST-API für die Verwaltung erstellt werden.

  • privateLinkResourceId Typvalidierung: Ähnlich wie groupId validiert Foundry IQ, dass der „richtige“ Ressourcentyp in privateLinkResourceId angegeben ist. Folgende Ressourcentypen sind gültig:

    Azure-Ressource Ressourcentyp Erste verfügbare API-Version
    Azure Storage Microsoft.Storage/storageAccounts 2020-08-01
    Azure Cosmos DB (ein Microsoft-Datenbankdienst) Microsoft.DocumentDb/databaseAccounts 2020-08-01
    Azure SQL-Datenbank Microsoft.Sql/servers 2020-08-01
    Azure Key Vault (ein Dienst zur sicheren Verwaltung kryptografischer Schlüssel) Microsoft.KeyVault/vaults 2020-08-01
    Azure Database for MySQL (Vorschau) Microsoft.DBforMySQL/servers 2020-08-01-Preview
    Azure Functions (Vorschau) Microsoft.Web/sites 2020-08-01-Preview
    Azure SQL Managed Instance (Vorschau) Microsoft.Sql/managedInstance 2020-08-01-Preview

    Darüber hinaus muss die angegebene groupId für den angegebenen Ressourcentyp gültig sein. Beispielsweise ist groupId "blob" für den Typ Microsoft.Storage/storageAccounts gültig, und es kann nicht mit einem anderen Ressourcentyp verwendet werden. Für eine bestimmte Version der Suchverwaltungs-API können Kunden die unterstützte groupId und Ressourcentypdetails herausfinden, indem sie die Liste der unterstützten APIs verwenden.

  • Durchsetzung von Kontingentgrenzen: Foundry IQ-Dienste unterliegen Kontingenten für die Anzahl der Shared Private Link-Ressourcen, die erstellt werden können, sowie für die Anzahl der verwendeten verschiedenen Zielressourcentypen (basierend auf groupId). Weitere Informationen finden Sie unter Ressourcenbeschränkungen für freigegebene private Links.

Bereitstellungsfehler

Ein Foundry IQ-Dienst initiiert die Anforderung, einen freigegebenen privaten Link zu erstellen, aber Azure Resource Manager führt die eigentliche Arbeit aus. Sie können den Status der Bereitstellung im Azure-Portal oder per Abfrage überprüfen und etwaige Fehler beheben.

Freigegebene private Linkressourcen, bei denen die Azure Resource Manager-Bereitstellung fehlschlägt, werden in List- und Get-API-Aufrufen angezeigt, haben aber einen "Bereitstellungsstatus" von Failed. Nachdem der Grund für den Bereitstellungsfehler des Azure Resource Managers festgestellt wurde, löschen Sie die Failed Ressource und erstellen Sie sie neu, nachdem Sie die entsprechende Lösung aus der folgenden Tabelle angewendet haben.

Grund für den Bereitstellungsfehler BESCHREIBUNG Lösung
LinkedAuthorizationFailed Die Fehlermeldung gibt an, dass der Client über die Berechtigung zum Erstellen des freigegebenen privaten Links im Foundry IQ-Dienst verfügt, aber nicht über die Berechtigung zum Ausführen der Aktion "privateEndpointConnectionApproval/action" für den verknüpften Bereich verfügt. Überprüfen Sie die PRIVATE Link-ID in der Anforderung erneut, um sicherzustellen, dass im URI keine Fehler oder Auslassungen vorhanden sind. Wenn sich Foundry IQ und die Azure PaaS-Ressource in verschiedenen Abonnements befinden und wenn Sie REST oder eine Befehlszeilenschnittstelle verwenden, stellen Sie sicher, dass das aktive Azure Konto die Azure PaaS-Ressource ist. Stellen Sie für REST-Clients sicher, dass Sie kein abgelaufenes Bearertoken verwenden und dass das Token für das aktive Abonnement gültig ist.
Netzwerkressourcenanbieter nicht im Abonnement der Zielressource registriert Ein privater Endpunkt (mit den zugehörigen DNS-Zuordnungen) wird für die Zielressource (Speicherkonto, Azure Cosmos DB, Azure SQL) über den Microsoft.Network-Ressourcenanbieter erstellt. Wenn das Abonnement, das die Zielressource hostet („Zielabonnement“), nicht beim Microsoft.Network-Ressourcenanbieter registriert ist, kann die Azure Resource Manager-Bereitstellung fehlschlagen. Sie müssen diesen Ressourcenanbieter in ihrem Zielabonnement registrieren. Sie können den Ressourcenanbieter über das Azure-Portal, PowerShell oder die CLI registrieren.
Ungültige groupId für die Zielressource Beim Erstellen von Azure Cosmos DB-Konten können Sie den API-Typ für das Datenbankkonto angeben. Während Azure Cosmos DB verschiedene API-Typen bietet, unterstützt Foundry IQ nur "Sql" als groupId für freigegebene private Linkressourcen. Wenn eine freigegebene Private Link-Ressource vom Typ „Sql“ für eine privateLinkResourceId erstellt wird, die auf ein Nicht-SQL-Datenbankkonto verweist, schlägt die Azure Resource Manager-Bereitstellung aufgrund des groupId-Konflikts fehl. Die Azure-Ressourcen-ID eines Azure Cosmos DB-Kontos reicht nicht aus, um den verwendeten API-Typ zu bestimmen. Foundry IQ versucht, den privaten Endpunkt zu erstellen, was dann von Azure Cosmos DB verweigert wird. Sie müssen sicherstellen, dass die privateLinkResourceId der angegebenen Azure Cosmos DB-Ressource für ein Datenbankkonto vom API-Typ „Sql“ bestimmt ist.
Zielressource nicht gefunden Das Vorhandensein der in privateLinkResourceId angegebenen Zielressource wird nur während des Beginns der Azure Resource Manager-Bereitstellung überprüft. Wenn die Zielressource nicht mehr verfügbar ist, schlägt die Bereitstellung fehl. Sie müssen sicherstellen, dass die Zielressource im angegebenen Abonnement und in der angegebenen Ressourcengruppe vorhanden ist und nicht verschoben/gelöscht wird.
Vorübergehende/andere Fehler Die Azure Resource Manager-Bereitstellung kann bei einem Ausfall der Infrastruktur oder aus anderen unerwarteten Gründen nicht erfolgreich sein. Dies sollte selten vorkommen und deutet normalerweise auf einen vorübergehenden Zustand hin. Versuchen Sie zu einem späteren Zeitpunkt erneut, diese Ressource zu erstellen. Wenn das Problem weiterhin besteht, wenden Sie sich an den Azure-Support.

Probleme beim Genehmigen des unterstützenden privaten Endpunkts

Ein privater Endpunkt wird in der Azure-Zielressource erstellt, wie in der Anforderung zum Erstellen von freigegebenen privaten Links angegeben. Dieser Schritt ist einer der letzten Schritte im asynchronen Azure Resource Manager Bereitstellungsvorgang, aber Foundry IQ muss die private IP-Adresse des privaten Endpunkts als Teil der Netzwerkkonfiguration verknüpfen. Wenn dieser Link abgeschlossen ist, wechselt die provisioningState Ressource für freigegebene private Verknüpfungen zu einem Terminalerfolgsstatus Succeeded. Kunden sollten den zugrunde liegenden privaten Endpunkt nur genehmigen oder verweigern (oder im Allgemeinen die Konfiguration ändern), nachdem der Zustand zu Succeeded gewechselt hat. Das Ändern des privaten Endpunkts in irgendeiner Weise vor diesem Übergang kann zu einem unvollständigen Bereitstellungsvorgang führen und dazu führen, dass die freigegebene private Linkressource (entweder sofort oder in der Regel innerhalb weniger Stunden) in einem Failed Zustand enden kann.

Änderung der Netzwerkkonnektivität des Foundry IQ-Diensts hängt im Status „Aktualisieren“ fest

Freigegebene private Links und private Endpunkte werden verwendet, wenn der Zugriff auf das öffentliche Netzwerk des Foundry IQ-Diensts deaktiviert ist. In der Regel sollte das Ändern der Netzwerkkonnektivität einige Minuten nach der Annahme der Anforderung erfolgreich sein. Unter bestimmten Umständen kann es bei Foundry IQ mehrere Stunden dauern, den Verbindungsänderungsvorgang abzuschließen.

Screenshot der Änderung des Zugriffs auf öffentliche Netzwerke zu „Deaktiviert“.

Wenn Sie feststellen, dass die Konnektivitätsänderung sehr viel Zeit in Anspruch nimmt, warten Sie ein paar Stunden. Konnektivitätsänderungsvorgänge umfassen Vorgänge wie das Aktualisieren von DNS-Einträgen, die möglicherweise länger als erwartet dauern.

Wenn der Zugriff auf öffentliche Netzwerke geändert wird, funktionieren vorhandene freigegebene private Links und private Endpunkte möglicherweise nicht ordnungsgemäß. Wenn vorhandene freigegebene private Verbindungen und private Endpunkte während eines Konnektivitätsänderungsvorgangs nicht mehr funktionieren, warten Sie einige Stunden, bis der Vorgang abgeschlossen ist. Falls sie dann immer noch nicht funktionieren, löschen Sie sie, und erstellen Sie sie neu.

In der Regel erreicht eine freigegebene private Verknüpfungsressource einen Terminalstatus (Succeeded oder Failed) in wenigen Minuten, nachdem die Anforderung akzeptiert wurde.

In seltenen Fällen kann Foundry IQ den Zustand der freigegebenen privaten Verknüpfungsressource nicht korrekt in einen Terminalzustand (Succeeded oder Failed) kennzeichnen. Dies ist in der Regel auf einen unerwarteten Fehler zurückzuführen. Freigegebene Private Link-Ressourcen werden automatisch in einen Zustand Failed versetzt, wenn sie seit mehr als ein paar Stunden in einem Zustand verblieben sind, der kein Endzustand ist.

Wenn die freigegebene private Verknüpfungsressource nicht zu einem Terminalstatus wechselt, warten Sie einige Stunden, um sicherzustellen, dass sie Failed erreicht, bevor Sie sie löschen und neu erstellen. Anstatt zu warten, können Sie alternativ versuchen, eine weitere freigegebene Private Link-Ressource mit einem anderen Namen zu erstellen (alle anderen Parameter bleiben dabei gleich).

Eine vorhandene freigegebene Private Link-Ressource kann mithilfe der API zum Erstellen oder Aktualisieren aktualisiert werden. Die Suche ermöglicht nur eingeschränkte Aktualisierungen der freigegebenen privaten Verbindung. Nur die Anforderungsnachricht kann über diese API geändert werden.

  • Es ist nicht möglich, die „Kerneigenschaften“ einer vorhandenen freigegebenen Private Link-Ressource (z. B. privateLinkResourceId oder groupId) zu aktualisieren. Dies wird niemals unterstützt. Wenn eine andere Eigenschaft außer der Anforderungsnachricht geändert werden muss, empfehlen wir Kunden, die freigegebene Private Link-Ressource zu löschen und dann neu zu erstellen.

  • Das Aktualisieren der Anforderungsnachricht einer freigegebenen privaten Linkressource ist nur möglich, wenn der Bereitstellungsstatus Succeeded erreicht wird.

Kunden können eine vorhandene freigegebene Private Link-Ressource über die Lösch-API löschen. Ähnlich wie bei der Erstellung (oder Aktualisierung) ist auch dies ein asynchroner Vorgang mit vier Schritten:

  1. Sie fordern einen Foundry IQ-Dienst auf, die freigegebene private Linkressource zu löschen.

  2. Der Foundry IQ-Dienst überprüft, ob die Ressource vorhanden ist und sich in einem für die Löschung gültigen Zustand befindet. Wenn dies der Fall ist, initiiert er einen Azure Resource Manager-Löschvorgang, um die Ressource zu entfernen.

  3. Die Suche fragt den Abschluss des Vorgangs ab (was in der Regel einige Minuten dauert). An diesem Punkt hätte die freigegebene private Linkressource einen Bereitstellungsstatus von Deleting.

  4. Nachdem der Vorgang erfolgreich abgeschlossen wurde, werden der unterstützende private Endpunkt und alle zugehörigen DNS-Zuordnungen entfernt. Die Ressource wird nicht als Teil des Listenvorgangs angezeigt und der Versuch eines Get-Vorgangs für diese Ressource führt zu einer 404 Nicht gefunden.

Schritte zum Löschen freigegebener privater Verknüpfungsressourcen

Im Folgenden finden Sie häufige Fehler, die während der Löschphase auftreten.

Fehlertyp BESCHREIBUNG Lösung
Ressource befindet sich im Nichtterminal-Zustand Eine freigegebene Private Link-Ressource, die sich nicht in einem Endzustand (Succeeded oder Failed) befindet, kann nicht gelöscht werden. Es ist (selten) möglich, dass eine freigegebene private Linkressource bis zu 8 Stunden in einem nicht-terminalen Zustand steckenbleibt. Warten Sie, bis die Ressource einen Terminalstatus erreicht, und wiederholen Sie die Löschanforderung.
Fehler beim Löschvorgang mit Fehlerursache „Conflict“ (Konflikt) Der Azure Resource Manager-Vorgang zum Löschen einer freigegebenen Private Link-Ressource greift auf den Ressourcenanbieter der in privateLinkResourceId angegebenen Zielressource („Zielressourcenanbieter“) zu, bevor er den privaten Endpunkt und die DNS-Zuordnungen entfernen kann. Kunden können Azure-Ressourcensperren verwenden, um Änderungen an ihren Ressourcen zu verhindern. Wenn Azure Resource Manager den Zielressourcenanbieter erreicht, muss der Zielressourcenanbieter den Zustand der Zielressource ändern (um Details zum privaten Endpunkt aus seinen Metadaten zu entfernen). Wenn für die Zielressource eine Sperre konfiguriert ist (oder für ihre Ressourcengruppe/ihr Abonnement), schlägt der Azure Resource Manager-Vorgang mit einem „Conflict“ (und entsprechenden Details) fehl. Die freigegebene Private Link-Ressource wird nicht gelöscht. Kunden sollten die Sperre für die Zielressource entfernen, bevor sie den Löschvorgang wiederholen. Hinweis: Dieses Problem kann auch auftreten, wenn Kunden versuchen, einen Foundry IQ-Dienst mit freigegebenen privaten Linkressourcen zu löschen, die auf "gesperrte" Zielressourcen verweisen
Fehler bei Löschvorgang Der asynchrone Azure Resource Manager-Löschvorgang kann in seltenen Fällen fehlschlagen. Wenn dieser Vorgang fehlschlägt, gibt das Abfragen des Status des asynchronen Vorgangs eine Fehlermeldung und entsprechende Details zurück. Wiederholen Sie den Vorgang zu einem späteren Zeitpunkt, oder wenden Sie sich an den Azure-Support, wenn das Problem weiterhin besteht.
Ressource verbleibt im Zustand „Deleting“ (Wird gelöscht) In seltenen Fällen kann eine freigegebene Private Link-Ressource bis zu 8 Stunden lang im Zustand „Deleting“ (Wird gelöscht) verbleiben, wahrscheinlich aufgrund eines schwerwiegenden Fehlers im Suchressourcenanbieter. Warten Sie 8 Stunden, nach denen die Ressource in den Zustand Failed übergeht, und wiederholen Sie die Anforderung dann.

Nächste Schritte

Erfahren Sie mehr über freigegebene Private Link-Ressourcen und deren Verwendung für sicheren Zugriff auf geschützte Inhalte.