حدد ملف تعريف تقني RESTful في نهج Azure Active Directory B2C المخصص

إشعار

في Azure Active Directory B2C، تم تصميم النُهج المخصصة بشكل أساسي لمعالجة السيناريوهات المعقدة. بالنسبة إلى معظم السيناريوهات، نوصي باستخدام تدفقات المستخدم المضمنة. إذا لم تقم بذلك، تعرف على حزمة بادئ النهج المخصصة في البدء باستخدام النهج المخصصة في Active Directory B2C.

يوفر Azure Active Directory B2C (Azure AD B2C) الدعم لتكامل خدمة RESTful الخاصة بك. يرسل Azure AD B2C البيانات إلى خدمة RESTful في مجموعة مطالبات الإدخال ويتلقى البيانات مرة أخرى في مجموعة مطالبات المخرجات. لمزيد من المعلومات، راجع دمج تبادل مطالبات واجهة برمجة تطبيقات REST في نهج Azure AD B2C المخصص.

البروتوكول

يجب تعيين سمة اسم عنصر البروتوكول على Proprietary. يجب أن تتضمن سمة المعالج اسم المؤهّل بالكامل لتجميع معالج البروتوكول الذي يستخدمه Azure AD B2C: Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null.

يوضح المثال التالي ملف تعريف تقني RESTful:

<TechnicalProfile Id="REST-UserMembershipValidator">
  <DisplayName>Validate user input data and return loyaltyNumber claim</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  ...

مطالبات الإدخال

يحتوي عنصر InputClaims على قائمة بالمطالبات لإرسالها إلى واجهة برمجة تطبيقات REST. يمكنك أيضًا تعيين اسم مطالبتك إلى الاسم المحدد في REST API. يوضح المثال التالي التعيين بين سياستك وواجهة برمجة تطبيقات REST. يتم إرسال مطالبة givenName إلى واجهة برمجة تطبيقات REST ك firstName، بينما يتم إرسال اللقب ك lastName. يتم تعيين مطالبة البريد الإلكتروني كما هي.

<InputClaims>
  <InputClaim ClaimTypeReferenceId="email" />
  <InputClaim ClaimTypeReferenceId="givenName" PartnerClaimType="firstName" />
  <InputClaim ClaimTypeReferenceId="surname" PartnerClaimType="lastName" />
</InputClaims>

قد يحتوي عنصر InputClaimsTransformations على مجموعة من عناصر InputClaimsTransformation التي يتم استخدامها لتعديل مطالبات الإدخال أو إنشاء مطالبات جديدة قبل الإرسال إلى واجهة برمجة تطبيقات REST.

إرسال حمولة JSON

يتيح لك ملف التعريف الفني لـ REST API إرسال حمولة JSON معقدة إلى نقطة نهاية.

لإرسال حمولة JSON معقدة:

1. بناء حمولة JSON الخاصة بك مع تحويل مطالبات GenerateJson .
2. في ملف التعريف التقني لواجهة برمجة تطبيقات REST:
   1. أضف تحويل مطالبات الإدخال مع الإشارة إلى GenerateJson تحويل المطالبات.
   2. SendClaimsIn تعيين خيار بيانات التعريف إلىbody
   3. ClaimUsedForRequestPayload تعيين خيار بيانات التعريف إلى اسم المطالبة التي تحتوي على حمولة JSON.
   4. في مطالبة الإدخال، أضف مرجعًا إلى مطالبة الإدخال التي تحتوي على حمولة JSON.

يرسل المثال TechnicalProfile التالي بريدا إلكترونيا للتحقق باستخدام خدمة بريد إلكتروني تابعة لجهة خارجية (في هذه الحالة، SendGrid).

<TechnicalProfile Id="SendGrid">
  <DisplayName>Use SendGrid's email API to send the code to the user</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://api.sendgrid.com/v3/mail/send</Item>
    <Item Key="AuthenticationType">Bearer</Item>
    <Item Key="SendClaimsIn">Body</Item>
    <Item Key="ClaimUsedForRequestPayload">sendGridReqBody</Item>
    <Item Key="DefaultUserMessageIfRequestFailed">Cannot process your request right now, please try again later.</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="BearerAuthenticationToken" StorageReferenceId="B2C_1A_SendGridApiKey" />
  </CryptographicKeys>
  <InputClaimsTransformations>
    <InputClaimsTransformation ReferenceId="GenerateSendGridRequestBody" />
  </InputClaimsTransformations>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="sendGridReqBody" />
  </InputClaims>
