إدارة الذكاء الاصطناعي خدمة البحث Azure باستخدام واجهات برمجة تطبيقات REST

مقالة
03/20/2024

في هذه المقالة، تعرف على كيفية إنشاء وتكوين الذكاء الاصطناعي خدمة البحث Azure باستخدام واجهات برمجة تطبيقات REST للإدارة. يتم ضمان إدارة واجهات برمجة التطبيقات REST فقط لتوفير الوصول المبكر إلى ميزات المعاينة.

تتوفر Management REST API في إصدارات مستقرة ومعاينة. تأكد من تعيين إصدار واجهة برمجة تطبيقات المعاينة إذا كنت تصل إلى ميزات المعاينة.

إنشاء خدمة أو تحديثها
تمكين التحكم في الوصول المستند إلى الدور في Azure لمستوى البيانات
فرض نهج مفتاح يديره العميل
تعطيل الترتيب الدلالي
تعطيل أحمال العمل التي تدفع البيانات إلى الموارد الخارجية
إنشاء مفتاح استعلام
إعادة إنشاء مفتاح مسؤول
سرد اتصالات نقطة النهاية الخاصة
سرد عمليات البحث
حذف خدمات البحث

تحتوي جميع واجهات برمجة تطبيقات REST للإدارة على أمثلة. إذا لم تتم تغطية مهمة في هذه المقالة، فراجع مرجع واجهة برمجة التطبيقات بدلا من ذلك.

المتطلبات الأساسية

اشتراك Azure - أنشئ اشتراكاً مجاناً.
Visual Studio Code مع عميل REST.
يستخدم Azure CLI للحصول على رمز مميز للوصول. يجب أن تكون مالكا أو مسؤولا في اشتراك Azure.

طلب رمز مميز للوصول

تتم مصادقة استدعاءات واجهة برمجة تطبيقات REST للإدارة من خلال معرف Microsoft Entra. تحتاج إلى توفير رمز مميز للوصول على الطلب، جنبا إلى جنب مع أذونات لإنشاء مورد وتكوينه.

يمكنك استخدام Azure CLI أو Azure PowerShell لإنشاء رمز مميز للوصول.

افتح shell أمر ل Azure CLI.
سجل الدخول إلى اشتراك Azure الخاص بك.
```
az login
```
احصل على معرف المستأجر ومعرف الاشتراك. إذا كان لديك عدة مستأجرين أو اشتراكات، فتأكد من استخدام المستأجر الصحيح.
```
az account show
```

احصل على الرمز المميز للوصول.

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

إعداد Visual Studio Code

إذا لم تكن على دراية بعميل REST ل Visual Studio Code، يتضمن هذا القسم الإعداد بحيث يمكنك إكمال المهام في هذا التشغيل السريع.

ابدأ تشغيل Visual Studio Code وحدد الإطار المتجانب Extensions.
ابحث عن عميل REST وحدد تثبيت.
افتح ملفا جديدا أو أنشئه باسم إما .rest بملحق ملف أو .http .

توفير متغيرات للقيم التي قمت باستردادها في الخطوة السابقة.

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

تحقق من تشغيل الجلسة عن طريق سرد خدمات البحث في اشتراكك.

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

حدد إرسال طلب. يجب أن تظهر استجابة في جزء مجاور. إذا كانت لديك خدمات بحث موجودة، يتم سردها. وإلا، تكون القائمة فارغة، ولكن طالما أن رمز HTTP هو 200 موافق، فأنت جاهز للخطوات التالية.

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

إنشاء خدمة أو تحديثها

إنشاء خدمة بحث أو تحديثها ضمن الاشتراك الحالي. يستخدم هذا المثال متغيرات لاسم خدمة البحث والمنطقة، والتي لم يتم تعريفها بعد. إما توفير الأسماء مباشرة، أو إضافة متغيرات جديدة إلى المجموعة.

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

إنشاء خدمة S3HD

لإنشاء خدمة S3HD ، استخدم مجموعة من sku الخصائص و hostingMode . قم بتعيين sku إلى standard3 و "hostingMode" إلى 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"
        }
    }

تكوين الوصول المستند إلى الدور لمستوى البيانات

ينطبق على: Search Index Data Contributor، Search Index Data Reader، Search Service Contributor

في هذه الخطوة، قم بتكوين خدمة البحث الخاصة بك للتعرف على عنوان تخويل على طلبات البيانات التي توفر رمز وصول OAuth2.

لاستخدام التحكم في الوصول المستند إلى الدور لعمليات مستوى البيانات، قم بتعيين authOptions إلى aadOrApiKey ثم أرسل الطلب.

لاستخدام التحكم في الوصول المستند إلى الدور بشكل حصري، قم بإيقاف تشغيل مصادقة مفتاح API عن طريق المتابعة بطلب ثان، هذه المرة الإعداد disableLocalAuth إلى صحيح.

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

فرض نهج مفتاح يديره العميل

إذا كنت تستخدم التشفير المدار من قبل العميل، يمكنك تمكين "encryptionWithCMK" مع تعيين "فرض" إلى "Enabled" إذا كنت تريد أن تقوم خدمة البحث بالإبلاغ عن حالة التوافق الخاصة بها.

عند تمكين هذا النهج، ستفشل أي استدعاءات REST تنشئ كائنات تحتوي على بيانات حساسة، مثل سلسلة الاتصال داخل مصدر بيانات، إذا لم يتم توفير مفتاح تشفير:"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": "Disabled",
            "encryptionComplianceStatus": "Compliant"
            },
        }
    }

تعطيل الترتيب الدلالي

على الرغم من عدم تمكين الترتيب الدلالي بشكل افتراضي، يمكنك تأمين الميزة على مستوى الخدمة.

### disable semantic ranking
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"
        }
    }

تعطيل أحمال العمل التي تدفع البيانات إلى الموارد الخارجية

يكتب Azure الذكاء الاصطناعي Search إلى مصادر البيانات الخارجية عند تحديث مخزن معلومات أو حفظ حالة جلسة تتبع الأخطاء أو إثراء التخزين المؤقت. يعطل المثال التالي أحمال العمل هذه على مستوى الخدمة.

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

حذف خدمة بحث

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

سرد مفاتيح واجهة برمجة تطبيقات المسؤول

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

إعادة إنشاء مفاتيح واجهة برمجة تطبيقات المسؤول

يمكنك إعادة إنشاء مفتاح API مسؤول واحد فقط في كل مرة.

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

إنشاء مفاتيح واجهة برمجة تطبيقات الاستعلام

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

سرد اتصالات نقطة النهاية الخاصة

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

سرد عمليات البحث

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

الخطوات التالية

بعد تكوين خدمة بحث، تتضمن الخطوات التالية إنشاء فهرس أو الاستعلام عن فهرس باستخدام المدخل أو واجهات برمجة تطبيقات REST أو Azure SDK.