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

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

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.

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 bezpłatne konto.

• Visual Studio Code z klientem REST.

• Azure CLI aby uzyskać token dostępu, zgodnie z opisem w poniższych krokach. Musisz być właścicielem lub administratorem w ramach subskrypcji Azure.

  Wywołania interfejsu API REST zarządzania są uwierzytelniane za pośrednictwem Microsoft Entra ID. Musisz podać token dostępu na żądanie i uprawnienia do tworzenia i konfigurowania zasobu. Oprócz Azure CLI można użyć Azure PowerShell aby utworzyć token dostępu.

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

  2. Zaloguj się do subskrypcji Azure. Jeśli masz wielu dzierżawców 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 uwierzytelniający. Wklej te wartości do pliku .rest lub pliku .http, który utworzysz w następnym kroku.

Skonfiguruj Visual Studio Code

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

1. Uruchom Visual Studio Code i wybierz kafelek Extensions.

2. Wyszukaj klienta REST i wybierz pozycję Zainstaluj.

   

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

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

   @tenant-id = PUT-YOUR-TENANT-ID-HERE
   @subscription-id = PUT-YOUR-SUBSCRIPTION-ID-HERE
   @token = PUT-YOUR-TOKEN-HERE
   

5. Aby sprawdzić, czy sesja działa, wyświetl listę usług wyszukiwania w subskrypcji.

    ### List search services
    GET https://management.azure.com/subscriptions/{{subscription-id}}/providers/Microsoft.Search/searchServices?api-version=2025-05-01  HTTP/1.1
         Content-type: application/json
         Authorization: Bearer {{token}}
   

6. Wybierz pozycję Wyślij żądanie. 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 = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PUT https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-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 Wyszukiwanie AI platformy Azure możliwości są dostępne tylko dla nowych usług. Aby uniknąć ponownego tworzenia usługi i przenieść te możliwości do istniejącej usługi, możliwe jest uaktualnienie usługi.

### Upgrade a search service
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/upgrade?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Zmienianie warstw cenowych

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

### Change pricing tiers
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  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 właściwości sku i hostingMode. Ustaw sku na standard3 i "hostingMode" na HighDensity.

### Create an S3HD service
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PUT https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-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 autoryzacja dla żądań danych, które dostarczają token dostępu OAuth2.

Aby użyć kontroli dostępu opartej na rolach dla operacji płaszczyzny danych, ustaw authOptions na 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 następne żądanie, tym razem ustawiając parametr disableLocalAuth na true.

### Configure role-based access
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "properties": {
            "disableLocalAuth": false,
            "authOptions": {
                "aadOrApiKey": {
                    "aadAuthFailureMode": "http401WithBearerChallenge"
                }
            }
        }
    }

Konfigurowanie poufnego przetwarzania

Poufne przetwarzanie jest opcjonalnym typem obliczeniowym ochrony danych w użyciu. Po skonfigurowaniu usługa wyszukiwania jest wdrażana na poufnych maszynach wirtualnych (DCasv5 lub DCesv5) zamiast standardowych maszyn wirtualnych. Ten typ obliczeniowy wiąże się również z 10% dopłatą za warstwy podlegające opłatom. Aby uzyskać więcej informacji, zobacz stronę cennika.

W przypadku dziennego użycia poufne przetwarzanie nie jest konieczne. Zalecamy tylko ten typ obliczeniowy dla rygorystycznych wymagań prawnych, zgodności lub zabezpieczeń. Aby uzyskać więcej informacji, zobacz Poufne przypadki użycia przetwarzania.

Typ obliczeniowy jest stały dla okresu istnienia usługi wyszukiwania. Aby trwale skonfigurować poufne przetwarzanie, ustaw computeType właściwość na confidential w nowej usłudze.

### Configure confidential computing
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE
PUT https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
    Content-type: application/json
    Authorization: Bearer {{token}}
    {
        "location": "{{region}}",
        "sku": {
            "name": "basic"
        },
        "properties": {
            "computeType": "confidential"
        }
    }

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 klucz szyfrowania nie zostanie podany: "Error creating Data Source: "CannotCreateNonEncryptedResource: The creation of non-encrypted DataSources is not allowed when encryption policy is enforced."

### Enforce a customer-managed key policy
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "encryptionWithCmk": {
                "enforcement": "Enabled"
            }
        }
    }

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

Wyszukiwanie AI platformy Azure zapisuje zewnętrzne źródła danych podczas aktualizowania magazynu wiedzy, zapisywania stanu sesji debugowania lub buforowania wzbogaceń. Poniższy przykład wyłącza te obciążenia na poziomie usługi.

### Disable external access
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "publicNetworkAccess": "Disabled"
        }
    }

Usuwanie usługi wyszukiwania

### Delete a search service
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

DELETE https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Wyświetlanie listy kluczy interfejsu API administratora

### List admin keys
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/listAdminKeys?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Ponowne generowanie kluczy interfejsu API administratora

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

### Regnerate admin keys
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/regenerateAdminKey/primary?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Utwórz klucze interfejsu API zapytań

### Create a query key
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE
@query-key = PUT-YOUR-QUERY-KEY-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/createQueryKey/{query-key}?api-version=2025-05-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
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

GET https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/privateEndpointConnections?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Lista operacji wyszukiwania

### List search operations
GET https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups?api-version=2021-04-01  HTTP/1.1
  Content-type: application/json
  Authorization: Bearer {{token}}

Następne kroki

Po skonfigurowaniu usługi wyszukiwania następne kroki obejmują tworzenie indeksu lub zapytanie indeksu przy użyciu portalu Azure, interfejsów API REST lub Azure SDK.

• Tworzenie indeksu Wyszukiwanie AI platformy Azure w portalu Azure
• Konfigurowanie indeksatora w celu załadowania danych z innych usług
• Zapytaj o indeks Wyszukiwanie AI platformy Azure, korzystając z Eksploratora wyszukiwania w portalu Azure
• Jak używać Wyszukiwanie AI platformy Azure w .NET