Erstellen ausgehender Verbindungen über eine freigegebene private Verbindung

  • Artikel

In diesem Artikel wird erläutert, wie Sie private ausgehende Aufrufe der Azure KI Cognitive Search an eine Azure PaaS-Ressource konfigurieren, die in einem virtuellen Netzwerk ausgeführt wird.

Durch das Einrichten einer privaten Verbindung kann ein Suchdienst eine Verbindung mit einer IP-Adresse eines virtuellen Netzwerks herstellen, anstatt mit einem Port, der für das Internet geöffnet ist. Das für die Verbindung erstellte Objekt wird als geteilte private Verbindung bezeichnet. Bei der Verbindung verwendet der Suchdienst die geteilte private Verbindung intern, um eine Azure PaaS-Ressource innerhalb der Netzwerkgrenze zu erreichen.

Die geteilte private Verbindung ist eine Premium-Funktion mit nutzungsbasierter Abrechnung. Wenn Sie eine geteilte private Verbindung einrichten, werden Gebühren für den privaten Endpunkt zu Ihrer Azure-Rechnung hinzugefügt. Wenn Sie die geteilte private Verbindung verwenden, werden auch Datenübertragungsraten für eingehenden und ausgehenden Zugriff in Rechnung gestellt. Ausführliche Informationen finden Sie unter Azure Private Link – Preise.

Hinweis

Wenn Sie eine private Indexerverbindung zu einer SQL Managed Instance einrichten, lesen Sie stattdessen diesen Artikel.

Die Azure KI Cognitive Search führt ausgehende Aufrufe an andere Azure PaaS-Ressourcen in den folgenden Szenarien aus:

  • Indexer oder Suchmaschine stellt eine Verbindung mit Azure OpenAI für Text-zu-Vektor-Einbettungen bereit
  • Indexerverbindungen mit unterstützten Datenquellen
  • Indexerverbindungen (Skillset)-Verbindungen mit Azure Storage zum Zwischenspeichern von Anreicherungen, Ausfüllen von Debug-Sitzungen oder Schreiben in einen Wissensspeicher
  • Anforderungen des Verschlüsselungsschlüssels an Azure Key Vault
  • Benutzerdefinierte Skill-Anforderungen an Azure Functions oder ähnliche Ressourcen

Gemeinsame private Links funktionieren nur für Azure-zu-Azure-Verbindungen. Wenn Sie eine Verbindung mit OpenAI oder einem anderen externen Modell herstellen, muss die Verbindung über das öffentliche Internet erfolgen.

Freigegebene private Links gelten für Vorgänge und Daten, auf die über einen privaten Endpunkt zugegriffen wird, für Azure-Ressourcen oder -Clients, die in einem virtuellen Azure-Netzwerk ausgeführt werden.

Für eine geteilte private Verbindung gilt Folgendes:

  • Erstellt mit Azure KI Cognitive Search-Tools, APIs oder SDKs
  • Genehmigt vom Azure PaaS-Ressourcenbesitzer
  • Intern von der Azure KI-Suche für eine private Verbindung mit einer bestimmten Azure-Ressource verwendet

Nur Ihr Suchdienst kann die von ihm erstellten privaten Verbindungen verwenden, und für jede Ressourcen- und Unterressourcenkombination kann es im Dienst nur eine erstellte geteilte private Verbindung geben.

Nachdem Sie die private Verbindung eingerichtet haben, wird sie automatisch verwendet, wenn der Suchdienst eine Verbindung mit dieser PaaS-Ressource herstellt. Sie müssen die Verbindungszeichenfolge nicht ändern oder den Client ändern, den Sie zum Ausgeben der Anforderungen verwenden, obwohl das für die Verbindung verwendete Gerät eine Verbindung über eine autorisierte IP in der Firewall der Azure PaaS-Ressource herstellen muss.

Es gibt zwei Szenarien für die gemeinsame Verwendung von Azure Private Link und Azure KI Cognitive Search.

Szenario 1 wird in diesem Artikel behandelt.

