Hantera din Azure AI-tjänsten Search med REST-API:er

Artikel
09/25/2024

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.

Förutsättningar

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.

Hämta en åtkomsttoken

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.

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

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

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.

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

Konfigurera rollbaserad åtkomst för dataplan

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

Framtvinga en princip 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 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"
            }
        }
    }

Inaktivera semantisk ranker

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

Inaktivera arbetsbelastningar som skickar data till externa resurser

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

Ta bort en söktjänst

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

Lista api-nycklar för administratör

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

Återskapa API-nycklar för administratörer

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

Skapa fråge-API-nycklar

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

Lista privata slutpunktsanslutningar

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

Lista sökåtgärder

### 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ästa steg

När en söktjänst har konfigurerats inkluderar nästa steg att skapa ett index eller köra frågor mot ett index med hjälp av portalen, REST-API:er eller en Azure SDK.

Dela via