المصادقة

استخدم مسار الوصول المعتمد في مؤسستك للحصول على مفتاح API وقيم الاتصال المهيأة لبيئتك.

قبل أن تبدأ

جهّز هذه المتطلبات:

احصل على بيانات الاعتماد

احصل على القيم التالية وهيئها عبر مسار الوصول المعتمد في مؤسستك:

• API_KEY: الاعتماد الخاص بالعمليات المحمية، مع قدرات الكلام التي يحتاجها تكاملك.
• API_URL: عنوان الخدمة المخصص للبيئة.
• API_PATH: تجاوز اختياري لمسار Socket.IO. يستخدم SDK المنشور /socket.io افتراضيًا؛ ولم تُوحّد نقطة النهاية القديمة sautech.humain.com بعد، ولذلك ما زالت تتطلب /realtime/socket.io.

لا تخمّن عنوانًا أو مسارًا من بيئة أخرى. استخدم فقط القيم المهيأة للبيئة التي يعمل فيها التكامل.

خزّن بيانات الاعتماد

في جلسة Bash محلية، اضبط القيم غير السرية واقرأ المفتاح من دون إظهاره أو وضعه في سجل أوامر الصدفة:

export API_URL="https://api.voice.humain.com"
read -rsp "HUMAIN Voice API key: " API_KEY
export API_KEY
printf '\n'

في الخدمة المنشورة، مرّر API_KEY من مدير أسرار أو متغير بيئة محمي. لا تضعه في التحكم بالمصدر أو متغيرات البيئة المكشوفة للعميل أو عناوين URL أو السجلات أو لقطات الشاشة أو رسائل الدعم. لا تطبع المتغير لتتأكد من ضبطه.

اضبط API_PATH فقط عندما يتجاوز نشرك القيمة الافتراضية /socket.io في SDK. تتطلب نقطة النهاية القديمة sautech.humain.com المسار /realtime/socket.io. لا يستخدمه Batch REST.

أرسل Origin في Socket.IO

تتطلب مصافحة Socket.IO ترويسة Origin حتى من العملاء غير المتصفحين الذين لا يضبطونها تلقائيًا. أرسل مخطط ومضيف عنوان الخدمة المخصص لبيئتك.

يشتق SDK 0.18.0 ترويسة Origin من api_url ويضبطها في مصافحة Socket.IO. أما عميل Socket.IO المباشر فعليه إرسال الترويسة بنفسه مضبوطة على مخطط API_URL ومضيفه. تتطلب عمليات Batch REST وRealtime HTTP ترويسة x-api-key؛ ولا يتطلب عقد OpenAPI المنشور لها Origin.

شغّل تشخيصًا غير معدّل للحالة

افحص المسار وبيانات الاعتماد المهيأة من دون رفع صوت أو فتح تدفق.

اقرأ معرّف عمل Batch غير موجود عمدًا

اقرأ معرّف مهمة صحيح البنية وغير مرتبط بمهمة حقيقية:

curl -sS -i \
  "$API_URL/v1/transcribe/00000000-0000-4000-8000-000000000000" \
  -H "x-api-key: $API_KEY"

لا يرفع هذا الطلب صوتًا ولا ينشئ مهمة. سجل الحالة والجسم كدليل تشخيصي من مسار الطلب المهيأ. لا يضمن العقد العام ترتيب التحقق من المصادقة والتفويض والبحث عن العمل، لذلك لا يثبت 404 وحده صلاحية بيانات الاعتماد وقدرة Batch. تعامل مع 401 و403 وفق الإجراءات التصحيحية أدناه.

تجنب curl -v في الطرفيات أو السجلات المشتركة، لأن المخرجات التفصيلية للطلب تتضمن ترويسة x-api-key.

أرسل بيانات الاعتماد

عمليات HTTP

أرسل x-api-key في كل طلب محمي عبر Batch REST أو Realtime HTTP:

curl -X POST "$API_URL/v1/transcribe/codeswitch?asr=bayan_cs_ar_en" \
  -H "x-api-key: $API_KEY" \
  -F "file=@meeting.wav"

تتطلب كل عملية منشورة حاليًا عبر Batch REST وRealtime HTTP ترويسة x-api-key.

اتصالات Socket.IO

من وقت تشغيل Node.js أو Bun موثوق، أرسل الترويستين أثناء مصافحة Socket.IO واستخدم المسار المخصص:

import { io } from "socket.io-client";

const socket = io(process.env.API_URL!, {
  path: process.env.API_PATH ?? "/socket.io",
  transports: ["websocket"],
  extraHeaders: {
    "x-api-key": process.env.API_KEY!,
    Origin: process.env.API_URL!,
  },
});

يضبط عملاء SDK المنشورون هذه المصافحة من api_url وapi_key؛ ويكون api_path اختياريًا وافتراضيًا /socket.io. ويشتقون Origin من api_url المهيأ. فضّلهم إلا إذا كنت تحتاج إلى التحكم المباشر بالبروتوكول.

عالج بيانات الاعتماد المرفوضة

تفرع وفق حالة HTTP أولًا. حلّل الرمز code القابل للمعالجة آليًا عندما تحتوي الاستجابة خطأ منصة منظمًا، واحتفظ باستجابة البوابة أو المصادقة غير المنظمة للتشخيص. لا تتفرع بناءً على نص الرسالة.

قد يرفض Socket.IO الاتصال أو يصدر حدث error بحسب وقت فشل التحقق. أوقف إرسال الصوت، وافحص قيم البيئة والقدرة نفسيهما، ثم أعد الاتصال فقط بعد تصحيح الإعداد.

تعامل مع مفتاح مكشوف أو غير مستخدم

إذا ظهر المفتاح في التحكم بالمصدر أو شيفرة العميل أو عنوان URL أو سجل أو موقع آخر غير موثوق، فاعتبره مكشوفًا:

1. أوقف استخدام المفتاح واحذفه من الإعداد الفعال والمواقع المكشوفة. حذف نسخة ظاهرة واحدة لا يجعل المفتاح آمنًا من جديد.
2. أبلغ عن التعرض عبر مسار الوصول المعتمد في مؤسستك من دون تضمين بيان الاعتماد في البلاغ، واتبع تعليمات الاستجابة المقدمة هناك.
3. إذا صدر بديل، فحدّث السر على الخادم وأعد تشغيل أو نشر كل وقت تشغيل موثوق استخدم القيمة القديمة.
4. احذف النسخ القديمة من مخازن الأسرار وإعدادات النشر، ثم اختبر عملية ممثلة باستخدام الإعداد الفعال.

للمفتاح غير المستخدم، أوقف استخدامه واتبع مسار الوصول المعتمد نفسه لإجراء الإيقاف المتبع في مؤسستك.

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

بعد أن ينتج التشخيص الاستجابة المتوقعة للبيئة المهيأة، أكمل أول عملية نسخ عبر البدء السريع لـ SDK أو راجع سلوك وسائل النقل المباشرة.