Správa služby Azure AI Search pomocí rozhraní REST API

Naučte se vytvářet a konfigurovat službu Azure AI Search pomocí rozhraní REST API pro správu. Zaručují se pouze rozhraní REST API pro správu, která poskytují přednostní přístup k funkcím ve verzi Preview.

Rozhraní REST API pro správu je k dispozici ve stabilních a preview verzích. Pokud přistupujete k funkcím preview, nezapomeňte nastavit verzi rozhraní API ve verzi Preview.

• Vytvoření nebo aktualizace služby
• Vylepšení služby
• Změna cenových úrovní
• Povolení řízení přístupu na základě role v Azure pro rovinu dat
• Vynucení zásad klíče spravovaného zákazníkem
• Zakázání sémantického rankeru
• Zakázání úloh, které odsílaly data do externích prostředků
• Vytvoření klíče dotazu
• Opětovné vygenerujte klíč správce.
• Výpis připojení privátních koncových bodů
• Vyhledávací operace v seznamech
• Odstranění vyhledávací služby

Všechna rozhraní REST API pro správu mají příklady. Pokud není v tomto článku popsaný úkol, přečtěte si místo toho referenční informace k rozhraní API.

Požadavky

• Účet Azure s aktivním předplatným. Vytvoření účtu zdarma

• Visual Studio Code s klientem REST

• Azure CLI pro získání přístupového tokenu, jak je popsáno v následujících krocích. Ve svém předplatném Azure musíte být vlastníkem nebo správcem.

  Volání rozhraní REST API pro správu se ověřují prostřednictvím ID Microsoft Entra. Musíte poskytnout přístupový token k žádosti a oprávnění k vytvoření a konfiguraci prostředku. Kromě Azure CLI můžete k vytvoření přístupového tokenu použít Azure PowerShell.

  1. Otevřete příkazové prostředí pro Azure CLI.

  2. Přihlaste se ke svému předplatnému Azure. Pokud máte více tenantů nebo předplatných, ujistěte se, že jste vybrali tu správnou.

     az login
     

  3. Získejte ID tenanta a ID předplatného.

     az account show
     

  4. Získejte přístupový token.

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

     Měli byste mít ID tenanta, ID předplatného a nosný token. Tyto hodnoty vložíte do souboru .rest nebo .http, který vytvoříte v dalším kroku.

Nastavit nástroj Visual Studio Code

Pokud nejste obeznámeni s klientem REST pro Visual Studio Code, tato část obsahuje nastavení, abyste mohli dokončit úlohy v tomto článku.

1. Spusťte Visual Studio Code a vyberte panel Rozšíření.

2. Vyhledejte klienta REST a vyberte Nainstalovat.

   

3. Otevřete nebo vytvořte nový soubor s názvem nebo .rest příponou .http souboru.

4. Zadejte proměnné pro hodnoty, které jste získali v předchozím kroku.

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

5. Ověřte, že relace funguje, výpisem vyhledávacích služeb ve vašem předplatném.

    ### 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. Vyberte Odeslat žádost. V sousedním podokně by se měla zobrazit odpověď. Pokud máte existující vyhledávací služby, jsou uvedené. V opačném případě je seznam prázdný, ale pokud je kód HTTP 200 OK, jste připraveni na další kroky.

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

Vytvoření nebo aktualizace služby

Vytvoří nebo aktualizuje vyhledávací službu v rámci aktuálního předplatného. Tento příklad používá proměnné pro název a oblast vyhledávací služby, které ještě nebyly definovány. Zadejte názvy přímo nebo přidejte do kolekce nové proměnné.

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

Vylepšit službu

Některé funkce Azure AI Search jsou dostupné jenom pro nové služby. Aby se předešlo vytváření služby znovu a přinesly tyto funkce do stávající služby, můžete službu upgradovat.

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

Změna cenových úrovní

Pokud potřebujete větší kapacitu, můžete přejít na vyšší cenovou úroveň. V současné době se můžete pohybovat pouze mezi úrovněmi Basic a Standard (S1, S2 a S3). sku Pomocí vlastnosti zadejte vyšší úroveň.

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

Vytvoření služby S3HD

Chcete-li vytvořit službu S3HD , použijte kombinaci sku a hostingMode vlastnosti. Nastavte sku na standard3 a "hostingMode" na 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"
        }
    }

Konfigurace přístupu na základě role pro rovinu dat

Platí pro: Přispěvatel dat Indexu Vyhledávání, Čtenář dat Indexu Vyhledávání, Přispěvatel Vyhledávací Služby

Nakonfigurujte vyhledávací službu tak, aby rozpoznala autorizační hlavičku u žádostí o data, která poskytují přístupový token OAuth2.

Pokud chcete pro operace roviny dat použít řízení přístupu na základě role, nastavte authOptionsaadOrApiKey a odešlete požadavek.

Pro úplné používání řízení přístupu na základě role, vypněte ověřování klíče API tím, že zašlete druhý požadavek, ve kterém nastavíte disableLocalAuth na hodnotu 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"
                }
            }
        }
    }

Uplatnění politiky klíče spravovaného zákazníkem

Pokud používáte šifrování spravované zákazníkem, můžete povolit šifrováníWithCMK s vynucením nastaveným na Povoleno, pokud chcete, aby vyhledávací služba hlásila stav dodržování předpisů.

Když tuto zásadu povolíte, všechna volání REST, která vytvářejí objekty obsahující citlivá data, jako je připojovací řetězec ve zdroji dat, selžou, pokud není zadaný šifrovací klíč:"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"
            }
        }
    }

Zakázání sémantického rankeru

Sémantický ranker je ve výchozím nastavení povolený v bezplatném plánu, který umožňuje bezplatně až 1 000 žádostí za měsíc. Tuto funkci můžete uzamknout na úrovni služby, abyste zabránili použití.

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

Zakázání úloh, které odsílaly data do externích prostředků

Azure AI Search zapisuje do externích zdrojů dat při aktualizaci úložiště znalostí, ukládání stavu relace ladění nebo ukládání do mezipaměti. Následující příklad tyto úlohy zakáže na úrovni služby.

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

Odstranění vyhledávací služby

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

Výpis klíčů rozhraní API pro správu

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

Opětovné vygenerování klíčů rozhraní API pro správu

Současně můžete znovu vygenerovat pouze jeden klíč rozhraní API pro správu.

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

Vytvoření klíčů rozhraní API pro dotazy

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

Seznam připojení privátních koncových bodů

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

Operace prohledávání seznamů

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

Další kroky

Jakmile je vyhledávací služba nakonfigurovaná, mezi další kroky patří vytvoření indexu nebo dotazování indexu pomocí webu Azure Portal, rozhraní REST API nebo sady Azure SDK.

• Vytvoření indexu Azure AI Search na webu Azure Portal
• Nastavení indexeru pro načtení dat z jiných služeb
• Dotazování indexu Azure AI Search pomocí Průzkumníka služby Search na webu Azure Portal
• Jak používat Azure AI Search v .NET