</TechnicalProfile>

مطالبات الإخراج

يحتوي عنصر OutputClaims على قائمة بالمطالبات التي تم إرجاعها بواسطة واجهة برمجة تطبيقات REST. قد تحتاج إلى تعيين اسم المطالبة المحددة في سياستك إلى الاسم المحدد في REST API. يمكنك أيضا تضمين المطالبات التي لم يتم إرجاعها بواسطة واجهة برمجة تطبيقات REST، طالما قمت بتعيين السمة DefaultValue .

قد يحتوي عنصر OutputClaimsTransformations على مجموعة من عناصر OutputClaimsTransformation التي تستخدم لتعديل مطالبات الإخراج أو إنشاء مطالبات جديدة.

يوضح المثال التالي المطالبة التي أرجعها REST API:

• مطالبة معرف العضوية التي تم تعيينها إلى اسم المطالبة loyaltyNumber.

يعرض الملف التعريفي الفني أيضًا المطالبات التي لم يتم إرجاعها بواسطة موفر الهوية:

• مطالبة oyaltyNumberIsNew التي تم تعيين قيمة افتراضية لها على true.

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" PartnerClaimType="MembershipId" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumberIsNew" DefaultValue="true" />
</OutputClaims>

بيانات التعريف

السمة	المطلوب	‏‏الوصف
ServiceUrl	‏‏نعم‬	عنوان URL لنقطة نهاية REST API.
نوع المصادقة	‏‏نعم‬	نوع المصادقة الذي يتم إجراؤه بواسطة موفر مطالبات RESTful. القيم المحتملة: None أو Basic أو Bearer أو ClientCertificate أو ApiKeyHeader. None تشير القيمة إلى أن واجهة برمجة تطبيقات REST مجهولة. Basic تشير القيمة إلى أن واجهة برمجة تطبيقات REST مؤمنة بمصادقة HTTP الأساسية. يمكن فقط للمستخدمين المعتمدين، بما في ذلك Azure AD B2C، الوصول إلى واجهة برمجة التطبيقات الخاصة بك. ClientCertificate تشير القيمة (الموصى بها) إلى أن واجهة برمجة تطبيقات REST تقيد الوصول باستخدام مصادقة شهادة العميل. فقط الخدمات التي لديها الشهادات المناسبة، على سبيل المثال Azure AD B2C، يمكنها الوصول إلى API الخاص بك. Bearer تشير القيمة إلى أن واجهة برمجة تطبيقات REST تقيد الوصول باستخدام رمز OAuth2 Bearer المميز للعميل. تشير القيمة ApiKeyHeader إلى أن واجهة برمجة تطبيقات REST مؤمنة برأس HTTP لمفتاح واجهة برمجة التطبيقات، مثل x-function-key.
AllowInsecureAuthInProduction	لا	يشير إلى ما إذا كان يمكن تعيين AuthenticationType على none في بيئة الإنتاج (إن DeploymentMode الخاص بـ TrustFrameworkPolicy قد تم تعيينه على Production، أو لم يتم تعيينه). القيم المحتملة: صواب أو خطأ (افتراضي).
SendClaimsIn	لا	يحدد كيفية إرسال مطالبات الإدخال إلى مزود مطالبات RESTful. القيم المحتملة: Body (افتراضي) أو Formأو HeaderUrl أو QueryString. Body القيمة هي مطالبة الإدخال التي يتم إرسالها في نص الطلب بتنسيق JSON. Form القيمة هي مطالبة الإدخال التي يتم إرسالها في نص الطلب بتنسيق قيمة مفتاح مفصول "&". Header القيمة هي مطالبة الإدخال التي يتم إرسالها في عنوان الطلب. Url القيمة هي مطالبة الإدخال التي يتم إرسالها في عنوان URL، على سبيل المثال، https://api.example.com/{claim1}/{claim2}?{claim3}={claim4}. لا يمكن أن يحتوي جزء اسم المضيف من URL على مطالبات. QueryString القيمة هي مطالبة الإدخال التي يتم إرسالها في سلسلة استعلام الطلب. أفعال HTTP التي يستدعيها كل منها هي كما يلي: Body:وظيفه Form:وظيفه Header:الحصول Url:الحصول QueryString:الحصول
ClaimsFormat	لا	غير مستخدم حاليًا، ويمكن تجاهله.
ClaimUsedForRequestPayload	لا	اسم مطالبة السلسلة التي تحتوي على الحمولة المراد إرسالها إلى REST API.
وضع التصحيح	لا	يقوم بتشغيل ملف التعريف الفني في وضع التصحيح. القيم المحتملة: true، أو false (افتراضية). في وضع التصحيح، يمكن لواجهة برمجة تطبيقات REST إرجاع المزيد من المعلومات. راجع قسم إرجاع رسالة الخطأ.
تضمينClaimResolvingInClaimsHandling	لا	بالنسبة لمطالبات الإدخال والإخراج، يتم تحديد إذا ما كان حل المطالبات مدرجًا في ملف التعريف الفني أم لا. القيم المحتملة: true، أو false (افتراضية). إذا كنت تريد استخدام محلل مطالبات في ملف التعريف الفني حدد القيمة إلى true.
ResolveJsonPathsInJsonTokens	لا	يشير إلى ما إذا كان ملف التعريف الفني يحل مسارات JSON. القيم المحتملة: true، أو false (افتراضية). استخدم هذه البيانات الأولية لقراءة البيانات من عنصر JSON متداخل. في OutputClaim، قم بتعيين PartnerClaimType إلى عنصر المسار JSON الذي تريد إخراجه. على سبيل المثال: firstName.localized أو data[0].to[0].email.
UseClaimAsBearerToken	لا	اسم المطالبة التي تحتوي على رمز الحامل.

