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

• Portal
• PowerShell
• Azure-CLI
• REST API

In dit artikel leert u hoe u een Azure AI-Search-service maakt en configureert met behulp van de REST API's voor beheer. 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
• Op rollen gebaseerd toegangsbeheer van Azure inschakelen voor het gegevensvlak
• Een door de klant beheerd sleutelbeleid afdwingen
• Semantische rangschikking uitschakelen
• 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 .

Vereisten

• Een Azure-abonnement: maak er gratis een.

• Visual Studio Code met een REST-client.

• Azure CLI heeft een toegangstoken opgehaald. U moet eigenaar of beheerder zijn in uw Azure-abonnement.

Een toegangstoken opvragen

REST API-aanroepen voor beheer worden geverifieerd via Microsoft Entra-id. U moet een toegangstoken opgeven voor de aanvraag, samen met machtigingen voor het maken en configureren van een resource.

U kunt de Azure CLI of Azure PowerShell gebruiken om een toegangstoken te maken.

1. Open een opdrachtshell voor Azure CLI.

2. Meld u aan bij uw Azure-abonnement.

   az login
   

3. Haal de tenant-id en abonnements-id op. Als u meerdere tenants of abonnementen hebt, moet u ervoor zorgen dat u de juiste tenant gebruikt.

   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 deze quickstart kunt voltooien.

1. Start Visual Studio Code en selecteer de tegel Extensies .

2. Zoek de REST-client en selecteer Installeren.

   

3. Open of maak een nieuw bestand met de naam een .rest of .http bestandsextensie.

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

   @tenantId = PASTE-YOUR-TENANT-ID-HERE
   @subscriptionId = PASTE-YOUR-SUBSCRIPTION-ID-HERE
   @token = PASTE-YOUR-TOKEN-HERE
   

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

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

6. Selecteer Verzoek 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

Hiermee maakt of werkt u een zoekservice 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 = 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"
        }
      }

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.

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

Op rollen gebaseerde toegang configureren voor het gegevensvlak

Van toepassing op: Inzender voor zoekindexgegevens, Zoekindexgegevenslezer, Inzender voor zoekservice

In deze stap configureert u 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 authOptions aadOrApiKey en verzendt u de aanvraag.

Als u uitsluitend op rollen gebaseerd toegangsbeheer wilt gebruiken, schakelt u API-sleutelverificatie uit door een tweede aanvraag te volgen. Deze keer wordt deze instelling ingesteld disableLocalAuth op waar.

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

Een door de klant beheerd sleutelbeleid afdwingen

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 voor het maken van objecten 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."

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

Semantische rangschikking uitschakelen

Hoewel semantische rangschikking niet standaard is ingeschakeld , kunt u de functie vergrendelen op serviceniveau voor meer zekerheid.

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

Workloads uitschakelen die gegevens naar externe resources pushen

Azure AI Search schrijft naar externe gegevensbronnen bij het bijwerken van een kennisarchief, het opslaan van foutopsporingssessiestatus of het opslaan van verrijkingen in de cache. In het volgende voorbeeld worden deze workloads uitgeschakeld op serviceniveau.

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

Een zoekservice verwijderen

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

Api-sleutels voor beheerders weergeven

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

API-beheersleutels opnieuw genereren

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

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

Query-API-sleutels maken

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

Privé-eindpuntverbindingen vermelden

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

Zoekbewerkingen weergeven

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

Volgende stappen

Nadat een zoekservice is geconfigureerd, moeten volgende stappen een index maken of een query uitvoeren op een index met behulp van Azure Portal, REST API's of een Azure SDK.

• Een Azure AI Search-index maken in Azure Portal
• Een indexeerfunctie instellen om gegevens van andere services te laden
• Een query uitvoeren op een Azure AI Search-index met behulp van Search Explorer in Azure Portal
• Azure AI Search gebruiken in .NET