Erstellen eines freigegebenen privaten Links für eine von SQL verwaltete Instanz aus Azure KI Search

Artikel
12/10/2024

In diesem Artikel wird erläutert, wie Sie einen Indexer in Azure KI Search für eine private Verbindung mit einer SQL-verwalteten Instanz konfigurieren, die in einem virtuellen Netzwerk ausgeführt wird. Die private Verbindung erfolgt über eine freigegebene private Verbindung und Azure Private Link.

Bei einer privaten Verbindung zu einer verwalteten Instanz muss der vollqualifizierte Domänenname (FQDN) der Instanz die DNS-Zoneenthalten. Derzeit stellt nur die REST-API der Azure KI Search Management einen dnsZonePrefix Parameter für die Annahme der DNS-Zonenspezifikation bereit.

Obwohl Sie die Verwaltungs-REST-API direkt aufrufen können, ist es einfacher, das Azure CLI-Modul az rest zum Senden von Verwaltungs-REST-API-Aufrufen über eine Befehlszeile zu verwenden. In diesem Artikel wird die Azure CLI mit REST verwendet, um den privaten Link einzurichten.

Hinweis

Dieser Artikel bezieht sich auf das Azure-Portal zum Abrufen von Eigenschaften und zur Bestätigung der Schritte. Stellen Sie beim Erstellen des freigegebenen privaten Links für die verwaltete SQL-Instanz jedoch sicher, dass Sie die REST-API verwenden. Obwohl auf der Registerkarte „Netzwerk“ Microsoft.Sql/managedInstances als Option aufgeführt ist, unterstützt das Azure-Portal derzeit nicht das erweiterte URL-Format, das von SQL Managed Instance verwendet wird.

Voraussetzungen

Azure-Befehlszeilenschnittstelle
Azure KI Search, Einfach oder höher. Wenn Sie KI-Anreicherung und Skillsets verwenden, verwenden Sie den Tarif „Standard 2“ (S2). In den Einschränkungen für Dienste finden Sie weitere Informationen.
Azure SQL Managed Instance, konfiguriert für die Ausführung in einem virtuellen Netzwerk.
Sie sollten mindestens über die Mitwirkenden-Berechtigungen für Azure KI Search und die verwaltete SQL-Instanz verfügen.
Azure SQL Managed Instance-Verbindungszeichenfolge. Verwaltete Identität wird derzeit nicht mit freigegebenem privaten Link unterstützt. Ihre Verbindungszeichenfolge muss einen Benutzernamen und ein Kennwort enthalten.

Hinweis

Freigegebene private Verbindungen können über die Preise für Azure Private Link in Rechnung gestellt werden, und die Gebühren werden auf der Grundlage des Verbrauchs berechnet.

1 - Abrufen von Verbindungsinformationen

Rufen Sie den FQDN der verwalteten Instanz ab, einschließlich der DNS-Zone. Die DNS-Zone ist Teil des Domänennamens der verwalteten SQL-Instanz. Wenn beispielsweise der FQDN der verwalteten SQL-Instanz my-sql-managed-instance.00000000000.database.windows.net ist, ist 00000000000 die DNS-Zone.

Suchen Sie im Azure-Portal das SQL Managed Instance Objekt.
Suchen Sie auf der Registerkarte Übersicht nach der Eigenschaft „Host“. Kopieren Sie den DNS-Zonenteil des FQDN für den nächsten Schritt.
Kopieren Sie auf der Registerkarte Verbindungszeichenfolgen die ADO.NET Verbindungszeichenfolge für einen späteren Schritt. Sie ist für die Datenquellenverbindung beim Testen der privaten Verbindung erforderlich.

Weitere Informationen zu Verbindungseigenschaften finden Sie unter Erstellen einer Azure SQL Managed Instance.

2 - Erstellen des Texts der Anforderung

Erstellen Sie mit einem Text-Editor den JSON-Code für den freigegebenen privaten Link.

{
    "name": "{{shared-private-link-name}}",
    "properties": {
        "privateLinkResourceId": "/subscriptions/{{target-resource-subscription-ID}}/resourceGroups/{{target-resource-rg}}/providers/Microsoft.Sql/managedInstances/{{target-resource-name}}",
        "dnsZonePrefix": "a1b22c333d44",
        "groupId": "managedInstance",
        "requestMessage": "please approve",
    }
}

