Gestire il servizio Azure AI Search con API REST

  • Articolo

In questo articolo viene illustrato come creare e configurare un servizio Azure AI Search tramite le API REST di Gestione. Solo le API REST di Gestione garantiscono l'accesso anticipato alle funzionalità di anteprima.

L'API REST di Gestione è disponibile nelle versioni stabile e di anteprima. Se si accede a funzionalità di anteprima, assicurarsi di impostare una versione API di anteprima.

Tutte le API REST di Gestione dispongono di esempi. Se un'attività non viene trattata in questo articolo, vedere la documentazione di riferimento dell'API.

Prerequisiti

Ottenere un token di accesso

Le chiamate API REST di gestione vengono autenticate tramite Microsoft Entra ID. Nella richiesta, è necessario fornire un token di accesso, insieme alle autorizzazioni per creare e configurare una risorsa.

È possibile usare l’interfaccia della riga di comando di Azure o Azure PowerShell per creare un token di accesso.

  1. Aprire una shell di comando per l’interfaccia della riga di comando di Azure.

  2. Accedere alla sottoscrizione di Azure.

    az login

  3. Ottenere l'ID tenant e l'ID sottoscrizione. Se si dispone di più tenant o sottoscrizioni, assicurarsi di usare quella corretta.

    az account show

  4. Ottenere un token di accesso.

    az account get-access-token --query accessToken --output tsv

È necessario disporre di un ID tenant, di un ID sottoscrizione e di un token di connessione. Questi valori dovranno essere incollati nel file .rest o .http che si creerà nel passaggio successivo.

Configurare Visual Studio Code

Se non si ha familiarità con il client REST per Visual Studio Code, questa sezione include la configurazione in modo da poter completare le attività in questa guida introduttiva.

  1. Avviare Visual Studio Code e selezionare il riquadro Estensioni.

  2. Cercare il client REST e selezionare Installa.

    Screenshot del comando di installazione.

  3. Aprire o creare un nuovo file denominato con un'estensione del file .rest o .http.

  4. Fornire le variabili per i valori recuperati nel passaggio precedente.

    @tenantId = PASTE-YOUR-TENANT-ID-HERE
@subscriptionId = PASTE-YOUR-SUBSCRIPTION-ID-HERE
@token = PASTE-YOUR-TOKEN-HERE

  5. Verificare che la sessione sia operativa elencando i servizi di ricerca presenti nella sottoscrizione.

     ### List search services
 GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01
      Content-type: application/json
      Authorization: Bearer {{token}}

  6. Selezionare Invia richiesta. Una risposta dovrebbe essere visualizzata in un riquadro adiacente. Se sono presenti servizi di ricerca esistenti, vengono elencati. In caso contrario, l'elenco risulta vuoto, ma se il codice HTTP è 200 OK, si è pronti per i passaggi successivi.

    HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 22068
Content-Type: application/json; charset=utf-8
Expires: -1
x-ms-ratelimit-remaining-subscription-reads: 11999
x-ms-request-id: f47d3562-a409-49d2-b9cd-6a108e07304c
x-ms-correlation-request-id: f47d3562-a409-49d2-b9cd-6a108e07304c
x-ms-routing-request-id: WESTUS2:20240314T012052Z:f47d3562-a409-49d2-b9cd-6a108e07304c
Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
X-Cache: CONFIG_NOCACHE
X-MSEdge-Ref: Ref A: 12401F1160FE4A3A8BB54D99D1FDEE4E Ref B: CO6AA3150217011 Ref C: 2024-03-14T01:20:52Z
Date: Thu, 14 Mar 2024 01:20:52 GMT
Connection: close

{
  "value": [ . . . ]
}

Creare o aggiornare un servizio

Crea o aggiorna un servizio di ricerca nell'ambito della sottoscrizione corrente. In questo esempio vengono usate le variabili per il nome del servizio di ricerca e l'area geografica, che non sono ancora state definite. Fornire direttamente i nomi, oppure aggiungere nuove variabili alla raccolta.

