مهارة واجهة برمجة تطبيقات الويب المخصصة في خط أنابيب إثراء البحث المعرفي في Azure

مقالة
04/27/2022
قراءة خلال 5 دقائق

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

ويرد في هذا المستند وصف لهيكل حمولة JSON بمزيد من التفصيل.

ملاحظة

سيعيد المفهرس المحاولة مرتين لبعض رموز حالة HTTP القياسية التي تم إرجاعها من واجهة برمجة تطبيقات الويب. رموز حالة HTTP هذه هي:

502 Bad Gateway
503 Service Unavailable
429 Too Many Requests

@odata.type

Microsoft.Skills.Custom.WebApiSkill

معلمات المهارة

المعلمات حساسة لحالة الأحرف.

اسم المعلمة	الوصف
`uri`	عنوان URI الخاص بواجهة برمجة تطبيقات الويب التي سيتم إرسال حمولة JSON إليها. يسمح فقط بمخطط https URI
`authResourceId`	(اختياري) تشير السلسلة التي إذا تم تعيينها إلى أن هذه المهارة يجب أن تستخدم هوية مدارة عند الاتصال بالوظيفة أو التطبيق الذي يستضيف الرمز. قيمة هذه الخاصية هي معرف التطبيق (العميل) للدالة أو تسجيل التطبيق في Azure Active Directory. سيتم استخدام هذه القيمة لتحديد نطاق الرمز المميز للمصادقة الذي تم استرداده بواسطة المفهرس ، وسيتم إرسالها مع طلب واجهة برمجة تطبيقات مهارات الويب المخصص إلى الوظيفة أو التطبيق. يتطلب إعداد هذه الخاصية تكوين خدمة البحث للهوية المدارة وتكوين تطبيق وظيفة Azure لتسجيل الدخول إلى Azure AD.
`httpMethod`	طريقة الاستخدام أثناء إرسال الحمولة. الطرق المسموح بها هي `PUT` أو `POST`
`httpHeaders`	مجموعة من أزواج القيم الرئيسية حيث تمثل المفاتيح أسماء الرؤوس وتمثل القيم قيم الرأس التي سيتم إرسالها إلى واجهة برمجة تطبيقات الويب الخاصة بك مع الحمولة. يحظر وجود الرؤوس التالية في هذه المجموعة: `Accept`, , , , `Accept-CharsetAccept-EncodingContent-LengthContent-TypeCookieHostTEUpgradeVia`
`timeout`	(اختياري) عند تحديده، يشير إلى المهلة لعميل http الذي يجري مكالمة واجهة برمجة التطبيقات. يجب تنسيقه كقيمة XSD "dayTimeDuration" (مجموعة فرعية مقيدة من قيمة مدة ISO 8601 ). على سبيل المثال ، `PT60S` لمدة 60 ثانية. إذا لم يتم تعيينها، يتم اختيار قيمة افتراضية مدتها 30 ثانية. يمكن تعيين المهلة إلى 230 ثانية كحد أقصى و 1 ثانية كحد أدنى.
`batchSize`	(اختياري) يشير إلى عدد "سجلات البيانات" (راجع بنية حمولة JSON أدناه) التي سيتم إرسالها لكل مكالمة API. إذا لم يتم تعيينه، اختيار افتراضي 1000. نوصي باستخدام هذه المعلمة لتحقيق مقايضة مناسبة بين إنتاجية الفهرسة والتحميل على واجهة برمجة التطبيقات الخاصة بك.
`degreeOfParallelism`	(اختياري) عند تحديده، يشير إلى عدد المكالمات التي سيجريها المفهرس بالتوازي مع نقطة النهاية التي قدمتها. يمكنك تقليل هذه القيمة إذا فشلت نقطة النهاية الخاصة بك تحت تحميل طلب مرتفع جدا، أو رفعها إذا كانت نقطة النهاية قادرة على قبول المزيد من الطلبات وترغب في زيادة أداء المفهرس. إذا لم يتم تعيينها، يتم استخدام قيمة افتراضية من 5. `degreeOfParallelism` يمكن ضبطه على 10 كحد أقصى والحد الأدنى 1.

مدخلات المهارات

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

مخرجات المهارات

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

نموذج تعريف

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "A custom skill that can identify positions of different phrases in the source text",
  "uri": "https://contoso.count-things.com",
  "batchSize": 4,
  "context": "/document",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    },
    {
      "name": "language",
      "source": "/document/languageCode"
    },
    {
      "name": "phraseList",
      "source": "/document/keyphrases"
    }
  ],
  "outputs": [
    {
      "name": "hitPositions"
    }
  ]
}

نموذج بنية JSON للإدخال

