Uw Azure AI Zoeken-service beheren met REST API's

Note

Azure AI Zoeken is beschikbaar via de Azure-portal, REST API's en Azure-SDK's. Het vormt ook een basis voor Foundry IQ, de beheerde kennislaag die bedrijfsinhoud transformeert in herbruikbare, machtigingsbewuste knowledge bases voor agents in de Microsoft Foundry-portal.

Meer informatie over het maken en configureren van een Azure AI Zoeken-service met behulp van de Management REST API's. Alleen de REST API's voor beheer bieden gegarandeerd vroege toegang tot preview-functies.

De Management REST API is beschikbaar in stabiele en preview-versies. Zorg ervoor dat u een preview-API-versie instelt als u preview-functies gebruikt.

Een service maken of bijwerken
Een dienst upgraden
Prijscategorieën wijzigen
Op rollen gebaseerd toegangsbeheer configureren voor het gegevensvlak
Confidential Computing configureren
Enable Azure op rollen gebaseerd toegangsbeheer voor gegevensvlak
Een door de klant beheerd sleutelbeleid afdwingen
Workloads uitschakelen die gegevens naar externe resources pushen
Een querysleutel maken
Een beheersleutel opnieuw genereren
Privé-eindpuntverbindingen vermelden
Zoekbewerkingen weergeven
Een zoekservice verwijderen

Alle REST API's voor beheer hebben voorbeelden. Als een taak niet wordt behandeld in dit artikel, raadpleegt u in plaats daarvan de API-verwijzing .

Tip

Als u CURL gebruikt om de Rest API van Management aan te roepen, moet u ervoor zorgen dat u een inhoudstypeheader instelt op application/json: -H "Content-Type: application/json". U kunt ook de --JSON vlag gebruiken als u de JSON wilt insluiten.

Voorwaarden

Een Azure-account met een actief abonnement. Maak gratis een account.
Visual Studio Code met een REST-client.
Azure CLI om een toegangstoken op te halen, zoals beschreven in de volgende stappen. U moet eigenaar of beheerder zijn in uw Azure-abonnement.

REST API-aanroepen voor beheer worden geverifieerd via Microsoft Entra ID. U moet een toegangstoken opgeven voor de aanvraag en machtigingen voor het maken en configureren van een resource. Naast de Azure CLI kunt u Azure PowerShell gebruiken om een toegangstoken te maken.
1. Open een opdrachtshell voor Azure CLI.
2. Meld u aan bij uw Azure-abonnement. Als u meerdere tenants of abonnementen hebt, moet u ervoor zorgen dat u het juiste selecteert.
```
az login
```
3. Haal de tenant-id en abonnements-id op.
```
az account show
```
4. Een toegangstoken ophalen.
```
az account get-access-token --query accessToken --output tsv
```
  U moet een tenant-id, abonnements-id en bearer-token hebben. U plakt deze waarden in het .rest bestand of .http bestand dat u in de volgende stap maakt.

Visual Studio Code instellen

Als u niet bekend bent met de REST-client voor Visual Studio Code, bevat deze sectie setup, zodat u de taken in dit artikel kunt voltooien.

Start Visual Studio Code en selecteer de tegel Extensions.
Zoek de REST-client en selecteer Installeren.
Open of creëer een nieuw bestand met een .rest of .http extensie.

Geef variabelen op voor de waarden die u in de vorige stap hebt opgehaald.

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

Controleer of de sessie operationeel is door zoekservices in uw abonnement te vermelden.

 ### 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}}

Selecteer Aanvraag verzenden. Er moet een antwoord worden weergegeven in een aangrenzend deelvenster. Als u bestaande zoekservices hebt, worden deze weergegeven. Anders is de lijst leeg, maar zolang de HTTP-code 200 OK is, bent u klaar voor de volgende stappen.

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": [ . . . ]
}

Een service maken of bijwerken

Maakt een zoekservice aan of werkt deze bij onder het huidige abonnement. In dit voorbeeld worden variabelen gebruikt voor de naam en regio van de zoekservice, die nog niet zijn gedefinieerd. Geef de namen rechtstreeks op of voeg nieuwe variabelen toe aan de verzameling.

### 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"
        }
      }

