احصل على نتيجة من خلية واحدة
بعد تثبيت إضافة GenderAPI for Google Sheets وحفظ المفتاح في إعدادات Formula الخاصة بها، اكتب =GENDER(A2) لتحليل الاسم في الخلية A2. وبالوسيطات الاختيارية تختار عنوان بريد إلكتروني أو اسم مستخدم كمُدخل، وسياقًا جغرافيًا، وأعمدة نتائج إضافية.
GENDER صيغة خاصة بالإضافة. فهي لا تقبل كائن JSON لطلب V2 ولا تعيد بنية الاستجابة في V2.
احفظ المفتاح قبل كتابة الصيغ
- افتح Extensions → GenderAPI → Determine Gender، ثم انتقل إلى صفحة Formula من قائمة الشريط الجانبي.
- اختر مفتاح API محفوظًا أو أدخل مفتاحك واحفظه. واحتفظ ببيانات الاعتماد في الشريط الجانبي، لا في خلايا مشتركة.
- أدخل قيمة تمثيلية في A2 وضع الصيغة في خلية أخرى. واترك مساحة على اليمين إذا طلبت معلومات إضافية.
- افحص النتيجة والإرشادات الحالية في الشريط الجانبي قبل نسخ الصيغة إلى صفوف أخرى.
تأتي الوسيطات بهذا الترتيب
| الوسيطة | النوع | القيمة الافتراضية | الوصف |
|---|---|---|---|
input | نص أو مرجع خلية | إلزامية | اسم أو عنوان بريد إلكتروني أو اسم مستخدم، مثل A2. |
method | نص | name | name أو email أو username بحسب المُدخل. |
country_filter | نص | بلا فلتر بلد | رمز بلد اختياري من حرفين. استخدم سلسلة نصية فارغة لتخطّي هذه الوسيطة قبل additional_info. |
additional_info | قيمة منطقية | FALSE | تعيد TRUE حقولًا إضافية في الأعمدة المجاورة، بينما تعيد FALSE الجنس فقط. |
كل سطر صيغة مستقلة. اختر الطريقة التي تناسب القيمة في A2. توضّح هذه الأمثلة البنية فقط ولا تضمن نتيجة بعينها. وقد تستخدم الإعدادات الإقليمية للورقة الفاصلة المنقوطة بدل الفاصلة للفصل بين الوسيطات.
=GENDER(A2)
=GENDER(A2, "email")
=GENDER(A2, "username")
=GENDER(A2, "name", "IT", TRUE)
=GENDER(A2, "email", "", TRUE)اترك مساحة للنتائج الموسّعة
عند تفعيل additional_info تذكر الإرشادات الحالية في الشريط الجانبي لـ Google Sheets أربع قيم بهذا الترتيب: الجنس، والبلد، وProbability، والاسم الموحَّد. ويختلف هذا الترتيب عن ترتيب صيغ Excel. لذا راجع إرشادات الإضافة المثبّتة عند إنشاء عناوين الأعمدة.
اترك جميع خلايا الوجهة فارغة حتى تتمكن المصفوفة من التمدد. فالمصفوفة المحجوبة أو المفتاح المفقود أو خطأ المنصة مشكلات يجب حلها بشكل منفصل، وليست تقديرات نتيجتها unknown.
| الموضع | الإرشادات الحالية في Sheets | طريقة التعامل |
|---|---|---|
| 1 | Gender | احفظ النتائج غير المحسومة بصيغة unknown وميّزها عن رسائل الخطأ. |
| 2 | Country | سياق تعيده عملية البحث، وليس موقعًا مُتحقَّقًا منه. |
| 3 | Probability | احتفظ بهذه القيمة القديمة مع النتيجة، ولا تُعِد تسميتها إلى confidence في V2. |
| 4 | Normalized name | راجع الاسم المشتق من مُدخلك قبل استخدامه في مكان آخر. |
افهم إعادة الحساب وملاحظات التخزين المؤقت
الصيغة ديناميكية. فتغيير مُدخلها أو إعادة حساب الورقة قد يتطلب معالجة جديدة. وقد تضيف الإضافة ملاحظة تتضمن الصيغة والنتيجة المخزّنة مؤقتًا، لكن الملاحظة لا تضمن أن تتم كل إعادة حساب لاحقة دون طلب جديد أو دون استهلاك أرصدة.
تفرض Google حدودًا على تنفيذ الدوال المخصّصة وعلى URL Fetch بمعزل عن أرصدة GenderAPI. ووفقًا للوثائق الحالية من Google، يقتصر كل تنفيذ لدالة مخصّصة على 30 ثانية. وقد تؤدي كثرة الصيغ المتزامنة أو بطء الطلبات إلى أخطاء حتى لو كان حسابك لا يزال يملك أرصدة.
للحصول على لقطة ثابتة، انسخ النتائج المملوءة والصقها كقيم في نطاق آخر. ولا تعتمد هذه النسخة على الصيغة بعد ذلك. واحتفظ أيضًا بالمُدخل الأصلي وتاريخ المراجعة.
خطّط للأرصدة والحدود وإعادة التشغيل
يتضمن حساب GenderAPI المجاني المسجَّل 200 رصيد يوميًا. وهذا رصيد في الحساب، وليس وعدًا بالحصول على 200 نتيجة identified في كل سير عمل. قبل البدء تحقّق من رصيد المفتاح المختار ومن خيارات المعالجة الحالية في الأداة.
تتبع الإضافات ومعالجة الملفات مسارات معالجة خاصة بها. فحدّ الطلب المجمّع في واجهة REST API في V2 وخيارات الذكاء الاصطناعي وحقول الخصم في الطلبات الفردية لا تنطبق تلقائيًا على هذه الأدوات. وقد ترسل إعادة التشغيل أو إعادة الحساب طلبات جديدة وتستهلك أرصدة، فلا تفترض أنها مجانية.
ابدأ بعيّنة صغيرة، واحفظ النتائج التي حصلت عليها، وراجع الصفوف الفاشلة قبل إعادة التشغيل. وإذا كنت تحتاج فقط إلى إصلاح تصدير أو تحديث في الوجهة، فأعد استخدام النتائج الموجودة لديك.
متى تستخدم V2 API مباشرة
أعدّ تكامل HTTP منفصلًا إذا كان تطبيقك يحتاج إلى خيارات صريحة للذكاء الاصطناعي وإلى معلومات status وsource وconfidence_kind وusage في V2 لكل عنصر. واتبع عقد الطلب والاستجابة في V2، إذ إن إضافة أسماء حقول V2 إلى صيغة خاصة أو إلى إضافة قائمة لا يغيّر سلوكها.
الأسئلة الشائعة
هل اسم الصيغة GENDER_API؟
لا. توثّق إضافة Google Sheets الصيغة =GENDER(input, method, country_filter, additional_info). أما Microsoft Excel فيستخدم أسماء مختلفة: GENDER.FROM_NAME وGENDER.FROM_EMAIL وGENDER.FROM_USERNAME.
هل يمكنني طلب حقول إضافية دون فلتر بلد؟
نعم. اترك الوسيطة الثالثة فارغة، مثل =GENDER(A2, "email", "", TRUE). وعندها تتمدد الحقول الإضافية في الخلايا المجاورة.
هل تجعل ملاحظة التخزين المؤقت إعادة الحساب مجانية؟
يمكن إعادة استخدام نتيجة محفوظة، لكن الملاحظة لا تضمن أن يتم كل تشغيل لاحق دون طلب جديد. راقب الأرصدة، واحفظ قيمًا ثابتة عندما لا تحتاج إلى إعادة حساب ديناميكية.
هل يحصل كل من يعدّل جدول البيانات على الصيغة تلقائيًا؟
لا تفترض ذلك. تحقّق من أن الإضافة متاحة ومصرّح بها للمستخدمين والمستند المعنيين. وشارك نسخة تحتوي القيم فقط إذا كان المستلمون يحتاجون إلى النتائج المملوءة وحدها.
المصادر والوثائق
رُوجع هذا الدليل آخر مرة في . تحقّق من طريقة التثبيت في وثائق المنصة، واستخدم وثائق API أدناه لبناء تكامل V2 منفصل.