Hantera din Azure AI-tjänsten Search med REST-API:er
I den här artikeln får du lära dig hur du skapar och konfigurerar en Azure AI-tjänsten Search med hjälp av REST API:er för hantering. 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.
- Skapa eller uppdatera en tjänst
- Aktivera rollbaserad åtkomstkontroll i Azure för dataplan
- Framtvinga en princip för kundhanterad nyckel
- Inaktivera semantisk ranker
- Inaktivera arbetsbelastningar som skickar data till externa resurser
- Skapa en frågenyckel
- Återskapa en administratörsnyckel
- Lista privata slutpunktsanslutningar
- Lista sökåtgärder
- Ta bort en söktjänst
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.
En Azure-prenumeration – Skapa en kostnadsfritt.
Visual Studio Code med en REST-klient.
Azure CLI används för att hämta en åtkomsttoken. 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, tillsammans med behörigheter för att skapa och konfigurera en resurs.
Du kan använda Azure CLI eller Azure PowerShell för att skapa en åtkomsttoken.
Öppna ett kommandogränssnitt för Azure CLI.
Logga in på din Azure-prenumeration.
az login
Hämta klientorganisations-ID och prenumerations-ID. Om du har flera klientorganisationer eller prenumerationer kontrollerar du att du använder rätt klientorganisation.
az account show
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.
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 snabbstarten.
Starta Visual Studio Code och välj panelen Tillägg .
Sök efter REST-klienten och välj Installera.
Öppna eller skapa en ny fil med namnet med antingen ett filnamnstillägg eller
.http
filnamnstillägg.rest
.Ange variabler för de värden som du hämtade i föregående steg.
@tenantId = PASTE-YOUR-TENANT-ID-HERE @subscriptionId = PASTE-YOUR-SUBSCRIPTION-ID-HERE @token = PASTE-YOUR-TOKEN-HERE
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/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01 Content-type: application/json Authorization: Bearer {{token}}
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": [ . . . ] }
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 = 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"
}
}
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
.
@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"
}
}
Gäller för: Search Index Data Contributor, Search Index Data Reader, Search Service Contributor
I det här steget konfigurerar du söktjänsten för att identifiera ett auktoriseringshuvud på 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 tidsinställningen disableLocalAuth
till 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"
}
}
}
}
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 anslutningssträng 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."
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"
}
}
}
Även om semantisk ranker inte är aktiverat som standard kan du låsa funktionen på tjänstnivå för att få större säkerhet om att den inte kan användas.
### 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"
}
}
Azure AI Search skriver till externa datakällor när du uppdaterar ett kunskapslager, sparar sessionstillstånd för felsökning eller cachelagring av berikningar. I följande exempel inaktiveras dessa arbetsbelastningar på tjänstnivå.
### 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"
}
}
### 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}}
### 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}}
Du kan bara återskapa en administratörs-API-nyckel i taget.
### 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}}
### 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}}
### 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}}
### 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}}
När en söktjänst har konfigurerats är nästa steg att skapa ett index eller fråga ett index med hjälp av Azure Portal, REST API:er eller en Azure SDK.