### Create a search service (provide an existing resource group)
@resource-group = my-rg
@search-service-name = my-search
PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "location": "North Central US",
        "sku": {
            "name": "basic"
        },
        "properties": {
            "replicaCount": 1,
            "partitionCount": 1,
            "hostingMode": "default"
        }
      }

Creare un servizio S3HD

Per creare un servizio S3HD usare una combinazione delle proprietà sku e hostingMode. Impostare sku su standard3 e "hostingMode" su HighDensity.

@resource-group = my-rg
@search-service-name = my-search
PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "location": "{{region}}",
        "sku": {
          "name": "standard3"
        },
        "properties": {
          "replicaCount": 1,
          "partitionCount": 1,
          "hostingMode": "HighDensity"
        }
    }

Configurare il controllo degli accessi in base al ruolo per il piano dati

Si applica a: Collaboratore ai dati dell'indice di ricerca, Lettore di dati dell'indice di ricerca, Collaboratore Servizio di ricerca

In questo passaggio configurare il servizio di ricerca in modo da riconoscere un'intestazione dell'autorizzazione nelle richieste di dati che forniscono un token di accesso OAuth2.

Per usare il controllo degli accessi in base al ruolo per le operazioni del piano dati, impostare authOptions su aadOrApiKey e quindi inviare la richiesta.

Per usare esclusivamente il controllo degli accessi in base al ruolo, disattivare l'autenticazione della chiave API eseguendo una seconda richiesta, questa volta impostando disableLocalAuth su true.

PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "properties": {
            "disableLocalAuth": false,
            "authOptions": {
                "aadOrApiKey": {
                    "aadAuthFailureMode": "http401WithBearerChallenge"
                }
            }
        }
    }

Applicare un criterio della chiave gestita dal cliente

Se si usa la crittografia gestita dal cliente, è possibile abilitare "encryptionWithCMK" con "tutela" impostato su "Abilitato", se si vuole che il servizio di ricerca riporti il relativo stato di conformità.

Quando si abilita questo criterio, qualsiasi chiamata REST che crea oggetti contenenti dati sensibili, ad esempio la stringa di connessione all'interno di un'origine dati, non riuscirà se non viene fornita una chiave di crittografia: "Error creating Data Source: "CannotCreateNonEncryptedResource: The creation of non-encrypted DataSources is not allowed when encryption policy is enforced."

PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "encryptionWithCmk": {
                "enforcement": "Enabled"
            }
        }
    }

Disabilitare il classificatore semantico

Sebbene il classificatore semantico non sia abilitato per impostazione predefinita, è possibile bloccare la funzionalità a livello di servizio per assicurarsi che non venga utilizzato.

### disable semantic ranker
PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "semanticSearch": "Disabled"
        }
    }

Disabilitare i carichi di lavoro che eseguono il push dei dati alla risorse esterne

Azure AI Search scrive in origini dati esterne durante l'aggiornamento di un archivio conoscenze, il salvataggio dello stato della sessione di debug o la memorizzazione nella cache degli arricchimenti. Nell’esempio seguente vengono disabilitati questi carichi di lavoro a livello di servizio.

### disable-external-access
PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "publicNetworkAccess": "Disabled"
        }
    }

Eliminare un servizio di ricerca

### delete a search service
DELETE https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Elencare le chiave API di amministrazione

### List admin keys
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/listAdminKeys?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Rigenerare le chiavi API di amministrazione

È possibile rigenerare solo una chiave API di amministrazione alla volta.

### Regnerate admin keys
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/regenerateAdminKey/primary?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Creare chiavi API di query

### Create a query key
@query-key-name = myQueryKey
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/createQueryKey/{name}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Elencare le connessioni all’endpoint privato

### List private endpoint connections
GET https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/privateEndpointConnections?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Elencare le operazioni di ricerca

### List search operations
GET https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups?api-version=2021-04-01 HTTP/1.1
  Content-type: application/json
  Authorization: Bearer {{token}}

Passaggi successivi

Dopo aver configurato un servizio di ricerca, i passaggi successivi includono la creazione di un indice o l'esecuzione di una query su un indice tramite il portale, le API REST o un SDK di Azure.