استخدام رموز وصول محدودة ل Face

يمكن لموردي البرامج المستقلين (ISVs) إدارة استخدام Face API لعملائهم عن طريق إصدار رموز الوصول المميزة التي تمنح الوصول إلى ميزات Face التي عادة ما تكون مسورة. يسمح هذا لشركات العملاء الخاصة بهم باستخدام واجهة برمجة تطبيقات Face دون الحاجة إلى المرور بعملية الموافقة الرسمية.

يوضح لك هذا الدليل كيفية إنشاء رموز الوصول المميزة، إذا كنت ISV معتمدا، وكيفية استخدام الرموز المميزة إذا كنت عميلا.

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

مثال على حالة الاستخدام

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

توقع المسؤولية

ISV لإصدار الرمز المميز هو المسؤول عن ضمان استخدام الرموز المميزة فقط للغرض المعتمد.

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

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

• cURL مثبت (أو أداة أخرى يمكنها إجراء طلبات HTTP).
• يحتاج ISV إما إلى مورد Azure الذكاء الاصطناعي Face أو مورد خدمات Azure الذكاء الاصطناعي متعدد الخدمات .
• يحتاج العميل إلى مورد Azure الذكاء الاصطناعي Face .

الخطوة 1: يحصل ISV على معرف مورد Face للعميل

يجب على ISV إعداد قناة اتصال بين خدمة السحابة الآمنة الخاصة بهم (والتي ستنشئ رمز الوصول) وتطبيقها الذي يعمل على جهاز العميل. يجب أن يكون معرف مورد Face للعميل معروفا قبل إنشاء LimitedAccessToken.

يحتوي معرف مورد Face على التنسيق التالي:

/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.CognitiveServices/accounts/<face-resource-name>

على سبيل المثال:

/subscriptions/dc4d27d9-ea49-4921-938f-7782a774e151/resourceGroups/client-rg/providers/Microsoft.CognitiveServices/accounts/client-face-api

الخطوة 2: ينشئ ISV رمزا مميزا

تستدعي خدمة سحابة ISV، التي تعمل في بيئة آمنة، واجهة برمجة تطبيقات issueLimitedAccessToken باستخدام معرف مورد Face المعروف للعميل النهائي.

لاستدعاء issueLimitedAccessToken API، انسخ الأمر cURL التالي إلى محرر نص.

curl -X POST 'https://<isv-endpoint>/sts/v1.0/issueLimitedAccessToken?expiredTime=3600' \  
-H 'Ocp-Apim-Subscription-Key: <client-face-key>' \  
-H 'Content-Type: application/json' \  
-d '{  
    "resourceId": "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.CognitiveServices/accounts/<face-resource-name>",  
    "featureFlags": ["Face.Identification", "Face.Verification"]  
}' 

بعد ذلك، قم بإجراء التغييرات التالية:

1. استبدل <isv-endpoint> بنقطة نهاية مورد ISV. على سبيل المثال، westus.api.cognitive.microsoft.com.
2. قم بتعيين المعلمة expiredTime بشكل اختياري لتعيين وقت انتهاء صلاحية الرمز المميز بالثوان. يجب أن يكون بين 60 و86400. القيمة الافتراضية هي 3600 (ساعة واحدة).
3. استبدل <client-face-key> بمفتاح مورد Face للعميل.
4. استبدل <subscription-id> بمعرف الاشتراك لاشتراك Azure الخاص بالعميل.
5. استبدل <resource-group-name> باسم مجموعة موارد العميل.
6. استبدل <face-resource-name> باسم مورد Face الخاص بالعميل.
7. قم بتعيين "featureFlags" إلى مجموعة أدوار الوصول التي تريد منحها. العلامات المتوفرة هي "Face.Identification"و "Face.Verification"و."LimitedAccess.HighRisk" يمكن لم ISV منح الأذونات التي تم منحها بنفسه من قبل Microsoft فقط. على سبيل المثال، إذا تم منح ISV حق الوصول إلى تعريف الوجه، فإنه يمكن إنشاء LimitedAccessToken ل Face.Identity للعميل. يتم تسجيل جميع عمليات إنشاء الرمز المميز واستخداماته لأغراض الاستخدام والأمان.

ثم الصق الأمر في نافذة طرفية وقم بتشغيله.

