Creare un collegamento privato condiviso per un'istanza gestita di SQL da Azure AI Search

Articolo
02/25/2025

Questo articolo illustra come configurare un indicizzatore in Azure AI Search per una connessione privata a un'istanza gestita di SQL eseguita all'interno di una rete virtuale. La connessione privata avviene tramite un collegamento privato condiviso e un collegamento privato di Azure.

In una connessione privata a un'istanza gestita, il nome di dominio completo (FQDN) dell'istanza deve includere la zona DNS. Attualmente, solo l'API REST di gestione Azure AI Search fornisce un parametro dnsZonePrefix con cui accettare la specifica della zona DNS.

Anche se è possibile chiamare direttamente l'API REST di gestione, è più semplice usare il modulo az rest dell'interfaccia della riga di comando di Azure per inviare chiamate API REST di gestione da una riga di comando. In questo articolo viene illustrato l’uso dell'interfaccia della riga di comando di Azure con REST per configurare il collegamento privato.

Nota

Questo articolo fa riferimento al portale di Azure per ottenere le proprietà e confermare la procedura. Tuttavia, quando si crea il collegamento privato condiviso per Istanza gestita di SQL, assicurarsi di usare l'API REST. Anche se la scheda Rete è elencata Microsoft.Sql/managedInstances come opzione, il portale di Azure attualmente non supporta il formato di URL esteso usato da Istanza gestita di SQL.

Prerequisiti

Interfaccia della riga di comando di Azure
Azure AI Search, Basic o versione superiore. Se si usano set di competenze e arricchimento tramite intelligenza artificiale, usare la versione standard 2 (S2) o superiore. Per informazioni dettagliate, vedere Limiti del servizio.
Istanza gestita di SQL di Azure, configurata per l'esecuzione in una rete virtuale.
È necessario avere almeno le autorizzazioni di Collaboratore sia per Azure AI Search che per Istanza gestita di SQL.
Stringa di connessione di Istanza gestita di SQL di Azure. L'identità gestita non è attualmente supportata con il collegamento privato condiviso. La stringa di connessione deve includere un nome utente e una password.

Nota

I collegamenti privati condivisi sono fatturabili secondo i prezzi del collegamento privato di Azure e gli addebiti vengono fatturati in base all'utilizzo.

1 - Recuperare informazioni sulla connessione

In questa sezione ottenere la zona DNS dal nome host e una stringa di connessione.

Nel portale di Azure, trovare l'oggetto Istanza gestita di SQL.
Nella scheda Informazioni generali individuare la proprietà Host. Copiare la parte della zona DNS del nome di dominio completo per il passaggio successivo. La zona DNS fa parte del nome di dominio dell'istanza gestita di SQL. Ad esempio, se il nome di dominio completo dell'istanza gestita di SQL è my-sql-managed-instance.a1b22c333d44.database.windows.net, la zona DNS è a1b22c333d44.
Nella scheda Stringhe di connessione copiare la stringa di connessione ADO.NET per uno dei passaggi successivi. È necessaria per la connessione all'origine dati durante il test della connessione privata.

Per altre informazioni sulle proprietà di connessione, vedere Creare un'istanza gestita di SQL di Azure.

2 - Creare il corpo della richiesta

Con un editor di testo, creare il codice JSON per il collegamento privato condiviso.
```
{
    "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"
    }
}
```
Specificare un nome significativo per il collegamento privato condiviso. Il collegamento privato condiviso viene visualizzato insieme ad altri endpoint privati. Un nome come "link-privato-condiviso-per-search" può ricordare come viene usato.

Incollare il nome della zona DNS in "dnsZonePrefix" recuperato in un passaggio precedente.