Een service upgraden

Sommige Azure AI Zoeken mogelijkheden zijn alleen beschikbaar voor nieuwe services. Om servicerecreatie te voorkomen en deze mogelijkheden naar een bestaande service te brengen, kunt u mogelijk uw service upgraden.

### 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}}

Prijscategorieën wijzigen

Als u meer of minder capaciteit nodig hebt, kunt u overschakelen naar een andere prijscategorie. Op dit moment kunt u alleen schakelen tussen de lagen Basic en Standard (S1, S2 en S3). Gebruik de sku eigenschap om de nieuwe laag op te geven.

### 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"
        }
    }

Een S3HD-service maken

Als u een S3HD-service wilt maken, gebruikt u een combinatie van sku en hostingMode eigenschappen. Ingesteld sku op standard3 en 'hostingMode' op 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"
        }
    }

Op rollen gebaseerde toegang configureren voor het gegevensvlak

Van toepassing op: Inzender voor zoekindexgegevens, zoekindexgegevenslezer, inzender voor zoekservice

Configureer uw zoekservice voor het herkennen van een autorisatieheader voor gegevensaanvragen die een OAuth2-toegangstoken bieden.

Als u op rollen gebaseerd toegangsbeheer wilt gebruiken voor bewerkingen in het gegevensvlak, stelt u deze in authOptionsaadOrApiKey en verzendt u de aanvraag.

Als u uitsluitend op rollen gebaseerd toegangsbeheer wilt gebruiken, schakelt u de API-sleutelverificatie uit door een tweede aanvraag te doen, waarbij u deze keer de instelling disableLocalAuth op true zet.

### 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"
                }
            }
        }
    }

Confidential Computing configureren

Confidential Computing is een optioneel rekentype voor de beveiliging van gegevens in gebruik. Wanneer deze is geconfigureerd, wordt uw zoekservice geïmplementeerd op vertrouwelijke VM's (DCasv5 of DCesv5) in plaats van op standaard-VM's. Dit rekentype kost ook een toeslag van 10% voor factureerbare lagen. Zie de pagina met prijzen voor meer informatie.

Voor dagelijks gebruik is confidential computing niet nodig. We raden dit rekentype alleen aan voor strenge wettelijke, nalevings- of beveiligingsvereisten. Zie Gebruiksvoorbeelden voor Confidential Computing voor meer informatie.

Het rekentype is vast voor de levensduur van uw zoekservice. Als u confidential computing permanent wilt configureren, stelt u de computeType eigenschap confidential in op een nieuwe service.

### 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"
        }
    }

Het afdwingen van een klant-beheerd sleutelbeleid

Als u door de klant beheerde versleuteling gebruikt, kunt u 'encryptionWithCMK' inschakelen met 'afdwingen' ingesteld op 'Ingeschakeld' als u wilt dat de zoekservice de nalevingsstatus rapporteert.

Wanneer u dit beleid inschakelt, mislukken ALLE REST-aanroepen die objecten maken die gevoelige gegevens bevatten, zoals de verbindingsreeks in een gegevensbron, als er geen versleutelingssleutel wordt opgegeven: "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"
            }
        }
    }

Workloads uitschakelen die gegevens naar externe resources pushen

Azure AI Zoeken schrijft naar externe gegevensbronnen bij het bijwerken van een kennisarchief, het opslaan van de status van foutopsporingssessies of het cachen van verrijkingen. In het volgende voorbeeld worden deze workloads uitgeschakeld op serviceniveau.

### 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"
        }
    }

Een zoekservice verwijderen

### 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}}

Api-sleutels voor beheerders weergeven

### 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}}

Beheerders-API-sleutels opnieuw genereren

U kunt slechts één beheer-API-sleutel tegelijk opnieuw genereren.

### 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}}

Query-API-sleutels maken

### 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}}

Privé-eindpuntverbindingen vermelden

### 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}}

Zoekbewerkingen weergeven

### 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}}

Volgende stappen

Nadat een zoekservice is geconfigureerd, zijn de volgende stappen het maken van een index of query van een index met behulp van de Azure-portal, REST API's of een Azure SDK.

Feedback

Is deze pagina nuttig?

Laatst bijgewerkt om 2026-05-12