Hantera din Azure AI-sökning-tjänst med hjälp av REST-API:er

Lär dig hur du skapar och konfigurerar en Azure AI-sökning-tjänst med hjälp av Management REST-API:erna. Endast REST-API:er för hantering garanteras att ge tidig åtkomst till förhandsversionsfunktioner.

REST-API:et för hantering är tillgängligt i stabila versioner och förhandsversioner. Se till att ange en förhandsversion av API:et om du har åtkomst till förhandsgranskningsfunktioner.

Alla REST-API:er för hantering har exempel. Om en uppgift inte beskrivs i den här artikeln kan du läsa API-referensen i stället.

Förutsättningar

• Ett Azure konto med en aktiv prenumeration. Skapa ett konto kostnadsfritt.

• Visual Studio Code med en REST-klient.

• Azure CLI för att hämta en åtkomsttoken enligt beskrivningen i följande steg. Du måste vara ägare eller administratör i din Azure-prenumeration.

  REST API-anrop för hantering autentiseras via Microsoft Entra ID. Du måste ange en åtkomsttoken för begäran och behörigheter för att skapa och konfigurera en resurs. Förutom Azure CLI kan du använda Azure PowerShell för att skapa en åtkomsttoken.

  1. Öppna ett kommandogränssnitt för Azure CLI.

  2. Logga in på din Azure-prenumeration. Om du har flera klientorganisationer eller prenumerationer, kontrollera att du väljer rätt.

     az login
     

  3. Hämta hyresgästs-ID och prenumerations-ID.

     az account show
     

  4. Hämta en åtkomsttoken.

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

     Du bör ha ett klient-ID, prenumerations-ID och ägartoken. Du klistrar in dessa värden i .rest filen eller .http som du skapar i nästa steg.

Konfigurera Visual Studio Code

Om du inte är bekant med REST-klienten för Visual Studio Code innehåller det här avsnittet konfiguration så att du kan slutföra uppgifterna i den här artikeln.

1. Starta Visual Studio Code och välj panelen Extensions.

2. Sök efter REST-klienten och välj Installera.

   

3. Öppna eller skapa en ny fil med antingen .rest eller .http som filändelse.

4. Ange variabler för de värden som du hämtade i föregående steg.

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

5. Kontrollera att sessionen fungerar genom att visa en lista över söktjänster i din prenumeration.

    ### 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. Välj Skicka begäran. Ett svar bör visas i ett intilliggande fönster. Om du har befintliga söktjänster visas de. Annars är listan tom, men så länge HTTP-koden är 200 OK är du redo för nästa steg.

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

Skapa eller uppdatera en tjänst

Skapar eller uppdaterar en söktjänst under den aktuella prenumerationen. I det här exemplet används variabler för söktjänstens namn och region, som ännu inte har definierats. Ange antingen namnen direkt eller lägg till nya variabler i samlingen.

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

Skapa en tjänst med en automatiskt genererad DNS-etikett

En automatiskt genererad DNS-etikett lägger till ett genererat suffix i Azure AI-sökning-tjänstens slutpunktsvärdnamn. Azure AI-sökning genererar etiketten automatiskt. Du väljer bara dess återanvändningsomfång. Omfånget avgör om etiketten är unik eller återanvänds för samma tjänstnamn i din prenumeration eller Microsoft Entra-klientorganisation.

Konfigurera den här funktionen via 2026-09-01-preview Management REST API när du skapar en tjänst. Välj etikettens återanvändningsomfång när du skapar eftersom du inte kan ändra omfånget efteråt.

Om du utelämnar autoGeneratedDomainNameLabelScope eller anger det till null använder tjänsten standardformatet för endpointar utan en automatiskt genererad etikett.

Använd förutsättningarna och REST-klientvariablerna ovan. Ange resource-group som en befintlig resursgrupp, search-service som ett nytt tjänstnamn och region som en tillgänglig region för din prenumeration.

Följande begäran skapar en Basic-tjänst med en unik etikett:

@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-NEW-SERVICE-NAME-HERE
@region = PUT-YOUR-REGION-HERE

### Create a service with an auto-generated DNS label
PUT https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2026-09-01-preview HTTP/1.1
Content-Type: application/json
Authorization: ******

{
  "location": "{{region}}",
  "sku": {
    "name": "basic"
  },
  "properties": {
    "replicaCount": 1,
    "partitionCount": 1,
    "autoGeneratedDomainNameLabelScope": "NoReuse"
  }
}

När etableringen har slutförts innehåller svaret den genererade endpointen och det valda scopet:

