اختر اتصال Integrately المناسب لعقد API لديك
تستدعي وصفة HTTP في هذا الدليل GenderAPI.io V2 على https://api.genderapi.io/api/v2/gender. أرسل type وvalue في جسم JSON؛ يظهر التقدير في data، بينما توجد معلومات الطلب والخصم في meta. للموصّلات الأصلية عقودها الخاصة، وهي موضّحة أدناه.
تشير صفحة GenderAPI.io على Integrately إلى genderapi.io، وتوفّر إجراءات للأسماء وعناوين البريد الإلكتروني ولاستخراج الاسم من عنوان البريد الإلكتروني. لا تذكر الصفحة إصدار API الأساسي ولا البنية الكاملة للمخرجات؛ وأسماء الإجراءات وحدها لا تؤكد التوافق مع V2.
توثّق Integrately الخيار Webhook/API كإجراء POST صادر. لم يُتحقَّق بشكل مستقل في هذا الدليل من عناصر التحكم الحالية في الترويسات ولا من محرر JSON. طبّق قواعد HTTP الخاصة بـ V2 أدناه فقط بعد التأكد من أن الإجراء الذي تستخدمه يستطيع إرسال ترويسة Authorization وجسم JSON متداخل. تحتفظ الإجراءات الأصلية القائمة بقواعد حقولها الخاصة.
جهّز الحساب والسجل المصدر
يُثري هذا المثال سجلات Mailchimp انطلاقًا من الاسم الأول. تحتاج إلى صلاحية الوصول إلى التطبيق المصدر والتطبيق الهدف، ومفتاح حساب GenderAPI.io، وميزات المنصة التي يستخدمها إجراء HTTP. لا يتضمن هذا الدليل بيانات اعتماد صالحة ولا حسابات مرتبطة.
يستخدم V1 وV2 مفتاح الحساب نفسه والرصيد نفسه. قبل إعداد أي طلب تُخصم عليه الأرصدة، تحقّق من المفتاح عبر GET /api/v2/usage وتأكّد من أن قيمة meta.access.mode في استجابة نقطة النهاية هذه هي api_key. إذا كان المفتاح مفقودًا أو غير معروف، فقد يُستخدم الوصول المشترك عبر التجربة حسب عنوان IP؛ ولا ينبغي أن تعتمد الأتمتة في بيئة الإنتاج على ذلك دون علمك.
أبقِ سير العمل متوقفًا أثناء إعداده. يُخصم على التقدير المُرسل للاختبار عدد الأرصدة المعتاد. راجعنا هذه الأدلة استنادًا إلى الوثائق العامة لكل منصة وإلى قواعد V2؛ ولم يُشغَّل لهذا المنشور أي سير عمل مُصادَق عليه من البداية إلى النهاية على أي منصة.
اضبط طلب GenderAPI.io V2 في Integrately
- اختر مشغّل Mailchimp للمشتركين وتحقّق من سجل اختبار. احفظ id الجمهور (Audience) وid المشترك للتحديث، واختر حقل الاسم الأول الفعلي، وتجاوز السجلات التي لا تحتوي على اسم أول.
- حدّد Webhook/API والإجراء المقابل لإرسال البيانات إلى URL. تحقّق من الإعداد المتاح قبل المتابعة: تتطلب القواعد أدناه ترويسات مُصادَقًا عليها وجسم JSON متداخلًا، ولم يُتحقَّق هنا بشكل مستقل من عناصر التحكم الحالية في المحرر.
- إذا كان الإجراء يلبّي هذه المتطلبات، فاختر POST ونقطة نهاية V2 الواردة أدناه. تأكّد باستخدام عناصر التحكم المتاحة في حسابك من أن الطلب الصادر يتضمن Authorization: Bearer YOUR_API_KEY وContent-Type: application/json.
- أنشئ جسم JSON يضم type = name، وvalue = الاسم الأول المربوط، وoptions يحتوي على ai_mode = off. راجع معاينة الطلب للإجراء المختار: حمولة النموذج المسطّحة ليست جسم JSON في V2، حتى إذا ضُبطت ترويسة Content-Type.
- للأسماء الأولى المتغيرة استخدم عناصر التحكم في الربط أو في تسلسل JSON التي توفّرها المنصة. إذا لم يستطع الإجراء المختار الحفاظ على JSON المتداخل أو الترويسات المُصادَق عليها، فاستخدم خطوة تدعم HTTP بدلًا من كتابة المفتاح أو JSON في معاملات سلسلة الاستعلام.
| إعداد HTTP | القيمة | الغرض |
|---|---|---|
Method | POST | يرسل طلب تقدير واحدًا. |
URL | https://api.genderapi.io/api/v2/gender | نقطة نهاية GenderAPI.io V2 للتقديرات الفردية. |
Authorization | Bearer YOUR_API_KEY | استبدل هذه القيمة النائبة عبر إعدادات المصادقة أو الترويسات في المنصة. |
Content-Type | application/json | يرسل كائنًا يتضمن كائن options متداخلًا، لا حقول نموذج. |
options.ai_mode | off | اختبار أول مقصود يعتمد على مجموعة البيانات فقط: يُخصم رصيد واحد عادةً، حتى في النتيجة غير المعروفة. |
راجع جسم JSON قبل الإرسال
يعرض هذا المثال إدخالًا ثابتًا، وليس نتيجة متوقعة. تحقّق أولًا من بنية الطلب، ثم استبدل value بالحقل المصدر المربوط مع تسلسل JSON صحيح. لا ترسل تعبيرات الربط الخاصة بالمنصة إلى API كنص حرفي.
لإدخالات أخرى اضبط type على name أو email أو username وضع القيمة المقابلة في value. أضف country فقط إذا كان لديك سياق موثوق؛ فهذا الحقل اختياري ولا يحدد بلد إقامة الشخص.
{
"type": "name",
"value": "Alice",
"options": {
"ai_mode": "off"
}
}تحقّق من خطوة HTTP قبل تفعيل التحديثات
اختبر إجراءً واحدًا بشكل محدود وافحص الجسم المُعاد قبل اختيار الحقول في الخطوات اللاحقة. قد تعرض خطوات GenderAPI.io الأصلية وخطوات Webhook/API تسميات حقول مختلفة، حتى للعميل المصدر نفسه.
احفظ المفتاح في عناصر التحكم المخصّصة للاتصال أو لمصادقة الطلب، وقيّد من يمكنه رؤية الأتمتة أو مشاركتها. لا يتضمن هذا الدليل العام مفتاحًا صالحًا ولا اتصالًا مُصدَّرًا ولا تحديثًا معدًّا مسبقًا للعملاء.
تعامل مع نتائج identified والنتائج غير المعروفة والأخطاء كلٌّ على حدة
حلّل جسم الاستجابة قبل اختيار أي تحديث في النظام الهدف. تشير مسارات JSON في الجدول أدناه إلى جسم استجابة V2؛ وقد تغلّفه منصتك داخل كائن آخر أو تسطّحه. تحقّق من البنية الفعلية باختبار محدود، واحفظ النتيجة مع id السجل المصدر.
لا يحدد التقدير هوية الشخص ولا الجنس الذي يصرّح به الشخص. احفظه منفصلًا عن البيانات التي يقدّمها الشخص بنفسه. حدّد معايير القبول ببيانات تمثّل حالة استخدامك، وقيّم درجة الثقة المستمدة من مجموعة البيانات ودرجة الثقة الصادرة عن الذكاء الاصطناعي كلًّا على حدة.
| التحقق | القيمة أو النوع المتوقع | القرار في سير العمل |
|---|---|---|
meta.access.mode | api_key لسير العمل المرتبط بالحساب | إذا كانت القيمة ip_trial، فأوقف سير العمل وأصلح المفتاح. لا تثبت الاستجابة الناجحة عبر التجربة حسب عنوان IP أن المصادقة تمت بالحساب، وقد تكون أرصدة التجربة قد استُهلكت بالفعل. |
meta.usage.billing_status | confirmed أو unconfirmed | إذا كانت القيمة unconfirmed، فاحفظ id الطلب وتحقّق من حالة الخصم قبل إعادة المحاولة أو المتابعة. |
data.result_status / data.gender | identified مع male أو female؛ النتيجة غير المعروفة مع null | احفظ نتائج identified المقبولة في حقل مخصص للبيانات المُستنتجة. أبقِ النتيجة غير المعروفة كما هي دون إسناد فئة افتراضية إليها. |
data.confidence / data.confidence_kind | رقم من 0 إلى 1 أو null؛ نوع الدليل أو null | فسّر observed_frequency وmodel_reported كلًّا على حدة؛ ولا يضمن أيٌّ منهما دقة عامة. |
data.source / data.sample_count | dataset أو ai أو none / عدد صحيح أو null | احفظ مصدر التقدير. لا يملك الذكاء الاصطناعي حجم عينة مخزّنًا، وحجم العينة في مجموعة البيانات ليس مقياسًا لدقة المنتج. |
meta.request_id / meta.usage | مرجع الطلب / كائن الاستخدام | احفظ كليهما مع سجل سير العمل والنتيجة. لا تكتب مفاتيح API أو بيانات شخصية غير ضرورية في السجلات العادية. |
خطأ HTTP / غياب الاستجابة | Problem Details أو استجابة غير مكتملة | أوقف التحديث وتحقّق من الخطأ ومن حالة الخصم. لا يثبت انتهاء المهلة أن الخادم لم يعالج شيئًا. |
حدّث السجل المطابق فقط في Mailchimp
استخدم id الجمهور (Audience) وid المشترك المحفوظين في Mailchimp لاختيار السجل الهدف. أضف شروطًا على حالة النتيجة وعلى فحوصات الوصول والخصم الموضحة أعلاه قبل الكتابة في حقل مخصص للبيانات المُستنتجة أو في وسم معتمد. لا تحوّل أبدًا جنسًا مفقودًا أو القيمة null إلى فئة افتراضية لجهة الاتصال.
اختبر فروع النتيجة identified والنتيجة غير المعروفة والخطأ كلًّا على حدة قبل تفعيل التحديثات. تتيح لك استجابات نموذجية وهمية التحقق من شروط التفرّع دون إرسال تقدير جديد. يجب أن يعتمد التحديث في التطبيق الهدف على هذه الفحوص، وألّا يستبدل حقولًا أو وسومًا غير ذات صلة.
تحكّم في إعادة المحاولة وتكرار الخصم
توثّق Integrately إعادة المحاولة التلقائية، بما في ذلك إعدادات تسري على مستوى الشركة بالكامل. تحقّق من السياسة ومن سجل النشاط قبل تفعيل هذه الأتمتة، وقيّم أثر أي تغيير في إعداد مشترك على مسارات العمل الأخرى قبل إجرائه. كل طلب HTTP مكرر طلب مستقل تُخصم عليه الأرصدة؛ احفظ المخرجات الناجحة لتتمكن من إصلاح فشل لاحق في Mailchimp دون طلب جديد.
كل طلب جديد إلى GenderAPI عملية مستقلة. أزِل أحداث المصدر المكررة في سير العمل قبل الإرسال، مستعينًا بمعرّف id المصدر المحفوظ وحالة المعالجة. ليس معرّف id لسجل المصدر مفتاحًا يمنع التكرار على الخادم.
النتيجة غير المعروفة الناجحة نتيجة مكتملة تُخصم أرصدتها. عند انتهاء المهلة أو وصول استجابة ناقصة، قد تكون النتيجة والخصم كلاهما غير معروفين: احفظ مرجع الطلب إن توفّر، وتحقّق من الخصم قبل إعادة إرسال الطلب. التزم بترويسة Retry-After عندما ترافق استجابة تجاوز حدود الطلبات.
متى تستخدم الذكاء الاصطناعي
forceToGenderize اختياري للأسماء وعناوين البريد الإلكتروني وأسماء المستخدمين. عند تفعيله، احذف ai_mode أو استخدم fallback؛ فلا يمكن الجمع بينه وبين off أو always، ويعيد ذلك 422. يكفي رصيد ابتدائي موجب لبدء الطلب، حتى لو جعل الخصم النهائي الرصيد سالبًا.
قد يعيد وضع الأسماء المستعارة جنسًا مع name: null، وقد يعطي أيضًا نتيجة غير معروفة. لا يضمن الرجوع العادي إلى الذكاء الاصطناعي ولا تفسير الأسماء المستعارة إجابة صحيحة أو قيمة غير null.
| خيار الطلب | السلوك | الأرصدة لكل بحث ناجح |
|---|---|---|
| options.ai_mode: off | يستخدم مجموعة البيانات فقط. | 1، حتى للنتيجة غير المعروفة |
| options.ai_mode: fallback | يبحث في مجموعة البيانات أولًا، ثم يستخدم الذكاء الاصطناعي العادي إذا لم يُعَد جنس. وهو الإعداد الافتراضي للطلبات الفردية. | 1 إجمالًا، بما في ذلك الرجوع إلى الذكاء الاصطناعي |
| options.ai_mode: always | يستخدم الذكاء الاصطناعي مباشرة. | 2 |
| forceToGenderize: true | يبحث في مجموعة البيانات أولًا، ثم يترك للذكاء الاصطناعي تفسير اسم مستعار شخصي أو كنية، حتى دون اسم أول حقيقي. | 1 للنتيجة الموجودة في مجموعة البيانات؛ و2 إجمالًا إذا استُخدم الذكاء الاصطناعي |
تحقّق من سير العمل قبل زيادة الحجم
- تحقّق باختبار محدود من JSON المُسلسل فعليًا، ومسارات النتائج المُحلَّلة، والوصول بمفتاح API، وتأكيد الخصم. واختبر إن أمكن التعامل مع النتائج غير المعروفة والأخطاء باستجابات نموذجية.
- حدّد خطوات سير العمل التي تُكرَّر وحقول العملاء التي تتغير. احفظ id السجل المصدر والاستجابة المستلمة ومرجع الطلب، حتى لا يستلزم فشلٌ لاحق في النظام الهدف طلبًا جديدًا.
- فعّل أولًا تشغيلًا صغيرًا ومضبوطًا، وتحقّق من السجلات والأرصدة قبل زيادة التوازي. أرصدة GenderAPI ومهام أو عمليات منصة الأتمتة المحتسبة تكلفتان منفصلتان.
- للمعالجة المجمّعة استخدم POST /api/v2/gender/batch بما يصل إلى 50 عنصرًا مع الوصول بمفتاح API أو 10 عناصر في التجربة حسب عنوان IP. يمكن أن تجمع المصفوفة items بين الأسماء وعناوين البريد الإلكتروني وأسماء المستخدمين، مع خيارات صريحة وid فريد لكل عنصر. افحص كل نتيجة على حدة: فقد تتضمن استجابة HTTP 200 أخطاءً في عناصر منفردة. ويجب التحقق بشكل منفصل من دعم الموصّل الأصلي للطلب المجمّع.
الأسئلة الشائعة
هل يمكنني ربط الحقل probability في الإجراء الأصلي القديم بالحقل confidence في V2؟
تحقّق أولًا من قواعد الاستجابة. يعيد طلب V2 المباشر data.confidence مع data.confidence_kind، على مقياس من 0 إلى 1 أو null. لا يوجد ما يدعم افتراض أن تسميات الحقول ومقياسها في الموصّل الأصلي تطابق هذه المسارات.
هل يستخدم مثال HTTP المباشر الذكاء الاصطناعي؟
يضبط جسم الطلب الأول options.ai_mode على off. غيّر القيمة عن قصد إلى fallback لاستخدام الرجوع المعتاد إلى الذكاء الاصطناعي بتكلفة إجمالية قدرها رصيد واحد، أو إلى always لاستخدام الذكاء الاصطناعي مباشرة بتكلفة 2 رصيد. يبحث forceToGenderize في مجموعة البيانات أولًا: يكلّف رصيدًا واحدًا إذا حُلّ الطلب هناك، أو 2 رصيد إجمالًا إذا استُخدم الذكاء الاصطناعي.
هل النتيجة غير المعروفة مجانية، وهل يمكن إعادة إرسالها تلقائيًا بأمان؟
لا. النتيجة غير المعروفة الناجحة نتيجة مكتملة تُخصم عليها الأرصدة. كل إعادة محاولة هي بحث جديد. عند حدوث خطأ في النقل أو عدم تأكيد الخصم، راجع بيانات الاستخدام المُعادة ومرجع الطلب قبل أن تقرر إعادة إرساله.
هل شُغّل سير العمل هذا بحساب مرتبط؟
لا. رُوجعت تعليمات إعداد المنصات في 26 سبتمبر 2026 استنادًا إلى وثائقها العامة. ورُوجعت شروح طلب GenderAPI.io V2 واستجابته في 27 سبتمبر 2026. أما مراجعة هذه النسخة العربية في 29 سبتمبر 2026 فهي تدقيق للترجمة، وليست اختبارًا جديدًا بحساب. قبل تفعيل التحديثات في بيئة الإنتاج، تحقّق في حسابك من الحقول الحالية للإجراء المختار، والمصادقة، وجسم الطلب، والاستجابة، وسلوك إعادة المحاولة.
المصادر والوثائق
رُوجعت النسخة العربية آخر مرة في . تستند معلومات المنصات إلى وثائقها العامة التي رُوجعت في 26 سبتمبر 2026، ولا تُعد هذه المراجعة اختبارًا جديدًا بحساب مرتبط. تحقّق من الإعداد الحالي ومن التوفر في الوثائق الرسمية للمنصة.