Správa Search Azure AI pomocí rozhraní REST API

• Azure Portal
• PowerShell
• Azure CLI
• REST API

V tomto článku se dozvíte, jak vytvořit a nakonfigurovat Search Azure AI 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
• 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ů
• Operace hledání seznamu
• Odstranění vyhledávacích služeb

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

• Předplatné Azure – Vytvořte si ho zdarma.

• Visual Studio Code s klientem REST

• Azure CLI slouží k získání přístupového tokenu. Ve svém předplatném Azure musíte být vlastníkem nebo správcem.

Získání přístupového tokenu

Volání rozhraní REST API pro správu se ověřují prostřednictvím ID Microsoft Entra. V požadavku musíte poskytnout přístupový token spolu s oprávněními k vytvoření a konfiguraci prostředku.

K vytvoření přístupového tokenu můžete použít Azure CLI nebo Azure PowerShell.

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

2. Přihlaste se ke svému předplatnému Azure.

   az login
   

3. Získejte ID tenanta a ID předplatného. Pokud máte více tenantů nebo předplatných, ujistěte se, že používáte ten správný.

   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 .rest souboru, .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 rychlém startu.

1. Spusťte Visual Studio Code a vyberte dlaždici Rozšíření .

2. Vyhledejte klienta REST a vyberte Nainstalovat.

   

3. Otevřete nebo vytvořte nový soubor s názvem nebo .http příponou .rest 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"
        }
      }

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

V tomto kroku nakonfigurujte vyhledávací službu tak, aby rozpoznala autorizační hlavičku požadavků na data, která poskytují přístupový token OAuth2.

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

Pokud chcete používat výhradně řízení přístupu na základě role, vypněte ověřování pomocí klíče rozhraní API podle druhého požadavku, tentokrát na disableLocalAuth 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"
                }
            }
        }
    }

Vynucení zásad 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

I když sémantický ranker není ve výchozím nastavení povolený , můžete funkci uzamknout na úrovni služby, abyste měli větší jistotu, že ji nelze použít.

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

Výpis 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 hledání seznamu

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