Obwohl beide Szenarien eine Abhängigkeit von Azure Private Link haben, sind sie unabhängig. Sie können eine geteilte private Verbindung erstellen, ohne Ihren eigenen Suchdienst für einen privaten Endpunkt konfigurieren zu müssen.

Begrenzungen

Beachten Sie beim Auswerten geteilter privater Verbindung für Ihr Szenario diese Einschränkungen.

  • Einige der Ressourcentypen, die in einer geteilten privaten Verbindung verwendet werden, befinden sich in der Vorschau. Falls Sie eine Verbindung mit einer Vorschau-Ressource (Azure Database for MySQL, Azure Functions oder Azure SQL Managed Instance) herstellen, verwenden Sie eine Vorschauversion der Verwaltungs-REST-API, um die geteilte private Verbindung zu erstellen. Zu diesen Versionen gehören 2020-08-01-preview, 2021-04-01-previewund 2024-03-01-preview.

  • Für die Indexerausführung muss die private Ausführungsumgebung verwendet werden, die spezifisch für Ihren Suchdienst ist. Private Endpunktverbindungen werden von der Multimandantenumgebung nicht unterstützt. Die Konfigurationseinstellung für diese Anforderung wird in diesem Artikel behandelt.

Voraussetzungen

  • Ein Azure KI Cognitive Search auf der Basic-Dienstebene oder höher. Wenn Sie KI-Anreicherung und Skillsets verwenden, ist mindestens der Tarif „Standard 2 (S2)“ erforderlich. In den Einschränkungen für Dienste finden Sie weitere Informationen.

  • Eine Azure PaaS-Ressource aus der folgenden Liste der unterstützten Ressourcentypen, konfiguriert für die Ausführung in einem virtuellen Netzwerk.

  • Berechtigungen für die Azure KI-Suche und die Datenquelle:

    • In der Azure PaaS-Ressource benötigen Sie die Berechtigung zum Genehmigen privater Endpunktverbindungen. Wenn Sie beispielsweise ein Azure Storage-Konto als Datenquelle verwenden (z. B. Blob-Container, Azure Files-Freigabe, Azure-Tabelle), benötigen Sie Microsoft.Storage/storageAccounts/privateEndpointConnectionsApproval/action.

    • Im Suchdienst benötigen Sie Lese- und Schreibberechtigungen für freigegebene private Linkressourcen und Lesevorgangsstatus:

      • Microsoft.Search/searchServices/sharedPrivateLinkResources/write
      • Microsoft.Search/searchServices/sharedPrivateLinkResources/read
      • Microsoft.Search/searchServices/sharedPrivateLinkResources/operationStatuses/read

Unterstützte Ressourcentypen

Sie können eine geteilte private Verbindung für die folgenden Ressourcen erstellen.

Ressourcentyp Unterressource (oder Gruppen-ID)
Microsoft.Storage/storageAccounts 1 blob, table, dfs, file
Microsoft.DocumentDB/databaseAccounts 2 Sql
Microsoft.Sql/servers sqlServer
Microsoft.KeyVault/vaults vault
Microsoft.DBforMySQL/servers (Vorschau) mysqlServer
Microsoft.Web/sites (Vorschau) 3 sites
Microsoft.Sql/managedInstances (Vorschau) 4 managedInstance
Microsoft.CognitiveServices/accounts (Preview) 5 openai_account

1 Wenn sich Azure Storage und Azure KI Cognitive Search in derselben Region befinden, wird die Verbindung zum Speicher über das Microsoft-Backbone-Netzwerk hergestellt, was bedeutet, dass eine geteilte private Verbindung für diese Konfiguration redundant ist. Wenn Sie jedoch bereits einen privaten Endpunkt für Azure Storage eingerichtet haben, sollten Sie auch eine geteilte private Verbindung einrichten, oder die Verbindung wird auf der Speicherseite abgelehnt. Wenn Sie für verschiedene Suchszenarien mehrere Speicherformate verwenden, müssen Sie außerdem für jede Unterressource eine separate geteilte private Verbindung erstellen.