{
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/my-resource-group/providers/Microsoft.Search/searchServices/mysearchservice",
  "name": "mysearchservice",
  "type": "Microsoft.Search/searchServices",
  "location": "westus",
  "sku": {
    "name": "basic"
  },
  "properties": {
    "endpoint": "https://mysearchservice-12345678abcdefgh.sg.search.windows.net/",
    "provisioningState": "Succeeded",
    "autoGeneratedDomainNameLabelScope": "NoReuse"
  }
}

Referens: Söktjänst – skapa eller uppdatera.

Läs properties.endpoint från tjänstsvaret innan du ansluter till API:erna för dataplanet. En endpoint med en automatiskt genererad etikett har följande format: https://<service-name>-<label>.sg.search.windows.net/. Tjänstens name och Azure Resource Manager resursen id ändras inte.

Välj något av följande värden:

Referens: egenskaper för söktjänsten.

Uppgradera en tjänst

Vissa Azure AI-sökning funktioner är bara tillgängliga för nya tjänster. För att undvika att tjänsten återskapas och föra dessa funktioner till en befintlig tjänst kanske du kan uppgradera tjänsten.

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

Ändra prisnivåer

Om du behöver mer eller mindre kapacitet kan du byta till en annan prisnivå. För närvarande kan du bara växla mellan nivåerna Basic och Standard (S1, S2 och S3). Använd egenskapen sku för att ange den nya nivån.

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

Skapa en S3HD-tjänst

Om du vill skapa en S3HD-tjänst använder du en kombination av sku och hostingMode egenskaper. Ange sku till standard3 och "hostingMode" till 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"
        }
    }

Konfigurera rollbaserad åtkomst för dataplan

Gäller för: Search Index Data Contributor, Search Index Data Reader, Search Service Contributor

Konfigurera söktjänsten för att identifiera ett auktoriseringshuvud för databegäranden som tillhandahåller en OAuth2-åtkomsttoken.

Om du vill använda rollbaserad åtkomstkontroll för dataplansåtgärder anger du authOptions till aadOrApiKey och skickar sedan begäran.

Om du vill använda rollbaserad åtkomstkontroll exklusivt inaktiverar du API-nyckelautentisering genom att följa upp med en andra begäran, den här gången ställ in disableLocalAuth till 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"
                }
            }
        }
    }

Konfigurera konfidentiell databehandling

Konfidentiell databehandling är en valfri beräkningstyp för skydd mot användning av data. När den konfigureras distribueras söktjänsten på konfidentiella virtuella datorer (DCasv5 eller DCesv5) i stället för vanliga virtuella datorer. Den här beräkningstypen medför också en tilläggsavgift på 10% för fakturerbara nivåer. Mer information finns på prissidan.

För daglig användning är konfidentiell databehandling inte nödvändigt. Vi rekommenderar endast den här beräkningstypen för stränga regel-, efterlevnads- eller säkerhetskrav. Mer information finns i Användningsfall för konfidentiell databehandling.

Beräkningstypen är fast under söktjänstens livslängd. Om du vill konfigurera konfidentiell databehandling permanent ställer du in egenskapen computeTypeconfidential på på en ny tjänst.

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

Tillämpa en policy för kundhanterad nyckel

Om du använder kundhanterad kryptering kan du aktivera "encryptionWithCMK" med "enforcement" inställt på "Enabled" om du vill att söktjänsten ska rapportera dess efterlevnadsstatus.

När du aktiverar den här principen misslyckas alla REST-anrop som skapar objekt som innehåller känsliga data, till exempel reťazec pripojenia i en datakälla, om en krypteringsnyckel inte tillhandahålls: "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"
            }
        }
    }

Inaktivera arbetsbelastningar som skickar data till externa resurser

Azure AI-sökning skriver till externa datakällor vid uppdatering av en kunskapslagring, sparar tillstånd för felsökningssessioner eller cachelagring av berikningar. I följande exempel inaktiveras dessa arbetsbelastningar på tjänstnivå.

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

Ta bort en söktjänst

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

Lista api-nycklar för administratör

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

Återskapa administratörs-API-nycklar

Du kan bara återskapa en administratörs-API-nyckel i taget.

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

Skapa fråge-API-nycklar

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

Lista privata slutpunktsanslutningar

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

Lista sökåtgärder

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

Nästa steg

När en söktjänst har konfigurerats inkluderar nästa steg skapa ett index eller querying ett index med hjälp av Azure-portalen, REST API:er eller en Azure SDKs.

• Skapa ett Azure AI-sökning index i Azure-portalen
• Konfigurera en indexerare för att läsa in data från andra tjänster
• Fråga ett Azure AI-sökning-index med hjälp av Search Explorer i Azure-portalen
• Så här använder du Azure AI-sökning i .NET