عالج الصفوف المختارة من الشريط الجانبي
تقرأ إضافة GenderAPI for Google Sheets عمودًا من الأسماء أو عناوين البريد الإلكتروني أو أسماء المستخدمين، وتكتب حقول النتائج المختارة في الورقة. ومن الشريط الجانبي يمكنك معالجة نطاق محدد وحفظ القيم دون ترك صيغة في كل خلية.
هذا هو سير العمل الخاص بالإضافة نفسها. فأعمدة النتائج فيها ومعالجتها المجمّعة مستقلة عن تنسيق الاستجابة العام لواجهة REST API في V2.
ثبّت الإضافة واربطها واختبرها على عيّنة صغيرة
- ثبّت الإضافة من صفحة التطبيق في Google Workspace Marketplace وراجع الأذونات المطلوبة. ثم افتح في Google Sheets القائمة Extensions → GenderAPI → Determine Gender.
- اختر مفتاح GenderAPI أو أدخله في الشريط الجانبي. وتحقّق من أن الحساب المختار لديه أرصدة متاحة.
- اختر الورقة والطريقة name أو email أو username. وحدّد عمود المصدر المطابق ونطاقًا صغيرًا من الصفوف دون صف العناوين.
- اختر عمودًا منفصلًا للجنس، وعند الحاجة أعمدة لـ Probability والبلد والاسم الذي عُثر عليه. ولا تكتب فوق القيم الأصلية.
- إذا كان لديك سياق جغرافي موثوق فاستخدم إعداد البلد أو عمودًا يحتوي رموز البلدان. ولا تستنتج هذا السياق من التقدير الذي توشك على طلبه.
- راجع خيار تخطّي النتائج الموجودة، ثم ابدأ المعالجة وافحص الصفوف المختارة قبل توسيع النطاق.
اربط المدخلات والوجهات
| الإعداد | النوع | الاختيار والوصف |
|---|---|---|
| مفتاح API | مُعرّف الحساب | استخدم المفتاح المختار في الإضافة وتحقّق من أنه صالح ولديه رصيد. |
| الطريقة | اختيار | name أو email أو username بحسب عمود المصدر. |
| الورقة ونطاق الصفوف | ورقة وأرقام صفوف | اختر الصفوف المراد معالجتها فقط واستبعد صف العناوين. |
| عمود المصدر | مرجع عمود | عمود الإدخال الوحيد للطريقة المختارة. |
| السياق الجغرافي | إعداد أو عمود اختياري | استخدم رموز بلدان موثوقة من حرفين عند توفرها. |
| أعمدة النتائج | مراجع أعمدة | الجنس هو الوجهة الأساسية. أما Probability والبلد والاسم الذي عُثر عليه فهي اختيارية. |
| تخطّي النتائج الموجودة | مربع اختيار | راجع هذا الإعداد حتى لا تستبدل إعادة التشغيل صفوفًا مملوءة من قبل عن طريق الخطأ. |
اقرأ أعمدة النتائج
احتفظ بالقيمة الأصلية بجانب النتيجة. فالارتباط المُستنتج من الاسم لا يحدّد الجنس الذي يصرّح به الشخص، والبلد المُعاد لا يثبت الإقامة ولا الجنسية.
- افحص نتيجة عادية وإدخالًا ملتبسًا وتشغيلًا فاشلًا قبل معالجة مجموعة البيانات كاملة.
- الخلية الفارغة والنص null وخطأ الصيغة قيم مختلفة. وحّد النتائج unknown عن وعي دون إخفاء الأخطاء.
- استخدم صياغة محايدة للحالات unknown أو غير المؤكدة، وافصل المعلومات التي يقدّمها الشخص نفسه عن التقديرات.
| النتيجة | النوع | الاستخدام |
|---|---|---|
| Gender | نص أو قيمة غير محسومة | احتفظ بـ male أو female فقط عند نجاح النتيجة. واحفظ القيمة غير المحسومة بصيغة unknown، وراجع رسائل الخطأ بشكل منفصل. |
| Probability | رقم عند توفره | مؤشر ثقة قديم. ولا يطابق حقل confidence في V2 ولا دقة مقيسة على بياناتك. |
| Country | نص عند توفره | سياق تعيده عملية البحث. احتفظ به منفصلًا عن بلد العميل المُتحقَّق منه. |
| Found / normalized name | نص عند توفره | الاسم المستخدم أو المستخرج أثناء المعالجة. راجعه عندما يكون عنوان البريد الإلكتروني أو اسم المستخدم ملتبسًا. |
خطّط للأرصدة والحدود وإعادة التشغيل
يتضمن حساب GenderAPI المجاني المسجَّل 200 رصيد يوميًا. وهذا رصيد في الحساب، وليس وعدًا بالحصول على 200 نتيجة identified في كل سير عمل. قبل البدء تحقّق من رصيد المفتاح المختار ومن خيارات المعالجة الحالية في الأداة.
تتبع الإضافات ومعالجة الملفات مسارات معالجة خاصة بها. فحدّ الطلب المجمّع في واجهة REST API في V2 وخيارات الذكاء الاصطناعي وحقول الخصم في الطلبات الفردية لا تنطبق تلقائيًا على هذه الأدوات. وقد ترسل إعادة التشغيل أو إعادة الحساب طلبات جديدة وتستهلك أرصدة، فلا تفترض أنها مجانية.
ابدأ بعيّنة صغيرة، واحفظ النتائج التي حصلت عليها، وراجع الصفوف الفاشلة قبل إعادة التشغيل. وإذا كنت تحتاج فقط إلى إصلاح تصدير أو تحديث في الوجهة، فأعد استخدام النتائج الموجودة لديك.
اختر البيانات التي تشاركها
ترسل تكاملات جداول البيانات القيم اللازمة للبحث، وتطلب أذونات على المستند المختار. قبل معالجة بيانات شخصية تحقّق ممن يمكنه الوصول إلى جدول البيانات، وأي حساب مرتبط، وأي أعمدة وجهة مستخدمة.
احفظ مفتاح API في إعدادات الإضافة، لا في خلايا عادية أو لقطات شاشة أو أمثلة مشتركة. وتصف سياسة الخصوصية المنشورة كيفية معالجة بيانات الإدخال وتخزينها وتسجيلها. ولا يعني تكامل جداول البيانات أن البيانات تبقى على جهازك وحده.
متى تستخدم V2 API مباشرة
أعدّ تكامل HTTP منفصلًا إذا كان تطبيقك يحتاج إلى خيارات صريحة للذكاء الاصطناعي وإلى معلومات status وsource وconfidence_kind وusage في V2 لكل عنصر. واتبع عقد الطلب والاستجابة في V2، إذ إن إضافة أسماء حقول V2 إلى صيغة خاصة أو إلى إضافة قائمة لا يغيّر سلوكها.
الأسئلة الشائعة
هل أحتاج إلى كتابة شيفرة لاستخدام الشريط الجانبي؟
لا. ثبّت الإضافة، واربط المفتاح، وحدّد عمود المصدر وأعمدة النتائج. أما التكامل المباشر مع V2 API فهو خيار منفصل للتطبيقات المخصّصة.
هل يمكنني معالجة صفوف موجودة؟
نعم. استخدم إعدادات الورقة ونطاق الصفوف في الشريط الجانبي. وقبل بدء المعالجة راجع صف العناوين ونوع الإدخال وأعمدة الوجهة وخيار النتائج الموجودة.
هل تطابق أعمدة النتائج استجابة JSON في V2؟
لا. تكتب المعالجة الخاصة بالإضافة الحقول المدعومة في الورقة. أما الكائنان data وmeta والحقلان source وconfidence_kind فهي جزء من عقد REST API المباشر في V2.
كيف أتعامل مع النتيجة unknown؟
احفظها بصيغة unknown وميّزها عن التشغيل الفاشل. وراجع المدخلات الملتبسة، واستخدم صياغة محايدة بدلًا من تعيين جنس تلقائيًا.
المصادر والوثائق
رُوجع هذا الدليل آخر مرة في . تحقّق من طريقة التثبيت في وثائق المنصة، واستخدم وثائق API أدناه لبناء تكامل V2 منفصل.