2 Der Ressourcentyp Microsoft.DocumentDB/databaseAccounts wird für Indexerverbindungen zu Azure Cosmos DB for NoSQL verwendet. Bei dem Anbieternamen und der Gruppen-ID muss die Groß-/Kleinschreibung beachtet werden.

3 Der Ressourcentyp Microsoft.Web/sites wird für App-Dienst- und Azure-Funktionen verwendet. Im Kontext von Azure KI Cognitive Search ist eine Azure-Funktion das wahrscheinlichere Szenario. Eine Azure-Funktion wird häufig zum Hosten der Logik eines benutzerdefinierten Skills verwendet. Azure Function verfügt über Verbrauchs-, Premium- und dedizierte App Service-Hostingpläne. Die App Service-Umgebung (ASE) und Azure Kubernetes Service (AKS) werden derzeit nicht unterstützt.

4 Weitere Anweisungen finden Sie unter Erstellen einer geteilten privaten Verbindung für eine SQL Managed Instance.

5 Der Ressourcentyp Microsoft.CognitiveServices/accounts wird bei der Implementierung integrierter Vektorisierung für Indexerverbindungen mit Azure OpenAI verwendet.

1. Erstellen einer freigegebenen privaten Verbindung

Verwenden Sie das Azure-Portal, die Verwaltungs-REST-API, die Azure CLI oder Azure PowerShell, um eine geteilte private Verbindung zu erstellen.

Im Folgenden einige Tipps:

  • Geben Sie der geteilten privaten Verbindung einen aussagekräftigen Namen. Eine geteilte private Verbindung wird in der Azure PaaS-Ressource zusammen mit anderen privaten Endpunkten angezeigt. Ein Name wie „geteilte-private-verbindung-für-cognitive-search“ kann Sie daran erinnern, wie er verwendet wird.

Wenn Sie diese Schritte ausführen, sollten Sie über eine geteilte private Verbindung verfügen, die mit einem Status „Ausstehend“ bereitgestellt wird. Die Erstellung der Verbindung dauert einige Minuten. Nachdem sie erstellt wurde, muss die Person, der die Ressource gehört, die Anforderung genehmigen, bevor sie betriebsbereit ist.

  1. Melden Sie sich beim Azure-Portal an, und finden Sie Ihren Suchdienst.

  2. Wählen Sie im linken Navigationsbereich unter Einstellungen die Option Netzwerk aus.

  3. Wählen Sie auf der Seite Gemeinsamer privater Zugriff die Option + Gemeinsamen privaten Zugriff hinzufügen aus.

  4. Wählen Sie entweder Verbindung mit einer Azure-Ressource in meinem Verzeichnis herstellen oder Verbindung mit einer Azure-Ressource nach Ressourcen-ID herstellen aus.

  5. Bei Verwendung der ersten Option (empfohlen) werden Sie vom Portal bei der Wahl der geeigneten Azure-Ressource unterstützt und es füllt andere Eigenschaften wie die Gruppen-ID der Ressource und den Ressourcentyp aus.

    Screenshot der Seite „Freigegebenen privaten Zugriff hinzufügen“ mit einer unterstützenden Benutzeroberfläche zum Erstellen einer freigegebenen Private Link-Ressource.

  6. Geben Sie bei Verwendung der zweiten Option die Azure-Ressourcen-ID manuell ein, und wählen Sie aus der Liste am Anfang dieses Artikels die entsprechende Gruppen-ID aus.

    Screenshot der Seite „Freigegebenen privaten Zugriff hinzufügen“ mit einer manuellen Benutzeroberfläche zum Erstellen einer freigegebenen Private Link-Ressource.

  7. Stellen Sie sicher, dass der Bereitstellungsstatus „Aktualisierung läuft“ lautet.

    Screenshot der Seite „Freigegebenen privaten Zugriff hinzufügen“, der zeigt, dass die Ressourcenerstellung aktuell ausgeführt wird.

  8. Nachdem die Ressource erfolgreich erstellt wurde, wird der Bereitstellungsstatus der Ressource zu „erfolgreich“ geändert.

    Screenshot der Seite „Freigegebenen privaten Zugriff hinzufügen“, der zeigt, dass die Ressourcenerstellung abgeschlossen wurde.

