Zarządzanie usługą Azure AI Search przy użyciu interfejsów API REST

Dowiedz się, jak utworzyć i skonfigurować usługę Azure AI Search przy użyciu interfejsów API REST zarządzania. Tylko interfejsy API REST zarządzania mają gwarancję wczesnego dostępu do funkcji zapoznawczych.

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
• Uaktualnianie usługi
• Zmienianie warstw cenowych
• Włączanie kontroli dostępu opartej na rolach platformy Azure dla płaszczyzny danych
• Wymuszanie polityki klucza zarządzanego przez klienta
• Wyłącz klasyfikator semantyczny
• Wyłącz obciążenia, 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
• Lista operacji wyszukiwania
• Usuwanie usługi 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

• Konto Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.

• Program Visual Studio Code z klientem REST.

• Interfejs wiersza polecenia platformy Azure umożliwiający uzyskanie tokenu dostępu zgodnie z opisem w poniższych krokach. Musisz być właścicielem lub administratorem w ramach subskrypcji platformy Azure.

  Wywołania interfejsu API REST zarządzania są uwierzytelniane za pośrednictwem identyfikatora Entra firmy Microsoft. Musisz podać token dostępu na żądanie i uprawnienia do tworzenia i konfigurowania zasobu. Oprócz interfejsu wiersza polecenia platformy Azure możesz użyć programu Azure PowerShell do utworzenia tokenu dostępu.

  1. Otwórz powłokę poleceń dla CLI platformy Azure.

  2. Zaloguj się do subskrypcji platformy Azure. Jeśli masz wiele dzierżaw lub subskrypcji, upewnij się, że wybierasz odpowiednią.

     az login
     

  3. Pobierz identyfikator dzierżawy i identyfikator subskrypcji.

     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 dostępu. Wkleisz te wartości do pliku .rest lub .http, który utworzysz 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 artykule.

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 rozszerzeniem .rest 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"
        }
      }

Uaktualnianie usługi

Niektóre funkcje usługi Azure AI Search są dostępne tylko dla nowych usług. Aby uniknąć rekreacji usług i przenieść te możliwości do istniejącej usługi, możesz uaktualnić usługę.

### Upgrade a search service
@resource-group = my-rg
@search-service-name = my-search
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/upgrade?api-version=2025-02-01-preview  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Zmiana warstw cenowych

Jeśli potrzebujesz większej pojemności, możesz przełączyć się na wyższą warstwę cenową. Obecnie można przechodzić w górę tylko między warstwami Podstawowa i Standardowa (S1, S2 i S3). sku Użyj właściwości , aby określić wyższą warstwę.

### Change pricing tiers
@resource-group = my-rg
@search-service-name = my-search
PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2025-02-01-preview HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "sku": {
            "name": "standard2"
        }
    }

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

Skonfiguruj usługę wyszukiwania, aby rozpoznać nagłówek autoryzacji dla żądań danych, które zapewniają 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 na 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 polityki 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

Ranga semantyczna jest domyślnie włączona w ramach bezpłatnego planu, który umożliwia maksymalnie 1000 żądań miesięcznie bez opłat. Możesz zablokować tę funkcję na poziomie usługi, aby zapobiec użyciu.

### 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, zapisu stanu sesji debugowania lub przechowywania w pamięci podręcznej wzbogaconych danych. 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}}

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

Wylistuj połączenia 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}}

Lista 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ń dotyczących 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