معالجة الخطأ

يمكن استخدام البيانات الوصفية التالية لتكوين رسائل الخطأ المعروضة عند فشل REST API. يمكن ترجمة رسائل الخطأ

السمة	المطلوب	‏‏الوصف
DefaultUserMessageIfRequestFailed	لا	رسالة خطأ مخصصة افتراضية لجميع استثناءات REST API.
UserMessageIfCircuitOpen	لا	ظهور رسالة خطأ عندما يتعذر الوصول إلى واجهة برمجة تطبيقات REST. إذا لم يتم تحديده، فسيتم إرجاع DefaultUserMessageIfRequestFailed.
UserMessageIfDnsResolutionFailed	لا	رسالة خطأ لاستثناء تحليل DNS. إذا لم يتم تحديده، فسيتم إرجاع DefaultUserMessageIfRequestFailed.
رسالة للمستخدم في حالة انتهاء وقت الطلب (UserMessageIfRequestTimeout)	لا	ظهور رسالة خطأ عند انتهاء مهلة الاتصال. إذا لم يتم تحديده، فسيتم إرجاع DefaultUserMessageIfRequestFailed.

مفاتيح تشفير

إذا تم تعيين نوع المصادقة على None، فلن يتم استخدام عنصر CryptographicKeys .

<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">None</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
</TechnicalProfile>

إذا تم تعيين نوع المصادقة على Basic، فإن عنصر CryptographicKeys يحتوي على السمات التالية:

السمة	المطلوب	‏‏الوصف
BasicAuthenticationUsername	‏‏نعم‬	اسم المستخدم الذي يتم استخدامة للمصادقة.
BasicAuthenticationPassword	‏‏نعم‬	كلمة المرور المستخدمة للمصادقة.

يوضح المثال التالي ملف تعريف تقني مصادقة أساسية:

<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">Basic</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="BasicAuthenticationUsername" StorageReferenceId="B2C_1A_B2cRestClientId" />
    <Key Id="BasicAuthenticationPassword" StorageReferenceId="B2C_1A_B2cRestClientSecret" />
  </CryptographicKeys>
</TechnicalProfile>

إذا تم تعيين نوع المصادقة على ClientCertificate، فإن عنصر CryptographicKeys يحتوي على السمة التالية:

السمة	المطلوب	‏‏الوصف
شهادة العميل	‏‏نعم‬	شهادة X509 (مجموعة مفاتيح RSA) لاستخدامها للمصادقة.