Modificare "privateLinkResourceId", sostituire i valori validi per i segnaposto. Specificare un ID sottoscrizione valido, il nome del gruppo di risorse e il nome dell'istanza gestita.
Salvare il file in locale come create-pe.json (o usare un altro nome, ricordando di aggiornare la sintassi dell'interfaccia della riga di comando di Azure nel passaggio successivo).
Nell'interfaccia della riga di comando di Azure digitare dir per prendere nota del percorso corrente del file.

3 - Creare un collegamento privato condiviso

Dalla riga di comando accedere ad Azure usando az login.
Se si hanno più sottoscrizioni, assicurarsi di usare quella che si intende usare: az account show.

Per impostare la sottoscrizione, usare az account set --subscription {{subscription ID}}
Chiamare il comando az rest per usare l'API REST di gestione di Azure AI Search.

Poiché il supporto dei collegamenti privati condivisi per le istanze gestite di SQL è ancora in anteprima, è necessaria una versione di anteprima dell'API REST di gestione. Usare 2021-04-01-preview o una versione di anteprima successiva dell’API per questo passaggio. È consigliabile usare la versione di anteprima più recente dell’API.
```
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
```
Specificare l'ID sottoscrizione, il nome del gruppo di risorse e il nome del servizio della risorsa di Azure AI Search.

Immettere lo stesso nome di collegamento privato condiviso specificato nel corpo JSON.

Specificare un percorso del file create-pe.json, se ci si è spostati dalla posizione del file. È possibile digitare dir nella riga di comando per verificare che il file si trovi nella directory corrente.
Eseguire il comando .

Completati questi passaggi, si dovrebbe disporre di un collegamento privato condiviso di cui è stato effettuato il provisioning in stato in sospeso. La creazione del collegamento richiede alcuni minuti. Una volta creato, il proprietario della risorsa deve approvare la richiesta affinché sia operativa.

È possibile controllare lo stato del collegamento privato condiviso nella portale di Azure. Nella pagina del servizio di ricerca, in Proprietà impostazioni>scorrere verso il basso per trovare le risorse del collegamento privato condiviso e visualizzare il valore JSON. Quando lo stato del provisioning passa da in sospeso a riuscito, è possibile continuare con il passaggio successivo.

4 - Approvare la connessione endpoint privato

Lato Istanza gestita di SQL, il proprietario della risorsa deve approvare la richiesta di connessione privata creata.

Nella portale di Azure aprire le connessioni dell'endpoint privato di sicurezza>dell'istanza gestita.
Trovare la sezione in cui sono elencate le connessioni dell'endpoint privato.
Selezionare la connessione e quindi Approva. L'aggiornamento dello stato nella portale di Azure può richiedere alcuni minuti.

Dopo l'approvazione dell'endpoint privato, Azure AI Search crea i mapping di zona DNS necessari nella zona DNS creata.

5 - Controllare lo stato del collegamento privato condiviso

Lato Azure AI Search è possibile confermare l'approvazione della richiesta rivedendo la scheda Accesso privato condiviso della pagina Rete del servizio di ricerca. Lo stato della connessione dovrebbe essere approvato.

6 - Configurare l'indicizzatore per l'esecuzione nell'ambiente privato

È ora possibile configurare un indicizzatore e la relativa origine dati in modo che venga usata una connessione privata in uscita all'istanza gestita.

Questo articolo presuppone un client REST e usa le API REST.

Creare la definizione dell'origine dati come si farebbe normalmente per Azure SQL. Per impostazione predefinita, un'istanza gestita è in ascolto sulla porta 3342, ma in una rete virtuale è in ascolto sulla porta 1433.

Specificare il stringa di connessione copiato in precedenza con un catalogo iniziale impostato sul nome del database.

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.a1b22c333d44.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
 }

Creare la definizione dell'indicizzatore impostando l'indicizzatore executionEnvironment su "private".

L'esecuzione dell'indicizzatore si verifica in un ambiente di esecuzione privato specifico del servizio di ricerca o in un ambiente multi-tenant ospitato da Microsoft e usato per eseguire l'offload di costose elaborazioni del set di competenze per più clienti. Quando ci si connette tramite un endpoint privato, l'esecuzione dell'indicizzatore deve essere privata.
```
 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": []
     }
```
Eseguire l'indicizzatore. Se l'esecuzione dell'indicizzatore ha esito positivo e l'indice di ricerca viene popolato, il collegamento privato condiviso funziona.

È possibile monitorare lo stato dell'indicizzatore nel portale di Azure o tramite l'API Stato dell'indicizzatore.

È possibile usare Esplora ricerche nel portale di Azure per controllare il contenuto dell'indice.

7 - Testare il collegamento privato condiviso

Se l'indicizzatore è stato eseguito nel passaggio precedente e il contenuto indicizzato correttamente dall'istanza gestita, il test ha avuto esito positivo. Tuttavia, se l'indicizzatore dà errore o non è presente contenuto nell'indice, è possibile modificare gli oggetti e ripetere il test scegliendo qualsiasi client in grado di richiamare una richiesta in uscita da un indicizzatore.

Una scelta semplice consiste nell’eseguire un indicizzatore nel portale di Azure, ma si può anche provare con un client REST e con le API REST per una maggiore precisione. Supponendo che il servizio di ricerca non sia configurato anche per una connessione privata, la connessione client REST a Ricerca intelligenza artificiale di Azure può essere tramite Internet pubblico.

Ecco alcuni promemoria per il test:

Se si usa un client REST, usare l'API REST di gestione e la versione dell'API 2021-04-01 anteprima per creare il collegamento privato condiviso. Usare l'API REST di ricerca e una versione stabile dell'API per creare e richiamare indicizzatori e origini dati.
È possibile usare l’importazione guidata dati per creare un indicizzatore, un'origine dati e un indice. Tuttavia, l'indicizzatore generato non avrà l'impostazione corretta dell'ambiente di esecuzione.
È possibile modificare l'origine dati e il codice JSON dell'indicizzatore nel portale di Azure per cambiare le proprietà, tra cui l'ambiente di esecuzione e la stringa di connessione.
È possibile reimpostare ed eseguire di nuovo l'indicizzatore nel portale di Azure. In questo scenario è importante reimpostarlo perché questo permette una rielaborazione completa di tutti i documenti.
È possibile usare Esplora ricerche per controllare il contenuto dell'indice.

Condividi tramite