Bei Erfolg wird die Antwort 202 Accepted zurückgegeben. Der Prozess der Erstellung eines ausgehenden privaten Endpunkts ist ein zeitintensiver (asynchroner) Vorgang. Er umfasst die Bereitstellung der folgenden Ressourcen:

  • Ein privater Endpunkt, dem eine private IP-Adresse in einem "Pending"-Zustand zugeordnet wurde. Die private IP-Adresse wird aus dem Adressraum abgerufen, der dem virtuellen Netzwerk der Ausführungsumgebung für den suchdienstspezifischen privaten Indexer zugeordnet ist. Nach der Genehmigung des privaten Endpunkts stammt jede Kommunikation von Azure KI Cognitive Search zur Azure-Ressource von der privaten IP-Adresse und einem sicheren privaten Verbindungskanal.

  • Eine private DNS-Zone für den Ressourcentyp, basierend auf der Gruppen-ID. Durch Bereitstellen dieser Ressource stellen Sie sicher, dass bei jedem DNS-Lookup zur privaten Ressource die dem privaten Endpunkt zugeordnete IP-Adresse verwendet wird.

2 – Genehmigen der Verbindung mit einem privaten Endpunkt

Die Genehmigung der privaten Endpunktverbindung wird auf Azure PaaS-Seite erteilt. Die explizite Genehmigung durch den Ressourcenbesitzer ist erforderlich. Die folgenden Schritte behandeln die Genehmigung über das Azure-Portal, hier sind jedoch einige Links zum programmgesteuerten Genehmigen der Verbindung auf der Azure PaaS-Seite:

Führen Sie im Azure-Portal folgende Schritte aus:

  1. Öffnen Sie im Azure-Portal die Seite Netzwerk der Azure PaaS-Ressource.text

  2. Suchen Sie nach dem Abschnitt, in dem die Verbindungen mit privaten Endpunkten aufgeführt sind. Im Folgenden finden Sie ein Beispiel für ein Speicherkonto.

    Der Screenshot des Azure-Portals zeigt den Bereich „Private Endpunktverbindungen“.

  3. Wählen Sie die Verbindung und dann wählen Sie dannGenehmigen aus. Es kann einige Minuten dauern, bis der Status im Portal aktualisiert wird.

    Screenshot des Azure-Portals, der im Bereich „Private Endpunktverbindungen“ den Status „Genehmigt“ zeigt

Nachdem der private Endpunkt genehmigt wurde, erstellt Azure KI Cognitive Search die erforderlichen DNS-Zonenzuordnungen in der dafür erstellten DNS-Zone.

Obwohl der private Endpunktlink auf der Seite Netzwerk aktiv ist, wird er nicht aufgelöst.

Screenshot des Links zum privaten Endpunkt auf der Seite „Azure PaaS Netzwerk“.

Wenn Sie den Link auswählen, wird ein Fehler erzeugt. Es wird eine Statusmeldung von "The access token is from the wrong issuer" und must match the tenant associated with this subscription angezeigt, da die private Back-End-Endpunktressource auf einem von Microsoft verwalteten Mandanten von Microsoft bereitgestellt wird, während sich die verknüpfte Ressource (Azure KI-Suche) auf Ihrem Mandanten befindet. Es ist beabsichtigt, dass Sie nicht auf die Ressource des privaten Endpunkts zugreifen können, indem Sie den Link zur Verbindung mit dem privaten Endpunkt auswählen.

Folgen Sie den Anweisungen im nächsten Abschnitt, um den Status des freigegebenen privaten Links zu überprüfen.

3 – Überprüfen des Status der geteilten privaten Verbindung

Auf der Seite der Azure KI-Suche können Sie die Genehmigung bestätigen, indem Sie die Seite „Freigegebener privater Zugriff“ der Seite Netzwerk des Suchdienstes überarbeiten. Der Verbindungsstatus sollte „Genehmigt“ lauten.

