Verwalten des Azure KI-Suchdienstes mit REST-APIs

• Portal
• PowerShell
• Azure-Befehlszeilenschnittstelle
• REST-API

In diesem Artikel erfahren Sie, wie Sie einen Azure KI-Suchdienst mithilfe der Management REST-APIs erstellen und konfigurieren. Nur mit der REST-APIs-Verwaltung wird garantiert, dass frühzeitiger Zugriff auf Vorschaufunktionen bereitgestellt werden.

Die Management-REST-API ist in stabilen und Vorschauversionen verfügbar. Stellen Sie sicher, dass Sie eine Vorschau-API-Version festlegen, wenn Sie auf Vorschaufeatures zugreifen.

• Erstellen oder Aktualisieren eines Dienstes
• Aktivieren der rollenbasierten Zugriffssteuerung von Azure für die Datenebene
• Erzwingen einer kundenseitig verwalteten Schlüsselrichtlinie
• Deaktivieren der semantischen Priorisierung
• Deaktivieren von Arbeitsauslastungen, die Daten an externe Ressourcen pushen
• Erstellen eines Abfrageschlüssels
• Neu generieren eines Administratorschlüssels
• Listet Verbindungen mit privaten Endpunkten
• Listet Suchvorgänge
• Löschen eines Suchdiensts

Die ganze REST-APIs-Verwaltung weist Beispiele auf. Wenn eine Aufgabe in diesem Artikel nicht behandelt wird, lesen Sie stattdessen die API-Referenz.

Voraussetzungen

• Azure-Abonnement – kostenloses Abonnement erstellen.

• Visual Studio Code mit einem REST-Client.

• Azure CLI verwendet, um ein Zugriffstoken abzurufen. Sie müssen ein Besitzer oder Administrator in Ihrem Azure-Abonnement sein.

Abrufen eines Zugriffstokens

Management REST-API-Aufrufe werden über Microsoft Entra ID authentifiziert. Sie müssen ein Zugriffstoken für die Anforderung sowie Berechtigungen zum Erstellen und Konfigurieren einer Ressource bereitstellen.

Sie können die Azure CLI oder Azure PowerShell verwenden, um ein Zugriffstokenzu erstellen.

1. Öffnen Sie eine Befehlsshell für Azure CLI.

2. Melden Sie sich bei Ihrem Azure-Abonnement an.

   az login
   

3. Abrufen Ihrer Mandanten-ID und Abonnement-ID Wenn Sie über mehrere Mandanten oder Abonnements verfügen, stellen Sie sicher, dass Sie die richtige verwenden.

   az account show
   

4. Rufe ein Zugriffstoken ab.

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

Einrichten von Visual Studio Code

Wenn Sie noch keine Erfahrung mit dem REST-Client für Visual Studio Code besitzen, finden Sie in diesem Abschnitt Informationen zum Setup, mit denen Sie die Aufgaben in dieser Anleitung ausführen können.

1. Starten Sie Visual Studio Code, und wählen Sie die Kachel Erweiterungen aus.

2. Suchen Sie nach dem REST-Client, und wählen Sie Installieren aus.

   

3. Öffnen oder erstellen Sie eine neue Datei mit der Dateierweiterung .rest oder .http.

4. Stellen Sie Variablen für die Werte bereit, die Sie im vorherigen Schritt abgerufen haben.

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

5. Überprüfen Sie, ob die Sitzung betriebsbereit ist, indem Sie Suchdienste in Ihrem Abonnement auflisten.

    ### 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. Klicken Sie auf Anforderung senden. Im angrenzenden Bereich sollte eine Antwort angezeigt werden. Wenn Sie über vorhandene Suchdienste verfügen, werden sie aufgeführt. Andernfalls ist die Liste leer. Solange jedoch der HTTP-Code „200 OK“ lautet, können Sie mit den nächsten Schritten fortfahren.

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

Erstellen oder Aktualisieren eines Diensts

Erstellt oder aktualisiert einen Suchdienst unter dem aktuellen Abonnement. In diesem Beispiel werden Variablen für den Namen und die Region des Suchdiensts verwendet, die noch nicht definiert wurden. Geben Sie entweder die Namen direkt an, oder fügen Sie der Sammlung neue Variablen hinzu.

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

Erstellen eines S3HD-Diensts

Um einen S3HD-Dienst zu erstellen, verwenden Sie eine Kombination aus den Eigenschaften sku und hostingMode. Setzen Sie sku auf standard3 und „hostingMode“ auf 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"
        }
    }

Konfigurieren der rollenbasierten Zugriffssteuerung (Role Based Access Control, RBAC) für die Datenebene

Gilt für: Mitwirkender an Suchindexdaten, Suchindexdatenleser, Suchdienstmitwirkender

In diesem Schritt konfigurieren Sie Ihren Dienst so, dass er einen Autorisierungsheader bei Datenanforderungen erkennt, die ein OAuth2-Token für den Zugriff enthalten.

Wenn Sie die rollenbasierte Zugriffssteuerung für Datenebenenvorgänge verwenden möchten, legen Sie diese authOptions fest, aadOrApiKey und senden Sie die Anforderung.

Um die rollenbasierte Zugriffssteuerung ausschließlich zu verwenden, deaktivieren Sie die API-Schlüsselauthentifizierung , indem Sie eine zweite Anforderung ausführen, diesmal disableLocalAuth auf true stellen.

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

Erzwingen einer kundenseitig verwalteten Schlüsselrichtlinie

Wenn Sie die vom Kunden verwaltete Verschlüsselung verwenden, können Sie „encryptionWithCMK" mit „Erzwingung" aktivieren, die auf „Aktiviert" festgelegt ist, wenn der Suchdienst den Konformitätsstatus melden soll.

Wenn Sie diese Richtlinie aktivieren, werden REST-Aufrufe, die Objekte mit vertraulichen Daten erstellen, z. B. die Verbindungszeichenfolge in einer Datenquelle fehlschlagen, wenn kein Verschlüsselungsschlüssel bereitgestellt wird: "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": "Disabled",
            "encryptionComplianceStatus": "Compliant"
            },
        }
    }

Deaktivieren der semantischen Priorisierung

Obwohl standardmäßig die semantische Priorisierung nicht aktiviert ist, können Sie die Funktion auf Dienstebene sperren.

### disable semantic ranking
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"
        }
    }

(Vorschau) Deaktivieren von Arbeitsauslastungen, die Daten an externe Ressourcen pushen

Azure KI-Suche schreibt in externe Datenquellen beim Aktualisieren eines Wissensspeichers, beim Speichern des Debugsitzungszustands oder beim Zwischenspeichern von Anreicherungen. Im folgenden Beispiel werden diese Arbeitsauslastungen auf Dienstebene deaktiviert.

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

Löschen eines Suchdiensts

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

Auflisten von Administrator-API-Schlüsseln

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

Erneutes Generieren von Administrator-API-Schlüsseln

Sie können jeweils nur einen Administrator-API-Schlüssel neu generieren.

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

Erstellen von Abfrage-API-Schlüsseln

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

Listet Verbindungen mit privaten Endpunkten auf.

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

Listet Suchvorgänge

### 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ächste Schritte

Nach der Konfiguration eines Suchdiensts müssen Sie einen Index erstellen oder einen Index abfragen mithilfe des Portals, REST-APIs oder des Azure SDK abfragen.

• Erstellen eines Azure KI Suchindex im Azure-Portal
• Einrichten eines Indexers zum Laden von Daten anderer Dienste
• Abfragen eines Azure KI Suchindex mit dem Suchexplorer im Azure-Portal
• Verwenden von Azure KI Suche in .NET