A Azure AI Keresés szolgáltatás kezelése REST API-k használatával

Megtudhatja, hogyan hozhat létre és konfigurálhat Azure AI Keresés szolgáltatást a Management REST API-k használatával. Csak a felügyeleti REST API-k biztosítják a korai hozzáférést az előzetes verziójú funkciókhoz.

A Felügyeleti REST API stabil és előzetes verzióban érhető el. Az előzetes verziójú funkciók elérésekor mindenképpen állítsa be az előzetes verziójú API-verziót.

Az összes Felügyeleti REST API-nak vannak példái. Ha a cikk nem foglalkozik egy feladatsal, tekintse meg inkább az API-hivatkozást .

Előfeltételek

• Aktív előfizetéssel rendelkező Azure fiók. Hozzon létre egy fiókot ingyenesen.

• Visual Studio CodeREST-ügyféllel.

• Azure CLI a hozzáférési jogkivonat lekéréséhez, az alábbi lépésekben leírtak szerint. Tulajdonosnak vagy rendszergazdának kell lennie a Azure-előfizetésben.

  A felügyeleti REST API-hívások hitelesítése Microsoft Entra ID keresztül történik. Meg kell adnia egy hozzáférési jogkivonatot az erőforrás létrehozásához és konfigurálásához szükséges kéréshez és engedélyekhez. A Azure CLI mellett a Azure PowerShell használatával is létrehozhat hozzáférési jogkivonatot.

  1. Nyisson meg egy parancshéjat a Azure CLI számára.

  2. Jelentkezzen be a Azure-előfizetésbe. Ha több bérlője vagy előfizetése van, győződjön meg arról, hogy a megfelelőt választja.

     az login
     

  3. Kérje le a bérlőazonosítót és az előfizetés azonosítóját.

     az account show
     

  4. Hozzáférési jogkivonat lekérése.

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

     Rendelkeznie kell egy bérlőazonosítóval, előfizetés-azonosítóval és tulajdonosi jogkivonattal. Ezeket az értékeket a következő lépésben létrehozott .rest vagy .http fájlba illessze be.

Visual Studio Code beállítása

Ha nem ismeri a REST-ügyfelet a Visual Studio Code esetében, ez a szakasz a telepítést is tartalmazza, hogy elvégezhesse a cikkben szereplő feladatokat.

1. Indítsa el Visual Studio Code, és válassza a Extensions csempét.

2. Keresse meg a REST-ügyfelet, és válassza a Telepítés lehetőséget.

   

3. Nyisson meg vagy hozzon létre egy új fájlt, amely rendelkezik .rest vagy .http fájlkiterjesztéssel.

4. Adja meg az előző lépésben lekért értékek változóit.

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

5. Ellenőrizze, hogy a munkamenet működőképes-e, ha felsorolja a keresési szolgáltatásokat az előfizetésében.

    ### 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. Válassza a Kérés küldése lehetőséget. A válasznak egy szomszédos panelen kell megjelennie. Ha már rendelkezik keresési szolgáltatásokkal, azok megjelennek a listában. Ellenkező esetben a lista üres, de amíg a HTTP-kód 200 OK, készen áll a következő lépésekre.

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

Szolgáltatás létrehozása vagy frissítése

Létrehoz vagy frissít egy keresési szolgáltatást az aktuális előfizetés alatt. Ez a példa változókat használ a keresési szolgáltatás nevéhez és régiójához, amelyeket még nem definiáltak. Adja meg közvetlenül a neveket, vagy adjon hozzá új változókat a gyűjteményhez.

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

Szolgáltatás létrehozása automatikusan létrehozott DNS-címkével

Az automatikusan létrehozott DNS-címke egy generált utótagot ad az Azure AI Keresés szolgáltatás végpontjának gazdagépnevéhez. Az Azure AI Keresés automatikusan létrehozza a címkét; Ön csak az újrafelhasználási hatókört választja ki. A hatókör meghatározza, hogy a címke egyedi-e, vagy ugyanahhoz a szolgáltatásnévhez használják-e fel újra az előfizetésén vagy a Microsoft Entra-bérlőben.

Szolgáltatás létrehozásakor konfigurálja ezt a funkciót a 2026-09-01-preview Felügyeleti REST API-n keresztül. Válassza ki a címke újrahasználati hatókörét a létrehozáskor, mert később nem módosíthatja a hatókört.

Ha kihagyja autoGeneratedDomainNameLabelScope vagy beállítja azt null, a szolgáltatás automatikusan létrehozott címke nélkül használja az alapértelmezett végpontformátumot.

Használja a fenti előfeltételeket és REST-ügyfélváltozókat . Állítsa a(z) resource-group értékét egy meglévő erőforráscsoportra, a(z) search-service értékét egy új szolgáltatásnévre, a(z) region értékét pedig az előfizetéséhez elérhető régióra.

A következő kérés egy Basic szolgáltatást hoz létre egyedi címkével:

@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-NEW-SERVICE-NAME-HERE
@region = PUT-YOUR-REGION-HERE

### Create a service with an auto-generated DNS label
PUT https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2026-09-01-preview HTTP/1.1
Content-Type: application/json
Authorization: ******

{
  "location": "{{region}}",
  "sku": {
    "name": "basic"
  },
  "properties": {
    "replicaCount": 1,
    "partitionCount": 1,
    "autoGeneratedDomainNameLabelScope": "NoReuse"
  }
}

A sikeres üzembe helyezés után a válasz tartalmazza a létrehozott végpontot és a kiválasztott hatókört:

{
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/my-resource-group/providers/Microsoft.Search/searchServices/mysearchservice",
  "name": "mysearchservice",
  "type": "Microsoft.Search/searchServices",
  "location": "westus",
  "sku": {
    "name": "basic"
  },
  "properties": {
    "endpoint": "https://mysearchservice-12345678abcdefgh.sg.search.windows.net/",
    "provisioningState": "Succeeded",
    "autoGeneratedDomainNameLabelScope": "NoReuse"
  }
}

Referencia: Keresési szolgáltatás létrehozása vagy frissítése.

Az adatsík API-khoz való csatlakozás előtt olvassa ki a(z) properties.endpoint elemet a szolgáltatás válaszából. Az automatikusan létrehozott címkével rendelkező végpont formátuma a következő: https://<service-name>-<label>.sg.search.windows.net/. A szolgáltatás name és az Azure Resource Manager-erőforrás id nem változik.

Válasszon az alábbi értékek közül:

Hivatkozás: Keresési szolgáltatás tulajdonságai.

Szolgáltatás frissítése

Egyes Azure AI Keresés képességek csak az új szolgáltatások számára érhetők el. A szolgáltatás újralétrehozásának elkerülése és az új funkciók meglévő szolgáltatásba való integrálása érdekében előfordulhat, hogy frissítheti a szolgáltatást.

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

Tarifacsomagok módosítása

Ha több vagy kevesebb kapacitásra van szüksége, másik tarifacsomagra válthat. Jelenleg csak az Alapszintű és a Standard (S1, S2 és S3) szint között válthat. sku A tulajdonság használatával adja meg az új szintet.

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

S3HD-szolgáltatás létrehozása

S3HD-szolgáltatás létrehozásához használja a sku és hostingMode tulajdonságok kombinációját. Állítsa be a sku-t a standard3-re és a "hostingMode"-ot a HighDensity-re.

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

Szerepköralapú hozzáférés konfigurálása adatsíkhoz

A következőkre vonatkozik: Keresési index adatszolgáltatója, keresési index adatolvasója, keresési szolgáltatás közreműködője

Konfigurálja a keresési szolgáltatást, hogy felismerjen egy engedélyezési fejlécet az OAuth2 hozzáférési jogkivonatot biztosító adatkéréseken.

Ha szerepköralapú hozzáférés-vezérlést szeretne használni az adatsík-műveletekhez, állítsa be authOptionsaadOrApiKey és küldje el a kérést.

Ha kizárólag szerepköralapú hozzáférés-vezérlést szeretne használni, kapcsolja ki az API-kulcs alapú hitelesítést, küldjön be egy második kérést, és állítsa be a disableLocalAuth értékét igazra.

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

Bizalmas számítástechnika konfigurálása

A bizalmas számítástechnika nem kötelező számítási típus a használatban lévő adatok védelméhez. Ha konfigurálva van, a keresési szolgáltatás a standard virtuális gépek helyett bizalmas virtuális gépeken (DCasv5 vagy DCesv5) lesz üzembe helyezve. Ez a számítási típus szintén 10% felárat von maga után a számlázható szintekért. További információkért tekintse meg a díjszabási oldalt.

A napi használathoz nincs szükség bizalmas számítástechnikára. Ezt a számítási típust csak szigorú szabályozási, megfelelőségi vagy biztonsági követelmények esetén javasoljuk. További információ: Bizalmas számítástechnikai használati esetek.

A számítási típus rögzített a keresési szolgáltatás élettartama alatt. A bizalmas számítástechnika végleges konfigurálásához állítsa be a computeType tulajdonságot egy új szolgáltatásra confidential .

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

Ügyfél által felügyelt kulcsszabályzat kényszerítése

Ha ügyfél által kezelt titkosítást használ, engedélyezheti az "encryptionWithCMK" beállítást "Engedélyezve" értékre állított "kényszerítés" mellett, ha azt szeretné, hogy a keresési szolgáltatás jelentse a megfelelőségi állapotát.

Ha engedélyezi ezt a szabályzatot, a bizalmas adatokat tartalmazó objektumokat létrehozó REST-hívások, például az adatforráson belüli kapcsolati karakterlánc, sikertelenek lesznek, ha nincs megadva titkosítási kulcs: "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"
            }
        }
    }

Olyan számítási feladatok letiltása, amelyek adatokat küldnek külső erőforrásokba

Azure AI Keresés írja át a külső adatforrásokat a tudástár frissítésekor, a hibakeresési munkamenet állapotának mentéséhez vagy a gyorsítótárazás bővítéséhez. Az alábbi példa szolgáltatásszinten tiltja le ezeket a számítási feladatokat.

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

Keresési szolgáltatás törlése

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

Rendszergazdai API-kulcsok listázása

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

Rendszergazdai API-kulcsok újragenerálása

Egyszerre csak egy rendszergazdai API-kulcsot lehet újragenerálni.

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

Lekérdezési API-kulcsok létrehozása

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

Privát végpontkapcsolatok listázása

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

Keresési műveletek listázása

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

Következő lépések

A keresési szolgáltatás konfigurálása után a következő lépések közé tartozik a index létrehozása vagy index lekérdezése az Azure portál, REST API-k vagy Azure SDK használatával.

• A Azure AI Keresés index létrehozása a Azure portálon
• Indexelő beállítása más szolgáltatásokból származó adatok betöltéséhez
• Az Azure AI Keresés indexek lekérdezése az Azure portál Keresés Felfedezőjével
• Hogyan lehet használni az Azure AI Keresés szolgáltatást a .NET-ben