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

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 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 per accettare la specifica della zona DNS.

Anche se è possibile chiamare direttamente l'API REST di gestione, è più semplice usare il modulo interfaccia della riga di comando di Azure az rest per inviare chiamate ALL'API REST di gestione da una riga di comando. Questo articolo usa il interfaccia della riga di comando di Azure con REST per configurare il collegamento privato.

Nota

Questo articolo si riferisce al portale di Azure per ottenere le proprietà e confermare le procedure. Tuttavia, quando si crea il collegamento privato condiviso per Istanza gestita di SQL, assicurarsi di usare l'API REST. Sebbene la scheda Rete elenchi 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 successiva. 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, configurato per l'esecuzione in una rete virtuale.

  • È necessario avere almeno le autorizzazioni di collaboratore per Azure AI Search e Istanza gestita di SQL.

  • Stringa di connessione nell'Istanza gestita di SQL di Azure L'identità gestita non è attualmente supportata con il collegamento privato condiviso. Il stringa di connessione deve includere un nome utente e una password.

Nota

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

1 - Recuperare informazioni sulla connessione

In questa sezione, ottieni la zona DNS dal nome host e da una stringa di connessione.

  1. Nel portale di Azure, individua l'oggetto Istanza SQL gestita.

  2. Nella scheda Informazioni generali individuare la proprietà Host. Copia la zona DNS del FQDN per il passaggio successivo. La zona DNS fa parte del nome di dominio del Istanza gestita di SQL. Ad esempio, se l'FQDN del Istanza gestita di SQL è my-sql-managed-instance.a1b22c333d44.database.windows.net, la zona DNS è a1b22c333d44.

  3. Nella scheda Stringhe di connessione copiare ADO.NET stringa di connessione per un passaggio successivo. È 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

  1. 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-ricerca" può aiutarti a ricordare come viene utilizzato.

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

    Modificare "privateLinkResourceId" e sostituire i segnaposto con valori validi. Specificare un ID sottoscrizione valido, il nome del gruppo di risorse e il nome dell'istanza gestita.

  2. Salvare il file in locale come create-pe.json (o usare un altro nome, ricordando di aggiornare la sintassi interfaccia della riga di comando di Azure nel passaggio successivo).

  3. Nella interfaccia della riga di comando di Azure digitare dir per prendere nota del percorso corrente del file.

3 - Creare un collegamento privato condiviso

  1. Dalla riga di comando accedere Azure usando az login.

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

  3. Chiamare il comando az rest per usare l'API REST Management di Azure AI Search.

    Il supporto dei collegamenti privati condivisi per le istanze gestite di SQL è in anteprima, pertanto è necessario usare una versione di anteprima dell'API REST di gestione. È consigliabile usare la versione più recente dell'API di anteprima.

    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=2026-03-01-preview --body @create-pe.json

    Specificare l'ID sottoscrizione, il nome del gruppo di risorse e il nome del servizio della risorsa 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.

  4. Eseguire il comando .

Una volta completati questi passaggi, dovresti avere un collegamento privato condiviso che è stato configurato in uno 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 nel 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 dell'approvvigionamento passa da in sospeso a riuscito, puoi procedere al passo successivo.

4 - Approvare la connessione dell'endpoint privato

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

  1. Nel portale di Azure, aprire la sezione Sicurezza>Connessioni endpoint private dell'istanza gestita.

  2. Trova la sezione che elenca le connessioni dell'endpoint privato.

  3. Selezionare la connessione e quindi Approva. L'aggiornamento dello stato nel 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

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

Screenshot del portale di Azure, che mostra una risorsa di collegamento privato condiviso

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.

  1. 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 la stringa di connessione copiata in precedenza con un Catalogo iniziale impostato sul proprio nome del database.

    POST https://myservice.search.windows.net/datasources?api-version=2025-09-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
 }

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

    Indexer execution 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=2025-09-01
  Content-Type: application/json
  api-key: admin-key
    {
     "name": "indexer",
     "dataSourceName": "my-sql-datasource",
     "targetIndexName": "my-search-index",
     "parameters": {
         "configuration": {
             "executionEnvironment": "private"
         }
     },
     "fieldMappings": []
     }

  3. 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 oppure usando l'API Indexer Status API.

È possibile usare Search Explorer 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 è eseguire un indicizzatore nel portale di Azure, ma è anche possibile provare un client REST e le API REST per maggiore precisione. Supponendo che il servizio di ricerca non sia configurato anche per una connessione privata, la connessione client REST a Azure AI Search può trovarsi su Internet pubblico.

Ecco alcuni promemoria per il test:

  • Se si usa un client REST, usare l'API REST di gestione e la versione più recente dell'API di 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 la procedura guidata Importa 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 in Azure portale per modificare le proprietà, tra cui l'ambiente di esecuzione e il 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.

Vedi anche

  • Last updated on