Screenshot des Azure-Portals mit einer genehmigten freigegebenen Private Link-Ressource.

Alternativ können Sie den „Verbindungsstatus“ auch mithilfe der GET Shared Private Link-API abrufen.

az rest --method get --uri https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/contoso/providers/Microsoft.Search/searchServices/contoso-search/sharedPrivateLinkResources/blob-pe?api-version=2023-11-01

Dadurch wird JSON-Code zurückgegeben, bei dem der Verbindungsstatus im Abschnitt „Eigenschaften“ als „Status“ angezeigt wird. Im Folgenden finden Sie ein Beispiel für ein Speicherkonto.

{
      "name": "blob-pe",
      "properties": {
        "privateLinkResourceId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/contoso/providers/Microsoft.Storage/storageAccounts/contoso-storage",
        "groupId": "blob",
        "requestMessage": "please approve",
        "status": "Approved",
        "resourceRegion": null,
        "provisioningState": "Succeeded"
      }
}

Wenn der „Bereitstellungsstatus“ (properties.provisioningState) der Ressource „Erfolgreich“ und der Verbindungsstatus (properties.status) „Genehmigt“ lautet, bedeutet dies, dass die geteilte private Verbindungsressource funktionsfähig ist und der Indexer so konfiguriert werden kann, dass er über den privaten Endpunkt kommuniziert.

4 – Konfigurieren der Indexerausführung in der privaten Umgebung

Die Indexerausführung erfolgt entweder in einer privaten suchdienstspezifischen Umgebung oder in einer Umgebung mit mehreren Mandanten, die intern verwendet wird, um die aufwendige Skillsetverarbeitung für mehrere Kunden und Kundinnen auszulagern.

Die Ausführungsumgebung ist transparent. Sobald Sie jedoch mit der Erstellung von Firewallregeln oder der Herstellung privater Verbindungen beginnen, müssen Sie die Indexerausführung berücksichtigen. Konfigurieren Sie für eine private Verbindung die Indexerausführung so, dass er immer in der privaten Umgebung ausgeführt wird.

Im folgenden Schritt wird gezeigt, wie Sie den Indexer mithilfe der REST-API für die Ausführung in der privaten Umgebung konfigurieren. Sie können die Ausführungsumgebung auch mit dem JSON-Editor im Portal festlegen.

Hinweis

Sie können diesen Schritt vor der Genehmigung der privaten Endpunktverbindung ausführen. Bis zur Genehmigung der privaten Endpunktverbindung tritt jedoch für jeden vorhandenen Indexer, der mit einer sicheren Ressource (z. B. dem Speicherkonto) kommunizieren möchte, ein vorübergehender Fehler auf, und es können keine neuen Indexer erstellt werden.

  1. Erstellen Sie die Datenquellendefinition, den Index und das Skillset (wenn Sie eine verwenden) wie gewohnt. In keiner dieser Definitionen gibt es Eigenschaften, die sich bei Verwendung eines freigegebenen privaten Endpunkts ändern.

  2. Erstellen Sie einen Indexer, der auf die Datenquelle, den Index und das Skillset verweist, die Sie im vorhergehenden Schritt erstellt haben. Erzwingen Sie außerdem durch Festlegen der Indexerkonfigurationseigenschaft executionEnvironment auf private, dass der Indexer in der privaten Ausführungsumgebung ausgeführt wird.

    {
    "name": "indexer",
    "dataSourceName": "blob-datasource",
    "targetIndexName": "index",
    "parameters": {
        "configuration": {
            "executionEnvironment": "private"
        }
    },
    "fieldMappings": []
}

Nachdem der Indexer erfolgreich erstellt wurde, sollte er sich über die private Endpunktverbindung mit der Azure-Ressource verbinden. Sie können den Status des Indexers mithilfe der Indexer-Status-API überwachen.

Hinweis

Wenn Sie bereits Indexer haben, können Sie sie über die PUT-API aktualisieren, indem Sie die Eigenschaft executionEnvironment auf private festlegen oder den JSON-Editor im Portal verwenden.