<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">ClientCertificate</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="ClientCertificate" StorageReferenceId="B2C_1A_B2cRestClientCertificate" />
  </CryptographicKeys>
</TechnicalProfile>

إذا تم تعيين نوع المصادقة على Bearer، فإن عنصر CryptographicKeys يحتوي على السمة التالية:

السمة	المطلوب	‏‏الوصف
BearerAuthenticationToken	لا	رمز OAuth 2.0 للحامل المميز.

<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">Bearer</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="BearerAuthenticationToken" StorageReferenceId="B2C_1A_B2cRestClientAccessToken" />
  </CryptographicKeys>
</TechnicalProfile>

إذا تم تعيين نوع المصادقة على ApiKeyHeader، فإن عنصر CryptographicKeys يحتوي على السمة التالية:

السمة	المطلوب	‏‏الوصف
اسم رأس HTTP، مثل x-functions-key، أو x-api-key.	‏‏نعم‬	المفتاح المستخدم للمصادقة.

إشعار

في الوقت الحالي، يدعم Azure AD B2C رأس HTTP واحد فقط للمصادقة. إذا كانت مكالمة RESTful الخاصة بك تتطلب عناوين متعددة، مثل معرف العميل والقيمة السرية للعميل، فستحتاج إلى توكيل الطلب بطريقة ما.

<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">ApiKeyHeader</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="x-functions-key" StorageReferenceId="B2C_1A_RestApiKey" />
  </CryptographicKeys>
</TechnicalProfile>

إرجاع رسالة خطأ التحقق من الصحة

قد تحتاج واجهة برمجة تطبيقات REST إلى إرجاع رسالة خطأ، مثل "لم يتم العثور على المستخدم في نظام CRM". في حالة حدوث خطأ، يجب أن تقوم واجهة برمجة تطبيقات REST بإرجاع رسالة خطأ HTTP 4xx، مثل رمز حالة استجابة 400 (طلب غير صالح) أو 409 (تعارض). يحتوي نص الاستجابة على رسالة خطأ بتنسيق JSON:

{
  "version": "1.0.0",
  "status": 409,
  "code": "API12345",
  "requestId": "50f0bd91-2ff4-4b8f-828f-00f170519ddb",
  "userMessage": "Message for the user",
  "developerMessage": "Verbose description of problem and how to fix it.",
  "moreInfo": "https://restapi/error/API12345/moreinfo"
}

السمة	المطلوب	الوصف
الإصدار	‏‏نعم‬	إصدار REST API الخاص بك. على سبيل المثال: 1.0.1
الحالة	‏‏نعم‬	رقم يشبه رموز حالة استجابة HTTP، ويجب أن يكون 409. يمكن لخدمة REST إرجاع رمز حالة HTTP 4XX، ولكن يجب أن تكون 409قيمة status المقدمة في نص الاستجابة بتنسيق JSON .
الكود	لا	رمز خطأ من موفر نقطة النهاية RESTful، والذي يتم عرضه عند DebugMode تمكينه.
طلب معرف	لا	معرف طلب من موفر نقطة النهاية RESTful، والذي يتم عرضه عند DebugMode تمكينه.
userMessage	‏‏نعم‬	رسالة خطأ تظهر للمستخدم.
المطور	لا	الوصف المطول للمشكلة وكيفية إصلاحها، والتي يتم عرضها عند DebugMode تمكينها.
مزيد من المعلومات	لا	URI يشير إلى معلومات إضافية، يتم عرضها عند DebugMode تمكينها.

يُظهر المثال التالي فئة #C التي تُرجع رسالة خطأ:

public class ResponseContent
{
  public string Version { get; set; }
  public int Status { get; set; }
  public string Code { get; set; }
  public string UserMessage { get; set; }
  public string DeveloperMessage { get; set; }
  public string RequestId { get; set; }
  public string MoreInfo { get; set; }
}

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

راجع المقالات التالية للحصول على أمثلة لاستخدام ملف تعريف تقني لـ RESTful:

• دمج تبادل مطالبات واجهة برمجة تطبيقات REST في نهج Azure AD B2C المخصص
• معاينة: إضافة موصل API إلى تدفق مستخدم الاشتراك
• معاينة: إضافة REST API المطالبات التبادلات إلى النهج المخصصة في Azure Active Directory B2C
• تأمين خدمات REST API