يجب أن ترجع واجهة برمجة التطبيقات استجابة 200 مع الرمز المميز في شكل رمز ويب JSON المميز (application/jwt). إذا كنت ترغب في فحص LimitedAccessToken، يمكنك القيام بذلك باستخدام JWT.

الخطوة 3: يستخدم تطبيق العميل الرمز المميز

يمكن لتطبيق ISV بعد ذلك تمرير الرمز المميز للوصول المحدود كعنوان طلب HTTP لطلبات Face API المستقبلية نيابة عن العميل. يعمل هذا بشكل مستقل عن آليات المصادقة الأخرى، لذلك لا يتم تسريب أي معلومات شخصية للعميل إلى ISV.

تنبيه

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

لكل ISV أن يقرر كيف يمرر الرمز المميز بالضبط من خدمته السحابية إلى تطبيق العميل.

واجهة برمجة التطبيقات REST

مثال على طلب Face API باستخدام رمز الوصول يبدو كما يلي:

curl -X POST 'https://<client-endpoint>/face/v1.0/identify' \  
-H 'Ocp-Apim-Subscription-Key: <client-face-key>' \  
-H 'LimitedAccessToken: Bearer <token>' \  
-H 'Content-Type: application/json' \  
-d '{  
  "largePersonGroupId": "sample_group",  
  "faceIds": [  
    "c5c24a82-6845-4031-9d5d-978df9175426",  
    "65d083d4-9447-47d1-af30-b626144bf0fb"  
  ],  
  "maxNumOfCandidatesReturned": 1,  
  "confidenceThreshold": 0.5  
}'

إشعار

ينتمي عنوان URL لنقطة النهاية ومفتاح Face إلى مورد Face الخاص بالعميل، وليس مورد ISV. <token> يتم تمرير كعنوان طلب HTTP.

C#‎

توضح لك القصاصات البرمجية التالية كيفية استخدام رمز مميز للوصول مع Face SDK ل C#‎.

تستخدم الفئة التالية رمز وصول لإنشاء كائن ServiceClientCredentials الذي يمكن استخدامه لمصادقة كائن عميل واجهة برمجة تطبيقات Face. يضيف تلقائيا رمز الوصول كعنوان في كل طلب سيقوم به عميل Face.

public class LimitedAccessTokenWithApiKeyClientCredential : ServiceClientCredentials 
{
    /// <summary> 
    /// Creates a new instance of the LimitedAccessTokenWithApiKeyClientCredential class 
    /// </summary> 
    /// <param name="apiKey">API Key for the Face API or CognitiveService endpoint</param> 
    /// <param name="limitedAccessToken">LimitedAccessToken to bypass the limited access program, requires ISV sponsership.</param> 

    public LimitedAccessTokenWithApiKeyClientCredential(string apiKey, string limitedAccessToken) 
    { 
        this.ApiKey = apiKey; 
        this.LimitedAccessToken = limitedAccessToken; 
    }

    private readonly string ApiKey; 
    private readonly string LimitedAccesToken; 

    /// <summary> 
    /// Add the Basic Authentication Header to each outgoing request 
    /// </summary> 
    /// <param name="request">The outgoing request</param>
    /// <param name="cancellationToken">A token to cancel the operation</param> 
    public override Task ProcessHttpRequestAsync(HttpRequestMessage request, CancellationToken cancellationToken) 
    { 
        if (request == null) 
            throw new ArgumentNullException("request"); 
        request.Headers.Add("Ocp-Apim-Subscription-Key", ApiKey); 
        request.Headers.Add("LimitedAccessToken", $"Bearer {LimitedAccesToken}");

        return Task.FromResult<object>(null); 
    } 
} 

في التطبيق من جانب العميل، يمكن استخدام فئة المساعد كما في هذا المثال:

static void Main(string[] args) 
{ 
    // create Face client object
    var faceClient = new FaceClient(new LimitedAccessTokenWithApiKeyClientCredential(apiKey: "<client-face-key>", limitedAccessToken: "<token>")); 

    faceClient.Endpoint = "https://willtest-eastus2.cognitiveservices.azure.com"; 

    // use Face client in an API call
    using (var stream = File.OpenRead("photo.jpg")) 
    {
        var result = faceClient.Face.DetectWithStreamAsync(stream, detectionModel: "Detection_03", recognitionModel: "Recognition_04", returnFaceId: true).Result; 

        Console.WriteLine(JsonConvert.SerializeObject(result)); 
    }
}

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

• مرجع واجهة برمجة تطبيقات LimitedAccessToken