Geben Sie einen aussagekräftigen Namen für den freigegebenen privaten Link an. Der freigegebene private Link wird zusammen mit anderen privaten Endpunkten angezeigt. Ein Name wie „geteilter-privater-link-zur-suche“ kann Sie daran erinnern, wie er verwendet wird.
Fügen Sie den DNS-Zonennamen in das dnsZonePrefix-Element ein, das Sie in einem früheren Schritt abgerufen haben.
Bearbeiten Sie die „privateLinkResourceId“, um den privaten Endpunkt Ihrer verwalteten Instanz widerzuspiegeln. Geben Sie die Abonnement-ID, den Ressourcengruppennamen und den Objektnamen der verwalteten Instanz an.
Speichern Sie die Datei lokal als create-pe.json (oder verwenden Sie einen anderen Namen, und denken Sie daran, die Azure CLI-Syntax im nächsten Schritt zu aktualisieren).
Geben Sie in der Azure CLI dir ein, um den aktuellen Speicherort der Datei zu notieren.

3 - Erstellen einer freigegebenen privaten Verbindung

Melden Sie sich über die Befehlszeile mit az login bei Azure an.
Wenn Sie über mehrere Abonnements verfügen, stellen Sie sicher, dass Sie jenes verwenden, welches Sie verwenden möchten: az account show.

Verwenden Sie zum Festlegen des Abonnements az account set --subscription {{subscription ID}}
Rufen Sie den az rest Befehl auf, um die Verwaltungs-REST-API von Azure KI Search zu verwenden.

Da sich die Unterstützung für freigegebene private Links für verwaltete SQL-Instanzen noch in der Vorschau befindet, benötigen Sie eine Vorschauversion der REST-API. Verwenden Sie 2021-04-01-preview oder eine höhere API-Vorschauversion für diesen Schritt. Wir empfehlen die Verwendung der neuesten API-Vorschauversion.
```
az rest --method put --uri https://management.azure.com/subscriptions/{{search-service-subscription-ID}}/resourceGroups/{{search service-resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/sharedPrivateLinkResources/{{shared-private-link-name}}?api-version=2024-06-01-preview --body @create-pe.json
```
Geben Sie die Abonnement-ID, den Ressourcengruppennamen und den Dienstnamen Ihrer Azure KI Search-Ressource an.

Geben Sie denselben freigegebenen privaten Linknamen an, den Sie im JSON-Textkörper angegeben haben.

Geben Sie einen Pfad zur Datei create-pe.json an, wenn Sie den Dateispeicherort verlassen haben. Sie können in der Befehlszeile dir eingeben, um zu bestätigen, dass sich die Datei im aktuellen Verzeichnis befindet.
Drücken Sie die EINGABETASTE, um den Befehl auszuführen.

Wenn Sie diese Schritte ausführen, sollten Sie über einen freigegebenen privaten Link verfügen, der in einem ausstehenden Zustand bereitgestellt wird. Die Erstellung des Links dauert einige Minuten. Nachdem er erstellt wurde, muss der Ressourcenbesitzer die Anforderung genehmigen, bevor er betriebsbereit ist.

4 - Genehmigen der Verbindung mit einem privaten Endpunkt

Auf der Seite der verwalteten SQL-Instanz muss der Ressourcenbesitzer die von Ihnen erstellte private Verbindungsanforderung genehmigen.

Öffnen Sie im Azure-Portal die Registerkarte Private Endpunktverbindungen der verwalteten Instanz.
Suchen Sie nach dem Abschnitt, in dem die Verbindungen mit privaten Endpunkten aufgeführt sind.
Wählen Sie die Verbindung und dann wählen Sie dannGenehmigen aus. Es kann einige Minuten dauern, bis der Status im Azure-Portal aktualisiert wird.

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

5 – Überprüfen des Status des freigegebenen privaten Links

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

6. Konfigurieren der Indexerausführung in der privaten Umgebung

Sie können jetzt einen Indexer und seine Datenquelle so konfigurieren, dass eine ausgehende private Verbindung mit Ihrer verwalteten Instanz verwendet wird.

Sie können den Assistent zum Importieren von Daten für diesen Schritt verwenden, aber der generierte Indexer ist für dieses Szenario nicht gültig. Sie müssen die JSON-Eigenschaft der Indexer ändern, wie in diesem Schritt beschrieben, um sie für dieses Szenario kompatibel zu machen. Anschließend müssen Sie den Indexer zurücksetzen und erneut ausführen, um die Pipeline mit dem aktualisierten Indexer vollständig zu testen.

In diesem Artikel wird davon ausgegangen, dass ein REST-Client verwendet wird und die REST-APIs verwendet werden, um die Anzeige aller Eigenschaften zu vereinfachen. Erinnern Sie sich daran, dass REST-API-Aufrufe für Indexer und Datenquellen die Search-REST-APIsverwenden, nicht die Verwaltungs-REST-APIs, die zum Erstellen der freigegebenen privaten Verknüpfung verwendet werden. Die Syntax und API-Versionen unterscheiden sich zwischen den beiden REST-APIs.

