Gestire il servizio Azure AI Search usando le API REST

Informazioni su come creare e configurare un servizio Azure AI Search usando le API REST Management. Solo le API REST di gestione garantiscono l'accesso anticipato alle funzionalità di anteprima.

L'API REST di gestione è disponibile in versioni stabili e di anteprima. Assicurarsi di impostare una versione dell'API di anteprima se si accede alle funzionalità di anteprima.

Tutte le API REST di gestione hanno esempi. Se un'attività non è descritta in questo articolo, vedere invece le informazioni di riferimento sulle API .

Suggerimento

Se si usa CURL per chiamare l'API REST di gestione, assicurarsi di impostare un'intestazione del tipo di contenuto su application/json: -H "Content-Type: application/json". In alternativa, è possibile usare il --JSON flag se si vuole incorporare il codice JSON.

Prerequisiti

  • Un account Azure con una sottoscrizione attiva. Creare gratuitamente un account.

  • Visual Studio Code con un client REST.

  • interfaccia della riga di comando di Azure per ottenere un token di accesso, come descritto nei passaggi seguenti. È necessario essere un proprietario o un amministratore nella sottoscrizione Azure.

    Le chiamate API REST di gestione vengono autenticate tramite Microsoft Entra ID. È necessario fornire un token di accesso per la richiesta e le autorizzazioni per creare e configurare una risorsa. Oltre alla interfaccia della riga di comando di Azure, è possibile usare Azure PowerShell per creare un token di accesso.

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

    2. Accedere alla sottoscrizione Azure. Se hai più tenant o sottoscrizioni, assicurati di selezionare quella corretta.

      az login

    3. Ottenere l'ID tenant e l'ID sottoscrizione.

      az account show

    4. Ottenere un token di accesso.

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

      È necessario avere un ID tenant, un ID sottoscrizione e un token di tipo bearer. Questi valori verranno incollati nel .rest file o .http creato 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 questo articolo.

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

  2. Cercare il client REST e selezionare Installa.

    Screenshot del comando di installazione.

  3. Aprire o creare un nuovo file con il nome e l'estensione di file .rest o .http.

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

    @tenant-id = PUT-YOUR-TENANT-ID-HERE
@subscription-id = PUT-YOUR-SUBSCRIPTION-ID-HERE
@token = PUT-YOUR-TOKEN-HERE

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

     ### List search services
 GET https://management.azure.com/subscriptions/{{subscription-id}}/providers/Microsoft.Search/searchServices?api-version=2025-05-01  HTTP/1.1
      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 è vuoto, ma purché il codice HTTP sia 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 nella sottoscrizione corrente. Questo esempio usa le variabili per il nome e l'area del servizio di ricerca, che non sono ancora stati definiti. Specificare direttamente i nomi o aggiungere nuove variabili alla raccolta.

### Create a search service (provide an existing resource group)
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PUT https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-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"
        }
      }

Aggiornare un servizio

Alcune funzionalità di Azure AI Search sono disponibili solo per i nuovi servizi. Per evitare la ricreazione del servizio e portare queste funzionalità a un servizio esistente, è possibile aggiornare il servizio.

### Upgrade a search service
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/upgrade?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Modificare i livelli tariffari

Se è necessaria più o meno capacità, è possibile passare a un piano tariffario diverso. Attualmente, è possibile passare solo tra i livelli Basic e Standard (S1, S2 e S3). Usare la sku proprietà per specificare il nuovo livello.

### Change pricing tiers
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "sku": {
            "name": "standard2"
        }
    }

Creare un servizio S3HD

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

### Create an S3HD service
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PUT https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

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

Configurare l'accesso 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 del servizio di ricerca

Configurare il servizio di ricerca per riconoscere un'intestazione di 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 su authOptionsaadOrApiKey e quindi inviare la richiesta.

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

### Configure role-based access
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

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

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

Configurare il calcolo confidenziale

Confidential computing è un tipo di calcolo facoltativo per la protezione dei dati in uso. Se configurato, il servizio di ricerca viene distribuito in macchine virtuali riservate (DCasv5 o DCesv5) anziché in macchine virtuali standard. Questo tipo di calcolo comporta anche un supplemento di 10% per i livelli fatturabili. Per altre informazioni, vedere la pagina dei prezzi.

Per l'utilizzo giornaliero, il confidential computing non è necessario. È consigliabile usare questo tipo di calcolo solo per requisiti normativi, di conformità o di sicurezza rigorosi. Per altre informazioni, vedere Casi d'uso di Confidential computing.

Il tipo di calcolo è fisso per la durata del servizio di ricerca. Per configurare in modo permanente il confidential computing, impostare la computeType proprietà su confidential in un nuovo servizio.

### Configure confidential computing
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE
PUT https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
    Content-type: application/json
    Authorization: Bearer {{token}}
    {
        "location": "{{region}}",
        "sku": {
            "name": "basic"
        },
        "properties": {
            "computeType": "confidential"
        }
    }

Applicare una politica di chiave gestita dal cliente

Se si usa la crittografia gestita dal cliente, è possibile abilitare "encryptionWithCMK" con "imposizione" impostata su "Abilitato" se si vuole che il servizio di ricerca ne segnala lo stato di conformità.

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

### Enforce a customer-managed key policy
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

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

Disabilitare i carichi di lavoro che inviano dati a risorse esterne

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

### Disable external access
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "publicNetworkAccess": "Disabled"
        }
    }

Eliminare un servizio di ricerca

### Delete a search service
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

DELETE https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Elencare le chiavi API di amministrazione

### List admin keys
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/listAdminKeys?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Rigenerare le chiavi API di amministrazione

È possibile rigenerare una sola chiave API amministratore alla volta.

### Regnerate admin keys
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/regenerateAdminKey/primary?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Creare chiavi API di query

### Create a query key
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE
@query-key = PUT-YOUR-QUERY-KEY-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/createQueryKey/{query-key}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Elenca le connessioni dell'endpoint privato

### List private endpoint connections
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

GET https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/privateEndpointConnections?api-version=2025-05-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/{{subscription-id}}/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 creare un indice o interrogare un indice usando il portale di Azure, le API REST o un SDK di Azure.

  • Last updated on