5 – Testen der geteilten privaten Verbindung

  1. Wenn Sie dies noch nicht getan haben, stellen Sie sicher, dass Ihre Azure PaaS-Ressource Verbindungen aus dem öffentlichen Internet ablehnt. Wenn Verbindungen akzeptiert werden, überprüfen Sie die DNS-Einstellungen auf der Seite Netzwerk Ihrer Azure PaaS-Ressource.

  2. Wählen Sie ein Tool aus, das ein ausgehendes Anforderungsszenario aufrufen kann, z. B. eine Indexerverbindung mit einem privaten Endpunkt. Eine einfache Wahl ist die Verwendung des Assistenten für das Importieren von Daten. Sie können aber auch einen REST-Client und REST-APIs ausprobieren, um eine größere Genauigkeit zu erzielen. Vorausgesetzt, Ihr Suchdienst ist nicht ebenfalls für eine private Verbindung konfiguriert, kann die REST-Clientverbindung zur Suche über das öffentliche Internet erfolgen.

  3. Legen Sie die Verbindungszeichenfolge auf die private Azure PaaS-Ressource fest. Das Format der Verbindungszeichenfolge ändert sich nicht für geteilte private Verbindungen. Der Suchdienst ruft die geteilte private Verbindung intern auf.

    Bei Indexerworkloads befindet sich die Verbindungszeichenfolge in der Datenquellendefinition. Ein Beispiel für eine Datenquelle könnte wie folgt aussehen:

     {
   "name": "my-blob-ds",
   "type": "azureblob",
   "subtype": null,
   "credentials": {
     "connectionString": "DefaultEndpointsProtocol=https;AccountName=<YOUR-STORAGE-ACCOUNT>;AccountKey=..."
   }

  4. Denken Sie bei Indexerworkloads daran, die Ausführungsumgebung in der Indexerdefinition festzulegen. Ein Beispiel für eine Indexerdefinition könnte wie folgt aussehen:

    "name": "indexer",
"dataSourceName": "my-blob-ds",
"targetIndexName": "my-index",
"parameters": {
   "configuration": {
       "executionEnvironment": "private"
       }
   },
"fieldMappings": []
}

  5. Führen Sie den Indexer aus. Wenn die Indexerausführung erfolgreich ausgeführt wird und der Suchindex aufgefüllt wird, funktioniert die geteilte private Verbindung.

Problembehandlung

  • Falls bei der Indexererstellung ein Fehler mit dem Hinweis auftritt, dass die Anmeldeinformationen für die Datenquelle ungültig sind, überprüfen Sie vor dem Debuggen der Verbindung zunächst den Genehmigungsstatus der geteilten privaten Verbindung. Sollte der Status Approved lauten, überprüfen Sie die Eigenschaft properties.provisioningState. Hat sie den Wert Incomplete, liegt möglicherweise ein Problem mit zugrunde liegenden Abhängigkeiten vor. Geben Sie in diesem Fall die Anforderung PUT erneut aus, um die freigegebene private Verbindung erneut zu erstellen. Unter Umständen muss auch der Genehmigungsschritt wiederholt werden.

  • Wenn bei Indexern konsistent oder zeitweilig Fehler auftreten, überprüfen Sie die Eigenschaft executionEnvironment des Indexers. Der Wert sollte auf private festgelegt sein. Wenn Sie diese Eigenschaft nicht festgelegt haben und Indexerausführungen in der Vergangenheit erfolgreich waren, liegt das daran, dass vom Suchdienst eigenständig eine private Umgebung verwendet wurde. Die Verarbeitung wird von einem Suchdienst aus der Standardumgebung ausgelagert, wenn das System ausgelastet ist.

  • Sollte beim Erstellen einer freigegebenen privaten Verbindung eine Fehlermeldung angezeigt werden, vergewissern Sie sich anhand der Dienstgrenzwerte, dass Sie das Kontingent für Ihren Tarif nicht überschritten haben.

Nächste Schritte

Erfahren Sie mehr über private Endpunkte und weitere sichere Verbindungsmethoden: