Freigeben über

Behandeln von Problemen mit freigegebenen privaten Verbindungen in Azure KI Search

  • Artikel

Eine freigegebene private Verbindung ermöglicht es Azure KI Search, sichere ausgehende Verbindungen über einen privaten Endpunkt herzustellen, wenn auf Kundenressourcen in einem virtuellen Netzwerk zugegriffen wird. Dieser Artikel hilft Ihnen beim Beheben von Fehlern, die auftreten können.

Das Erstellen einer freigegebenen privaten Verbindung ist ein Vorgang der Steuerungsebene des Suchdiensts. Eine freigegebene private Verbindung kann entweder über das Azure-Portal oder eine Verwaltungs-REST-API erstellt werden. Während der Bereitstellung lautet der Status der Anforderung „Wird aktualisiert…“. Nachdem der Vorgang erfolgreich abgeschlossen wurde, ist der Status „Erfolgreich“. Es wird ein privater Endpunkt für die Ressource zusammen mit allen DNS-Zonen und -Zuordnungen erstellt. Dieser Endpunkt wird ausschließlich von Ihrer Suchdienstinstanz verwendet und über Azure KI Search verwaltet.

Schritte beim Erstellen freigegebener Private Link-Ressourcen

Einige häufige Fehler, die während der Erstellungsphase auftreten können, werden unten aufgeführt.

Anforderungsüberprüfungsfehler

  • Nicht unterstützte SKU: Freigegebene private Verbindungen werden im Basic-Tarif und höher unterstützt. Für Indexer mit Skillsets ist mindestens Tarif „Standard 2“ (S2) erforderlich.

  • 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 Werte aus der folgenden Tabelle 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 for NoSQL Sql 2020-08-01
    Azure SQL-Datenbank sqlServer 2020-08-01
    Azure Database for MySQL (Vorschau) mysqlServer 2020-08-01-Preview
    Azure Key Vault 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: Azure KI Search überprüft, ob in privateLinkResourceId der korrekte Ressourcentyp angegeben ist. Folgende Ressourcentypen sind gültig:

    Azure-Ressource Ressourcentyp Erste verfügbare API-Version
    Azure Storage (in englischer Sprache) Microsoft.Storage/storageAccounts 2020-08-01
    Azure Cosmos DB Microsoft.DocumentDb/databaseAccounts 2020-08-01
    Azure SQL-Datenbank Microsoft.Sql/servers 2020-08-01
    Azure-Schlüsseltresor 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, kann aber 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.

  • Erzwingung der Kontingentgrenze: Für Suchdienste gelten Kontingente für die unterschiedliche Anzahl von freigegebenen Private Link-Ressourcen, die erstellt werden können, und für die Anzahl der verschiedenen verwendeten Zielressourcentypen (basierend auf groupId). Diese sind im Abschnitt Ressourcenlimits für freigegebene Private Link-Ressourcen auf der Seite mit den Grenzwerten für Azure KI Search Services dokumentiert.

Bereitstellungsfehler

Ein Suchdienst initiiert die Anforderung zum Erstellen eines freigegebenen Private Link, aber Azure Resource Manager übernimmt die eigentliche Arbeit. Sie können den Status der Bereitstellung im Azure-Portal oder per Abfrage überprüfen und etwaige Fehler beheben.

Freigegebene Private Link-Ressourcen, bei denen die Azure Resource Manager-Bereitstellung fehlgeschlagen ist, werden in List- und Get-API-Aufrufen angezeigt, weisen jedoch den „Bereitstellungsstatus“ Failed auf. Sobald der Grund für den Azure Resource Manager-Bereitstellungsfehler festgestellt wurde, löschen Sie die Ressource Failed, und erstellen Sie sie neu, nachdem Sie die entsprechende Auflösung aus der folgenden Tabelle angewendet haben.

Grund für den Bereitstellungsfehler Beschreibung Lösung
LinkedAuthorizationFailed Die Fehlermeldung gibt an, dass der Client berechtigt ist, die freigegebene private Verbindung im Suchdienst zu erstellen, aber nicht über die Berechtigung zum Ausführen der Aktion „privateEndpointConnectionApproval/action“ für den verknüpften Bereich verfügt. Überprüfen Sie noch einmal die ID der privaten Verbindung in der Anforderung, um Fehler oder Auslassungen im URI auszuschließen. Wenn sich Azure KI Search und die Azure PaaS-Ressource in verschiedenen Abonnements befinden und Sie REST oder eine Befehlszeilenschnittstelle verwenden, vergewissern Sie sich, dass es sich bei dem aktiven Azure-Konto um das Konto für die Azure PaaS-Ressource handelt. 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. Azure Cosmos DB bietet zwar verschiedene API-Typen, aber Azure KI Search unterstützt nur „Sql“ als groupId für freigegebene Private Link-Ressourcen. 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. Azure KI Search 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, tritt bei der Bereitstellung ein Fehler auf. 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. Dies ist einer der letzten Schritte im asynchronen Azure Resource Manager-Bereitstellungsvorgang, aber Azure KI Search muss die private IP-Adresse des privaten Endpunkts als Teil der Netzwerkkonfiguration verknüpfen. Sobald diese Verknüpfung abgeschlossen ist, wechselt der provisioningState der Ressource für freigegebene Private Link-Ressourcen in einen erfolgreichen Endzustand Succeeded. Kunden sollten die Konfiguration des unterstützenden privaten Endpunkts nur genehmigen oder verweigern (oder ganz allgemein ändern), nachdem der Status in Succeeded übergegangen ist. Wird der private Endpunkts vorher auf irgendeine Weise geändert, kann dies zu einem unvollständigen Bereitstellungsvorgang führen und dazu, dass die freigegebene Private Link-Ressource (entweder sofort oder in der Regel innerhalb weniger Stunden) in einem Failed-Status endet.

Netzwerkkonnektivität des Suchdiensts verbleibt im Status „Wird aktualisiert“

Wenn die Option Zugriff über öffentliche Netzwerke für den Suchdienst auf Deaktiviert festgelegt ist, werden freigegebene private Verbindungen und private Endpunkte verwendet. Normalerweise sollten die Änderungen an der Netzwerkkonnektivität innerhalb weniger Minuten nach Bestätigung der Anforderung wirksam werden. Unter bestimmten Umständen kann es jedoch mehrere Stunden dauern, bis Azure KI Search die Konnektivitätsänderung durchgeführt hat.

Screenshot: Änderung der Option „Zugriff über öffentliche Netzwerke“ in „Deaktiviert“

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

Wenn die Option Zugriff über öffentliche Netzwerke geändert wird, funktionieren bestehende freigegebene private Verbindungen und private Endpunkte möglicherweise nicht mehr 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 sollte eine freigegebene private Verbindung innerhalb weniger Minuten in einen Endzustand (Succeeded oder Failed) übergehen, nachdem die Anforderung akzeptiert wurde.

In seltenen Fällen kann es vorkommen, dass Azure KI Search den Status der freigegebenen Private Link-Ressource nicht richtig auf einen Endzustand (Succeeded oder Failed) festlegt. 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 Sie feststellen, dass die freigegebene Private Link-Ressource nicht in einen Endzustand versetzt wurde, warten Sie ein paar Stunden, um sicherzustellen, dass sie als Failed gekennzeichnet wird, 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.

  • Der Versuch, die Anforderungsnachricht einer freigegebenen Private Link-Ressource zu aktualisieren, ist nur möglich, wenn sie den Bereitstellungsstatus Succeeded erreicht hat.

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 Suchdienst auf, die freigegebene private Verbindung zu löschen.

  2. Der Suchdienst überprüft, ob die Ressource vorhanden ist und sich in einem Zustand befindet, in dem ein Löschvorgang gültig ist. 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 weist die freigegebene Private Link-Ressource den Bereitstellungsstatus „Deleting“ (Wird gelöscht) auf.

  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 List-Vorgangs angezeigt, und der Versuch, einen Get-Vorgang für diese Ressource auszuführen, führt zu 404 Not Found (Nicht gefunden).

Schritte beim Löschen freigegebener Private Link-Ressourcen

Einige häufige Fehler, die während der Löschphase auftreten können, werden unten aufgeführt.

Fehlertyp Beschreibung Lösung
Ressource befindet sich in keinem Endzustand Eine freigegebene Private Link-Ressource, die sich nicht in einem Endzustand (Succeeded oder Failed) befindet, kann nicht gelöscht werden. Es ist möglich (aber selten), dass eine freigegebene Private Link-Ressource bis zu acht Stunden lang in einem Zustand verbleibt, der kein Endzustand ist. Warten Sie, bis die Ressource einen Endzustand erreicht hat, 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 Suchdienst mit freigegebenen Private Link-Ressourcen 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, erhalten Kunden beim Abfragen des Zustands des asynchronen Vorgangs eine Fehlermeldung und entsprechende Details. 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.