في المرة الأولى التي تقوم فيها بتشغيل apidog run ويتوقف مع رسالة "لم يتم العثور على رمز وصول"، فإنك تصطدم بالجزء الوحيد من سير عمل سطر الأوامر الذي لا يحذرك أحد بشأنه. الأعلام، معرفات السيناريوهات، والمبلغون جميعها سهلة النسخ من علامة تبويب. المصادقة هي الخطوة التي يتعطل فيها أمر منسوخ على جهازك، أو يسرب سرًا إلى سجل، أو يعمل بهدوء على جهاز الكمبيوتر المحمول الخاص بك ويفشل في CI لأسباب لا يشرحها رسالة الخطأ.
يُعد هذا الدليل هو الإجابة المخصصة لتلك الخطوة. واجهة سطر الأوامر لـ Apidog هي حزمة npm، apidog-cli، التي تشغل سيناريوهات اختبار API التي تبنيها في تطبيق Apidog مباشرة من المحطة الطرفية. نظرًا لأن هذه السيناريوهات تعيش في حسابك، يجب على واجهة سطر الأوامر إثبات أنها مسموح لها بجلبها وتشغيلها، وتقوم بذلك باستخدام رمز وصول. اضبط التعامل مع الرمز بشكل صحيح مرة واحدة وكل تشغيل بعد ذلك سيكون أمرًا بسيطًا وواضحًا. إذا أخطأت، فستواجه نفس خطأ المصادقة في ثلاث بيئات مختلفة.
سوف نغطي جميع الجوانب: إنشاء رمز وصول، تسجيل الدخول باستخدام apidog login، التحقق من هويتك كمسجل دخول باستخدام apidog whoami، مكان تخزين الرمز، كيفية تحديد apidog run للرمز الذي يجب استخدامه، والجزء الذي يخطئ فيه معظم الفرق، وهو التعامل مع هذا الرمز كسر في CI بدلاً من لصقه في ملف المسار. تعيش آليات التثبيت في دليل منفصل؛ هذا الدليل يتناول المصادقة فقط. إذا لم تكن قد قمت بتثبيت واجهة سطر الأوامر بعد، ابدأ بـ دليل تثبيت واجهة سطر الأوامر لـ Apidog، ثم عد إلى هنا.
لماذا تحتاج واجهة سطر الأوامر إلى رمز على الإطلاق
لا تحتوي واجهة سطر الأوامر على اختبارات خاصة بها. بل تصل إلى مشروعك في Apidog، وتجد سيناريو حسب المعرف، وتشغله بنفس الطريقة التي يشغلها بها تطبيق سطح المكتب. هذا التصميم هو السبب الذي يجعلها تحتاج إلى المصادقة: فسيناريو الاختبار، وقيم البيئة، وتأكيدات الاختبار كلها تعيش على جانب الخادم في حسابك، لذا يجب على المشغل تعريف نفسه قبل أن يسلم الخادم أيًا من ذلك.
رمز الوصول هو كيف تعرف واجهة سطر الأوامر نفسها. يرتبط الرمز بحسابك في Apidog، لذا يمكن للتشغيل المصادق عليه باستخدام رمزك أن يفعل ما يمكنك فعله: قراءة مشاريعك، جلب سيناريوهاتك، تنفيذها مقابل البيئات التي حددتها. هذا هو السبب أيضًا في أن الرمز هو بيانات اعتماد يجب أن تحميها. يمكن لأي شخص يمتلكه تشغيل سيناريوهات باسمك، مقابل أي بيئات تستهدفها تلك السيناريوهات. تعامل معه بالطريقة التي تتعامل بها مع رمز وصول شخصي لأي خدمة أخرى.
هذا نوع مختلف من المصادقة عن المصادقة التي تجريها اختباراتك. من المحتمل أن ترسل سيناريوهاتك رموز حامل خاصة بها أو مفاتيح API إلى نقاط النهاية قيد الاختبار، وهذا اهتمام منفصل يتم تغطيته في أساليب مصادقة API. يقوم رمز الوصول الخاص بواجهة سطر الأوامر بمصادقة المشغل لدى Apidog. تقوم بيانات الاعتماد داخل طلباتك بمصادقة طلباتك إلى واجهة برمجة التطبيقات الخاصة بك. حافظ على الفصل بينهما، لأنهما يعيشان في أماكن مختلفة ويتناوبان وفق جداول زمنية مختلفة.
الخطوة 1: إنشاء رمز وصول
يمكنك إنشاء الرمز في Apidog، وليس من واجهة سطر الأوامر. هناك مكانان يظهر فيهما الرمز، وأي منهما تستخدمه يعتمد على ما تفعله.
للحصول على رمز خاص بحسابك ستعيد استخدامه عبر السيناريوهات، افتح تطبيق Apidog أو وحدة تحكم الويب، انقر على صورتك الرمزية (الأفاتار)، وابحث ضمن إعدادات حسابك عن قسم رمز وصول API.
قم بإنشاء واحد، وانسخه فورًا، وخزنه في مكان آمن مثل مدير كلمات المرور. عادة لا يمكنك رؤية السلسلة الكاملة مرة أخرى بعد مغادرة الصفحة، وهذا أمر طبيعي لبيانات الاعتماد وسبب لنسخها لحظة ظهورها.
بالنسبة لرمز مرتبط بسيناريو معين تقوم بربطه بـ CI، هناك مسار أسرع. افتح سيناريو الاختبار، انتقل إلى علامة التبويب CI/CD الخاصة به، اختر خيار سطر الأوامر، وانقر لإنشاء رمز وصول. يقوم Apidog ببناء الأمر apidog run كاملاً لك مع الرمز، ومعرف السيناريو، ومعرف البيئة المملوءة مسبقًا. هذا الأمر الذي تم إنشاؤه هو نقطة البداية الأساسية، ونسخه يعني أنك لن تكتب أي معرف يدويًا. يوضح دليل Apidog CLI الشامل علامة التبويب CI/CD هذه بالتفصيل.
في كلتا الحالتين، يكون الناتج هو نفسه: سلسلة رمز. ما تفعله به بعد ذلك هو الخيار بين نمطين للمصادقة.
الخطوة 2: اختر نمط المصادقة الخاص بك
تدعم واجهة سطر الأوامر طريقتين لتقديم الرمز، وهما يناسبان مواقف مختلفة.
الأول هو تسجيل دخول مخزن. تقوم بتشغيل apidog login مرة واحدة، تقوم واجهة سطر الأوامر بحفظ الرمز على جهازك، وكل apidog run لاحق يقرأه تلقائيًا. لا يوجد رمز في أي سطر أوامر بعد ذلك. هذا هو ما تريده على جهاز مطور تستخدمه يوميًا.
الثاني هو لكل أمر. تقوم بتمرير --access-token عند استدعاء apidog run نفسه، عادة من متغير بيئة. لا يتم تخزين أي شيء، يتم توفير الرمز جديدًا في كل مرة، ولا يترك أي أثر على القرص. هذا هو ما تريده في CI، حيث يكون المشغل مؤقتًا ويأتي الرمز من سر.
من المحتمل أن تستخدم كليهما، تسجيل الدخول المخزن محليًا ولكل أمر في المسار. يغطي القسمان التاليان كل منهما.
الخطوة 3: تسجيل الدخول محليًا باستخدام apidog login
على جهازك الخاص، قم بتسجيل الدخول مرة واحدة وانسَ أمر الرمز. يطلب منك النموذج التفاعلي إدخاله حتى لا تظهر السلسلة أبدًا في سجل الأوامر الخاص بك:
apidog login
تطلب واجهة سطر الأوامر رمز الوصول الخاص بك، تقوم بلصقه، ثم تضغط على Enter. خلف الكواليس، تقوم بالتحقق من صحة الرمز مقابل Apidog قبل حفظ أي شيء؛ يتم رفض الرمز غير الصالح أو منتهي الصلاحية على الفور بدلاً من الفشل لاحقًا في أول تشغيل لك. عند النجاح، تؤكد الحساب الذي تم تسجيل الدخول به وتخبرك بمكان تخزين بيانات الاعتماد.
إذا كنت تفضل تمرير الرمز مباشرة، على سبيل المثال داخل نص برمجي للإعداد، فاستخدم العلامة --with-token:
apidog login --with-token YOUR_ACCESS_TOKEN
تحذير واحد بخصوص هذا الشكل: الرمز الموجود في سطر الأوامر يظهر في سجل أوامر shell الخاص بك ويمكن قراءته من قائمة العمليات أثناء تشغيل الأمر. فضل استخدام apidog login التفاعلي للاستخدام اليدوي، واحتفظ بـ --with-token للإعدادات غير التفاعلية حيث تقرأ القيمة من متغير تتحكم فيه. لا تضع أبدًا رمزًا حقيقيًا في نص برمجي تقوم بتثبيته (commit).
أين يذهب الرمز؟ تكتبه واجهة سطر الأوامر إلى ملف تكوين ضمن دليل .apidog في مجلدك الرئيسي. هذا هو مخزن بيانات اعتماد محلي على جهازك الخاص، وهذا هو الهدف بالضبط: الرمز يجلس على القرص حيث يمكن لحساب المستخدم الخاص بك فقط قراءته، وتلتقطه واجهة سطر الأوامر في كل تشغيل لاحق دون الحاجة إلى إعادة كتابته. إذا كنت على جهاز مشترك أو مؤقت، فتجاوز تسجيل الدخول المخزن واستخدم الرمز لكل أمر بدلاً من ذلك، حتى لا يبقى أي شيء بعد مغادرتك.
الخطوة 4: التحقق باستخدام apidog whoami
بعد تسجيل الدخول، تأكد من أنه يعمل قبل الاعتماد عليه:
apidog whoami
يطبع هذا الحساب الذي تم مصادقة واجهة سطر الأوامر به حاليًا. إنها أسرع طريقة للإجابة على سؤال "هل أنا مسجل الدخول، وباسم من؟" دون تشغيل سيناريو حقيقي. استخدمها كلما فشل تشغيل بسبب خطأ مصادقة ولم تكن متأكدًا مما إذا كانت المشكلة في الرمز أو في شيء آخر؛ إذا أظهر whoami حسابك، فإن تسجيل الدخول المخزن على ما يرام ويمكنك البحث في مكان آخر.
يقبل apidog whoami أيضًا --access-token إذا كنت ترغب في التحقق من رمز معين بدلاً من الرمز المخزن. وهذا مفيد لتأكيد صلاحية رمز CI قبل الوثوق به في المسار: الصق الرمز في أمر apidog whoami --access-token YOUR_ACCESS_TOKEN لمرة واحدة من محطة آمنة، وشاهد إلى أي حساب يشير، ثم انقله إلى مخزن الأسرار الخاص بك.
عند الانتهاء من العمل على جهاز مشترك، أو عندما ترغب في التبديل إلى حساب مختلف، قم بمسح بيانات الاعتماد المخزنة:
apidog logout
هذا يزيل الرمز المحفوظ من ملف التكوين. سيتطلب apidog run التالي تسجيل دخول جديدًا أو علامة --access-token، وهذا هو السلوك الذي تريده بعد إعادة الجهاز.
الخطوة 5: كيف يختار apidog run رمزًا
بمجرد فهمك للترتيب الذي يتحقق به المشغل، يتوقف خطأ "لم يتم العثور على رمز وصول" عن كونه غامضًا. عندما تستدعي apidog run، تبحث واجهة سطر الأوامر عن رمز بهذا الترتيب:
- علامة
--access-tokenالممررة في الأمر، إذا كانت موجودة. - الرمز المخزن على القرص من تسجيل دخول سابق لـ
apidog login.
إذا لم يجد أيًا منهما، فإنه يتوقف ويطلب منك تشغيل login أولاً أو تمرير --access-token. هذا التفضيل مفيد: العلامة تفوز دائمًا على تسجيل الدخول المخزن، لذا يمكنك أن تكون مسجلاً دخولك كشخصك يوميًا ومع ذلك تجاوز ذلك برمز مختلف لتشغيل لمرة واحدة دون تسجيل الخروج.
في الممارسة العملية، هذا يعني أن عمليات التشغيل المحلية الخاصة بك يمكن أن تكون قصيرة مثل المعرفات:
apidog run -t 605067 -e 1629989 -n 1 -r cli
لا يوجد رمز في هذا السطر، لأن تسجيل الدخول المخزن يوفره. يشير -t إلى السيناريو بواسطة المعرف، ويحدد -e البيئة، ويقوم -n 1 بتشغيله مرة واحدة، ويطبع -r cli تقريرًا قابلاً للقراءة. قارن ذلك بشكل CI، حيث تمرر الرمز صراحة لأنه لا يوجد شيء مخزن:
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -e 1629989 -r junit,cli
نفس الأمر، نفس السيناريو، مصدر مصادقة مختلف. هذا هو الفارق بين المصادقة المحلية ومصادقة CI، وبقية هذا الدليل تدور حول كيفية إعداد جزء CI بشكل صحيح. للحصول على المرجع الكامل للأعلام وراء هذه العمليات، يغطي دليل Apidog CLI الشامل كل خيار.
الخطوة 6: التعامل مع الرمز كسر في CI
هذا هو المكان الذي تتعثر فيه الفرق. الحل هو قاعدة واحدة: يجب أن يكون الرمز موجودًا في مخزن الأسرار الخاص بنظام CI لديك، ويصل إلى الأمر كمتغير بيئة. لا يظهر أبدًا في ملف ملتزم به، أو تعريف مسار تم فحصه في المستودع، أو سجل بناء.
لا تسجل الدخول داخل CI، ولا تكتب الرمز في ملف يقوم المشغل بإنشائه. استخدم نموذج --access-token لكل أمر، الذي يتم تغذيته من سر مقنّع. يتبع كل مثال أدناه نفس الشكل، حيث يتم تسمية السر مرة واحدة في المنصة، ويتم الإشارة إليه كـ $APIDOG_ACCESS_TOKEN في خطوة التشغيل.
إجراءات GitHub
خزّن الرمز تحت إعدادات المستودع، في قسم الأسرار والمتغيرات، ثم قم بتعريضه للخطوة من خلال env:
- name: Run API test scenario
run: |
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 605067 \
-e 1629989 \
-r junit,cli
env:
APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
يقوم GitHub بإخفاء السر في السجلات تلقائيًا، وتمريره عبر env يبقيه بعيدًا عن سطر الأوامر المرئي. الفشل الأكثر شيوعًا هنا هو عدم تطابق الاسم: يجب أن يستخدم مفتاح env، ومرجع ${{ secrets.X }}، والسر الذي أنشأته في الإعدادات جميعها نفس الاسم. يعيش سير العمل الكامل، بما في ذلك مخرجات التقارير، في Apidog CLI في إجراءات GitHub.
GitLab CI
قم بتخزين APIDOG_ACCESS_TOKEN كمتغير CI/CD مقنّع ومحمي ضمن الإعدادات، ولا تضعه أبدًا في ملف .gitlab-ci.yml. ثم أشر إليه مباشرة، حيث يقوم GitLab بحقن متغيرات المشروع في بيئة المهمة:
api-tests:
stage: test
image: node:20
script:
- npm install -g apidog-cli
- apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -e 1629989 -r junit,cli
تعليم المتغير بأنه "مقنّع" يخبر GitLab بحجبه من سجلات المهام؛ وتعليمه بأنه "محمي" يبقيه بعيدًا عن الفروع غير المحمية، بحيث لا يمكن لفرع ثانوي أو فرع ميزة تسريبه.
Jenkins
خزّن الرمز كاعتماد Jenkins، ثم اربطه في كتلة environment بحيث يكون متاحًا كمتغير دون أن يتم طباعته أبدًا:
pipeline {
agent any
environment {
APIDOG_ACCESS_TOKEN = credentials('apidog-access-token')
}
stages {
stage('API tests') {
steps {
sh 'apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r junit,cli'
}
}
}
}
يقوم Jenkins بإخفاء بيانات الاعتماد المرتبطة بهذه الطريقة في مخرجات وحدة التحكم. إذا قمت ببناء المسار الكامل حول هذه الخطوة، فإن Apidog CLI في مسار CI/CD يغطي الهيكل المحيط.
النمط متطابق عبر كل مشغل: سر مقنّع في المنصة، ومتغير بيئة في الأمر، وعلامة --access-token تقرأ منه. هذا هو نفس الانضباط الذي ستطبقه على أي بيانات اعتماد في المسار، ويستحق قراءة أفضل الممارسات لإدارة مفاتيح API إذا كنت تدير أكثر من واحد.
تدوير وسحب الرموز
الرموز ليست أبدية. قم بتدويرها وفق جدول زمني واسحبها لحظة احتمال تسرب أحدها.
للتدوير، قم بإنشاء رمز جديد في Apidog، وحدّث السر في كل نظام CI يستخدمه، وقم بتشغيل مسار عمل (pipeline) لتأكيد أن الرمز الجديد يعمل. ثم اسحب الرمز القديم من نفس المكان الذي أنشأته فيه. محليًا، قم بتشغيل apidog logout متبوعًا بـ apidog login مع الرمز الجديد. الترتيب مهم: قم بتحديث CI قبل السحب، وإلا ستفشل عملية البناء بين الخطوتين.
اسحب الرمز فورًا إذا ظهر في مكان لا ينبغي أن يكون فيه، مثل سجل، أو لقطة شاشة، أو التزام (commit)، أو محطة طرفية مشتركة. يؤدي السحب إلى إبطال الرمز في كل مكان دفعة واحدة، لذا فإن أي مسار عمل لا يزال يستخدم القيمة القديمة سيفشل بصوت عالٍ، وهي الإشارة التي تريدها. البناء الفاشل قابل للاسترداد؛ أما بيانات الاعتماد الحية في سجل عام فلا يمكن استردادها. وللعادة الأوسع، تغطي أفضل الممارسات لتدوير مفاتيح API من أجل أمان محسن الوتيرة.
فخ خفي واحد: إعادة إنشاء رمز في Apidog يبطل الرمز السابق. إذا قمت بإعادة إنشاء ونسيت تحديث سر CI، فسيبدأ مسار العمل هذا بالفشل مع خطأ مصادقة على الرغم من عدم تغيير أي شيء في YAML. عندما يفشل بناء كان يعمل سابقًا فجأة في المصادقة ولم تلمس ملف سير العمل، فإن الرمز الذي تم تجديده هو أول ما يجب التحقق منه.
عندما تفشل المصادقة
تتجمع أخطاء المصادقة في بضعة أسباب. إليك كيفية التمييز بينها.
"لم يتم العثور على رمز وصول." لم تجد واجهة سطر الأوامر لا علامة --access-token ولا تسجيل دخول مخزن. محليًا، قم بتشغيل apidog login. في CI، تأكد من ملء السر وأن علامة --access-token تقرأ منه؛ فمتغير البيئة الفارغ ينتج نفس هذه الرسالة.
"رمز وصول غير صالح" أو خطأ مصادقة في منتصف التشغيل. الرمز خاطئ، أو منتهي الصلاحية، أو تم سحبه. قم بتشغيل apidog whoami للتحقق من الرمز المخزن، أو apidog whoami --access-token YOUR_TOKEN للتحقق من رمز معين. إذا لم يؤدِ أي منهما إلى حسابك، فأنشئ رمزًا جديدًا وسجل الدخول مرة أخرى.
يعمل محليًا، ويفشل في CI. عدم التطابق الكلاسيكي. جهازك لديه تسجيل دخول مخزن، لذا تنجح عمليات التشغيل المحلية؛ لكن مشغل CI ليس لديه شيء مخزن ويعتمد بالكامل على السر. تأكد من أن اسم السر يتطابق تمامًا بين إعدادات المنصة والأمر، وأن القيمة تم حفظها بدون مسافة زائدة أو سطر جديد في النهاية، وهو أمر سهل الوقوع فيه عند اللصق.
"تم رفض الوصول" على سيناريو معين. الرمز صالح ولكن الحساب وراءه لا يمكنه الوصول إلى هذا المشروع. تحقق من معرفات المشروع والسيناريو، وتأكد من أن حساب الرمز لديه وصول إلى هذا المشروع. هذه مشكلة ترخيص، وليست مشكلة مصادقة؛ لقد أثبتت واجهة سطر الأوامر هويتها، لكن الخادم لن يسمح لهذا الحساب بتشغيل هذا السيناريو.
يصل الرمز إلى الأمر لكن عملية البناء لا تزال تسربه. إذا رأيت الرمز الخام في سجل (log) في أي وقت، فأنت تقوم بعرضه في مكان ما، غالبًا في سطر تصحيح يطبع الأمر الكامل أو البيئة. قم بإخفائه (mask it): اطبع طول الرمز للتأكد من أنه ممتلئ، وليس قيمته أبدًا. تقوم معظم منصات CI بحجب الأسرار المعروفة تلقائيًا، ولكن استخدام أمر echo يدويًا للأمر بأكمله يمكن أن يبطل ذلك.
أين تتناسب المصادقة مع سير العمل الأكبر
المصادقة هي البوابة الصغيرة التي تُفتح لمرة واحدة وتجعل كل شيء لاحقًا ممكنًا. بمجرد أن تتمكن واجهة سطر الأوامر من إثبات هويتها، يصبح تشغيل سيناريو Apidog أمرًا واحدًا، محليًا ضمن حلقة التعديل والاختبار الخاصة بك، وفي CI مع كل عملية دفع، وحتى داخل وكيل ترميز ذكاء اصطناعي يقوم بتشغيل اختباراتك نيابة عنك. يستحق هذا النمط الأخير نظرة إذا كنت تعمل مع الوكلاء: يوضح كيفية استخدام وكلاء الذكاء الاصطناعي لاختبار API كيف تسمح واجهة سطر الأوامر التي تم تسجيل الدخول إليها لوكيل بتشغيل سيناريوهاتك وقراءة النتيجة، ويقوم خادم Apidog MCP بربط مواصفاتك بهؤلاء الوكلاء مباشرة.
النموذج الذهني بسيط. سجل الدخول مرة واحدة على جهازك باستخدام apidog login، وتحقق باستخدام apidog whoami، ودع الرمز المخزن يدعم كل تشغيل لاحق. في CI، تخطى تسجيل الدخول، واحتفظ بالرمز في سر مقنّع، ومرره لكل أمر باستخدام --access-token. قم بالتدوير بانتظام، واسحب الرمز عند الشك، وحدث CI قبل السحب. هذه هي قصة المصادقة بأكملها، ومع التعامل معها، تتلاشى واجهة سطر الأوامر في الخلفية حيث ينتمي مشغل الاختبار الجيد.
تواصل تأليف السيناريوهات بصريًا في Apidog، وتقوم واجهة سطر الأوامر بتشغيلها حيث لا يراقب أحد. قم بتنزيل Apidog لإعداد السيناريو الأول الخاص بك، ثم وجه المشغل إليه. لكل ما يمكن للمشغل القيام به بمجرد مصادقته، فإن دليل Apidog CLI الشامل هو المرجع الذي يجب أن يبقى مفتوحًا.