Erstellen Sie die Datenquellendefinition wie gewohnt für Azure SQL. Das Format der Verbindungszeichenfolge unterscheidet sich für eine verwaltete Instanz geringfügig, andere Eigenschaften sind jedoch identisch mit der Konfiguration einer Datenquellenverbindung mit der Azure SQL-Datenbank.

Geben Sie die zuvor kopierte Verbindungszeichenfolge mit einem Ursprungskatalog an.

POST https://myservice.search.windows.net/datasources?api-version=2024-07-01
 Content-Type: application/json
 api-key: admin-key
 {
     "name" : "my-sql-datasource",
     "description" : "A database for testing Azure AI Search indexes.",
     "type" : "azuresql",
     "credentials" : { 
         "connectionString" : "Server=tcp:contoso.public.0000000000.database.windows.net,1433;Persist Security Info=false; User ID=<your user name>; Password=<your password>;MultipleActiveResultsSets=False; Encrypt=True;Connection Timeout=30;Initial Catalog=<your database name>"
        },
     "container" : { 
         "name" : "Name of table or view to index",
         "query" : null (not supported in the Azure SQL indexer)
         },
     "dataChangeDetectionPolicy": null,
     "dataDeletionDetectionPolicy": null,
     "encryptionKey": null
 }

Erstellen Sie die Indexerdefinition, und legen Sie den Indexer executionEnvironment auf „privat“ fest.

Die Indexerausführung erfolgt entweder in einer privaten Ausführungsumgebung, die spezifisch für Ihren Suchdienst ist, oder in einer Umgebung mit mehreren Mandanten, die von Microsoft gehostet und verwendet wird, um die teure Skillsetverarbeitung für mehrere Kunden auszulagern. Beim Herstellen einer Verbindung über einen privaten Endpunkt muss die Indexerausführung privat sein.
```
 POST https://myservice.search.windows.net/indexers?api-version=2024-07-01
  Content-Type: application/json
  api-key: admin-key
    {
     "name": "indexer",
     "dataSourceName": "my-sql-datasource",
     "targetIndexName": "my-search-index",
     "parameters": {
         "configuration": {
             "executionEnvironment": "private"
         }
     },
     "fieldMappings": []
     }
```
Führen Sie den Indexer aus. Wenn die Indexerausführung erfolgreich ausgeführt wird und der Suchindex aufgefüllt wird, funktioniert der freigegebene private Link.

Sie können den Status des Indexers mithilfe der Indexer-Status-API überwachen.

Sie können Such-Explorer im Azure-Portal verwenden, um den Inhalt des Indexes zu überprüfen.

7 - Testen des freigegebenen privaten Links

Wenn Sie den Indexer im vorherigen Schritt ausgeführt und Inhalte aus Ihrer verwalteten Instanz erfolgreich indiziert haben, war der Test erfolgreich. Wenn der Indexer jedoch fehlschlägt oder kein Inhalt im Index vorhanden ist, können Sie Ihre Objekte ändern und Tests wiederholen, indem Sie einen beliebigen Client auswählen, der eine ausgehende Anforderung von einem Indexer aufrufen kann.

Eine einfache Option besteht darin, einen Indexer im Azure-Portal auszuführen, Sie können aber auch einen REST-Client und REST-APIs für eine genauere Genauigkeit ausprobieren. Vorausgesetzt, Ihr Suchdienst ist nicht ebenfalls für eine private Verbindung konfiguriert, kann die REST-Clientverbindung zur Suche über das öffentliche Internet erfolgen.

Hier sind einige Erinnerungen für Tests:

Wenn Sie einen REST-Client verwenden, verwenden Sie die Verwaltungs-REST-API und die Version 2021-04-01-Preview-API, um den freigegebenen privaten Link zu erstellen. Verwenden Sie die Search-REST-API und eine stabile API-Version, um Indexer und Datenquellen zu erstellen und aufzurufen.
Mit dem Assistenten zum Importieren von Daten können Sie einen Indexer, eine Datenquelle und einen Index erstellen. Der generierte Indexer verfügt jedoch nicht über die richtige Einstellung für die Ausführungsumgebung.
Sie können die JSON-Datei der Datenquelle und des Indexers im Azure-Portal bearbeiten, um Eigenschaften zu ändern, einschließlich der Ausführungsumgebung und der Verbindungszeichenfolge.
Sie können den Indexer im Azure-Portal zurücksetzen und erneut ausführen. Das Zurücksetzen ist für dieses Szenario wichtig, da dadurch eine vollständige Neuverarbeitung aller Dokumente erzwungen wird.
Sie können den Such-Explorer verwenden, um den Inhalt des Indexes zu überprüfen.

Freigeben über