Zarządzanie usługa wyszukiwania usługi Azure AI przy użyciu interfejsów API REST

• Portal
• Program PowerShell
• Interfejs wiersza polecenia platformy Azure
• Interfejs API REST

Z tego artykułu dowiesz się, jak utworzyć i skonfigurować usługa wyszukiwania sztucznej inteligencji platformy Azure przy użyciu interfejsów API REST zarządzania. Tylko interfejsy API REST zarządzania mają gwarancję wczesnego dostępu do funkcji w wersji zapoznawczej.

Interfejs API REST zarządzania jest dostępny w stabilnych wersjach i wersji zapoznawczych. Pamiętaj, aby ustawić wersję interfejsu API w wersji zapoznawczej, jeśli uzyskujesz dostęp do funkcji w wersji zapoznawczej.

• Tworzenie lub aktualizowanie usługi
• Włączanie kontroli dostępu opartej na rolach platformy Azure dla płaszczyzny danych
• Wymuszanie zasad klucza zarządzanego przez klienta
• Wyłączanie klasyfikatora semantycznego
• Wyłączanie obciążeń, które wypychają dane do zasobów zewnętrznych
• Tworzenie klucza zapytania
• Ponowne generowanie klucza administratora
• Wyświetlanie listy połączeń prywatnych punktów końcowych
• Wyświetlanie listy operacji wyszukiwania
• Usuwanie usług wyszukiwania

Wszystkie interfejsy API REST zarządzania mają przykłady. Jeśli zadanie nie zostało omówione w tym artykule, zapoznaj się z dokumentacją interfejsu API.

Wymagania wstępne

• Subskrypcja platformy Azure — utwórz bezpłatnie.

• Program Visual Studio Code z klientem REST.

• Interfejs wiersza polecenia platformy Azure używany do uzyskiwania tokenu dostępu. Musisz być właścicielem lub administratorem w ramach subskrypcji platformy Azure.

Pobranie tokenu dostępu

Wywołania interfejsu API REST zarządzania są uwierzytelniane za pośrednictwem identyfikatora Entra firmy Microsoft. Musisz podać token dostępu w żądaniu wraz z uprawnieniami do tworzenia i konfigurowania zasobu.

Aby utworzyć token dostępu, możesz użyć interfejsu wiersza polecenia platformy Azure lub programu Azure PowerShell.

1. Otwórz powłokę poleceń dla interfejsu wiersza polecenia platformy Azure.

2. Zaloguj się do subskrypcji platformy Azure.

   az login
   

3. Pobierz identyfikator dzierżawy i identyfikator subskrypcji. Jeśli masz wiele dzierżaw lub subskrypcji, upewnij się, że używasz odpowiedniej dzierżawy.

   az account show
   

4. Uzyskiwanie tokenu dostępu.

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

Należy mieć identyfikator dzierżawy, identyfikator subskrypcji i token elementu nośnego. Wklej te wartości do .rest pliku lub .http utworzonego w następnym kroku.

Konfigurowanie programu Visual Studio Code

Jeśli nie znasz klienta REST programu Visual Studio Code, ta sekcja zawiera konfigurację, aby można było wykonać zadania w tym przewodniku Szybki start.

1. Uruchom program Visual Studio Code i wybierz kafelek Rozszerzenia .

2. Wyszukaj klienta REST i wybierz pozycję Zainstaluj.

   

3. Otwórz lub utwórz nowy plik o nazwie z .rest rozszerzeniem lub .http .

4. Podaj zmienne dla wartości pobranych w poprzednim kroku.

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

5. Sprawdź, czy sesja działa, wyświetlając listę usług wyszukiwania w subskrypcji.

    ### 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. Wybierz pozycję Wyślij wniosek. Odpowiedź powinna pojawić się w sąsiednim okienku. Jeśli masz istniejące usługi wyszukiwania, są one wymienione na liście. W przeciwnym razie lista jest pusta, ale o ile kod HTTP to 200 OK, możesz przystąpić do następnych kroków.

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

Tworzenie lub aktualizowanie usługi

Tworzy lub aktualizuje usługę wyszukiwania w ramach bieżącej subskrypcji. W tym przykładzie użyto zmiennych dla nazwy i regionu usługi wyszukiwania, które nie zostały jeszcze zdefiniowane. Podaj nazwy bezpośrednio lub dodaj nowe zmienne do kolekcji.

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

Tworzenie usługi S3HD

Aby utworzyć usługę S3HD , użyj kombinacji sku właściwości i hostingMode . Ustaw sku parametr na standard3 i "hostingMode" na HighDensitywartość .

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

Konfigurowanie dostępu opartego na rolach dla płaszczyzny danych

Dotyczy: Współautor danych indeksu wyszukiwania, Czytelnik danych indeksu wyszukiwania, Współautor usługi wyszukiwania

W tym kroku skonfiguruj usługę wyszukiwania, aby rozpoznała nagłówek autoryzacji dla żądań danych, które udostępniają token dostępu OAuth2.

Aby użyć kontroli dostępu opartej na rolach dla operacji płaszczyzny danych, ustaw authOptions wartość , aadOrApiKey a następnie wyślij żądanie.

Aby używać wyłącznie kontroli dostępu opartej na rolach, wyłącz uwierzytelnianie klucza interfejsu API, wykonując kolejne żądanie, tym razem ustawiając wartość disableLocalAuth 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"
                }
            }
        }
    }

Wymuszanie zasad klucza zarządzanego przez klienta

Jeśli używasz szyfrowania zarządzanego przez klienta, możesz włączyć opcję "encryptionWithCMK" z ustawieniem "enforcement" na wartość "Enabled", jeśli chcesz, aby usługa wyszukiwania zgłosiła stan zgodności.

Po włączeniu tych zasad wszystkie wywołania REST, które tworzą obiekty zawierające poufne dane, takie jak parametry połączenia w źródle danych, zakończą się niepowodzeniem, jeśli nie podano klucza szyfrowania:"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"
            }
        }
    }

Wyłączanie klasyfikatora semantycznego

Mimo że semantyczny ranger nie jest domyślnie włączony , można zablokować funkcję na poziomie usługi, aby zapewnić większą pewność, że nie można jej używać.

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

Wyłączanie obciążeń, które wypychają dane do zasobów zewnętrznych

Usługa Azure AI Search zapisuje dane w zewnętrznych źródłach danych podczas aktualizowania magazynu wiedzy, zapisywania stanu sesji debugowania lub buforowania wzbogacenia. Poniższy przykład wyłącza te obciążenia na poziomie usługi.

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

Usuwanie usługi wyszukiwania

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

Wyświetlanie listy kluczy interfejsu API administratora

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

Ponowne generowanie kluczy administracyjnego interfejsu API

Jednocześnie można wygenerować tylko jeden klucz interfejsu API administratora.

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

Tworzenie kluczy interfejsu API zapytań

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

Wyświetlanie listy połączeń prywatnych punktów końcowych

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

Wyświetlanie listy operacji wyszukiwania

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

Następne kroki

Po skonfigurowaniu usługi wyszukiwania kolejne kroki obejmują tworzenie indeksu lub wykonywanie zapytań względem indeksu przy użyciu witryny Azure Portal, interfejsów API REST lub zestawu Azure SDK.

• Tworzenie indeksu usługi Azure AI Search w witrynie Azure Portal
• Konfigurowanie indeksatora w celu załadowania danych z innych usług
• Wykonywanie zapytań względem indeksu usługi Azure AI Search przy użyciu eksploratora wyszukiwania w witrynie Azure Portal
• Jak używać usługi Azure AI Search na platformie .NET