تمثل بنية JSON هذه الحمولة التي سيتم إرسالها إلى واجهة برمجة تطبيقات الويب الخاصة بك. وسوف يتبع دائما هذه القيود:

يتم استدعاء values كيان المستوى الأعلى وسيكون عبارة عن مجموعة من الكائنات. سيكون عدد هذه الكائنات على batchSizeالأكثر .
سيكون لكل كائن في الصفيف values ما يلي:
- خاصية recordId عبارة عن سلسلة فريدة ، تستخدم لتحديد هذا السجل.
- خاصية data عبارة عن كائن JSON. سوف تتوافق حقول الخاصية data مع "الأسماء" المحددة في inputs قسم تعريف المهارة. ستكون قيمة هذه الحقول من تلك الحقول source (والتي يمكن أن تكون من حقل في المستند ، أو ربما من مهارة أخرى).

{
    "values": [
      {
        "recordId": "0",
        "data":
           {
             "text": "Este es un contrato en Inglés",
             "language": "es",
             "phraseList": ["Este", "Inglés"]
           }
      },
      {
        "recordId": "1",
        "data":
           {
             "text": "Hello world",
             "language": "en",
             "phraseList": ["Hi"]
           }
      },
      {
        "recordId": "2",
        "data":
           {
             "text": "Hello world, Hi world",
             "language": "en",
             "phraseList": ["world"]
           }
      },
      {
        "recordId": "3",
        "data":
           {
             "text": "Test",
             "language": "es",
             "phraseList": []
           }
      }
    ]
}

هيكل JSON لإخراج العينة

يتوافق "الإخراج" مع الاستجابة التي تم إرجاعها من واجهة برمجة تطبيقات الويب الخاصة بك. يجب أن تقوم واجهة برمجة تطبيقات الويب بإرجاع حمولة JSON فقط (تم التحقق منها من خلال النظر Content-Type إلى رأس الاستجابة) ويجب أن تستوفي القيود التالية:

يجب أن يكون هناك كيان من المستوى الأعلى يسمى values والذي يجب أن يكون مجموعة من الكائنات.
يجب أن يكون عدد الكائنات في الصفيف هو نفسه عدد الكائنات المرسلة إلى واجهة برمجة تطبيقات الويب.
يجب أن يحتوي كل كائن على:
- recordId عقار
- خاصية data ، وهي كائن تكون فيه الحقول عبارة عن إثراءات مطابقة ل "الأسماء" في output الحقل وتعتبر قيمتها الإثراء.
- خاصية، صفيف يسرد errors أي أخطاء تمت مواجهتها ستتم إضافتها إلى محفوظات تنفيذ المفهرس. هذه الخاصية مطلوبة، ولكن يمكن أن يكون لها قيمة null .
- خاصية، صفيف يسرد warnings أي تحذيرات تمت مواجهتها ستتم إضافتها إلى محفوظات تنفيذ المفهرس. هذه الخاصية مطلوبة، ولكن يمكن أن يكون لها قيمة null .
ترتيب الكائنات في values الطلب أو الاستجابة ليس مهما. ومع ذلك ، يتم استخدام الارتباط ، recordId لذلك سيتم تجاهل أي سجل في الاستجابة يحتوي على recordId جزء من الطلب الأصلي إلى واجهة برمجة تطبيقات الويب.

{
    "values": [
        {
            "recordId": "3",
            "data": {
            },
            "errors": [
              {
                "message" : "'phraseList' should not be null or empty"
              }
            ],
            "warnings": null
        },
        {
            "recordId": "2",
            "data": {
                "hitPositions": [6, 16]
            },
            "errors": null,
            "warnings": null
        },
        {
            "recordId": "0",
            "data": {
                "hitPositions": [0, 23]
            },
            "errors": null,
            "warnings": null
        },
        {
            "recordId": "1",
            "data": {
                "hitPositions": []
            },
            "errors": null,
            "warnings": {
                "message": "No occurrences of 'Hi' were found in the input text"
            }
        },
    ]
}

حالات الخطأ

بالإضافة إلى عدم توفر واجهة برمجة تطبيقات الويب الخاصة بك، أو إرسال رموز حالة غير ناجحة، يعتبر ما يلي حالات خاطئة:

إذا قامت واجهة برمجة تطبيقات الويب بإرجاع رمز حالة نجاح ولكن الاستجابة تشير إلى أنه ليس application/json كذلك ، اعتبار الاستجابة غير صالحة ولن يتم إجراء أي إثراءات.
إذا كانت هناك سجلات غير صالحة (على سبيل المثال، مفقودة أو مكررة) في صفيف الاستجابةvalues، recordId فلن يتم إجراء أي إثراء للسجلات غير الصالحة.

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