تخطَّ إلى المحتوى
Documentation

RTC: استخدم التخزين الخاص بك

يمكن لـ RTC نسخ كل تسجيل مكتمل إلى دلو تملكه. CHAMPREP يحتفظ بنسخته الخاصة أيضًا، لذا يظل التسجيل قابلاً للتنزيل من RTC سواء نجح التسليم أم لا.

يتم تضمين التسليم إلى التخزين الخاص بك في النمو و الأعمال المستويات. لا تشملها النسخة التجريبية المجانية، ومستوى Starter، والحد المسموح به في الخطط المدفوعة CHAMPREP. وبدونها، تستجيب مسارات التخزين 403 RTC_FEATURE_NOT_IN_PLAN مع المستويات التي تتضمنها في offers. انظر الخطط والفوترة.

إذا توقفت خطتك عن تضمينها، فإن RTC تقوم بإيقاف تشغيل وجهاتك. بعد الترقية مرة أخرى، قم بتشغيل كل واحدة منها مرة أخرى؛ حيث تقوم RTC بإجراء اختبار كتابة جديد أولاً.

النوعاستخدمه من أجلما يحتفظ به RTC
aws-role (مفضل)دلو AWS S3لا يوجد أي سر. تفترض RTC وجود دور IAM تقوم بإنشائه، مع معرّف خارجي.
s3-compatibleCloudflare R2، أو MinIO، أو Wasabi، أو Backblaze B2، أو AWS باستخدام مفاتيح الوصولمعرف مفتاح الوصول والمفتاح السري الخاصين بك، مشفرين

تنتمي الوجهة إلى مؤسستك. وهي تخدم مشروعًا واحدًا، أو كل مشروع عندما projectId هي null. يمكن أن يكون لدى المنظمة ما يصل إلى 5 وجهات؛ إجابة أخرى 409 DESTINATION_LIMIT.

إنشاء الوجهات وتغييرها واختبارها وإزالتها في وحدة التحكم RTC، أو من خلال الواجهة البرمجية (API) باستخدامAPI جلسة عمل وحدة التحكم بعد تسجيل الدخول. لا يمكن APIللمفاتيح إنشاء أو تغيير الوجهات. المفتاح الذي يمتلك recordings:read يمكنه عرض قائمة بها؛ أما مفتاح المشروع فيرى وجهات مشروعه ووجهات كل مشروع.

الطريقة والمساربيانات الاعتمادالنتيجة
GET /v1/storage/destinationsجلسة عمل وحدة التحكم، أو مفتاح مع recordings:readالوجهات، الأقدم أولاً
GET /v1/storage/destinations/{destinationId}جلسة عمل وحدة التحكم، أو مفتاح مع recordings:readوجهة واحدة
GET /v1/storage/aws-setupجلسة وحدة التحكممعرفك الخارجي وسياسات IAM المطلوب لصقها (دور AWS)
POST /v1/storage/destinationsجلسة وحدة التحكم201، الوجهة بعد اختبار الكتابة
PATCH /v1/storage/destinations/{destinationId}جلسة وحدة التحكمقم بتغيير الإعدادات، أو تدوير المفاتيح، أو تشغيلها أو إيقافها
POST /v1/storage/destinations/{destinationId}/testجلسة وحدة التحكمقم بتشغيل «test-write» مرة أخرى
DELETE /v1/storage/destinations/{destinationId}جلسة وحدة التحكم{ "id": "…", "deleted": true }
GET /v1/recordings/{recordingId}/deliveriesrecordings:readعمليات تسليم التسجيل (تتبع عمليات التسليم)
POST /v1/recordings/{recordingId}/redeliverrecordings:write202، يعيد تسليم التسجيل مرة أخرى
DELETE /v1/recordings/{recordingId}recordings:writeيرسل التسجيل إلى سلة المهملات (حذف تسجيل)
GET /v1/recordings?trashed=truerecordings:readالتسجيلات في سلة المهملات
POST /v1/recordings/{recordingId}/restorerecordings:writeاسترجاع التسجيل من سلة المهملات
POST /v1/recordings/{recordingId}/purgerecordings:writeيحذف التسجيل نهائيًا من سلة المهملات

لا يتم إرجاع بيانات الاعتماد أبدًا. يتم إرسال الردود مع Cache-Control: no-store.

الحقلكلا النوعينNotes
type✓aws-role أو s3-compatible
name✓التسمية الخاصة بك، بحد أقصى 80 حرفًا
projectId✓مشروع واحد، أو null لكل مشروع
bucket, region✓اسم الحاوية ومنطقتها
pathTemplate✓اختياري؛ انظر قوالب المسارات
keepCopyDays✓اختياري، من 0 إلى 3650، القيمة الافتراضية 7؛ انظر الاحتفاظ
roleArn, kmsKeyIdaws-roleدورك، ومفتاح KMS الخاص بك لـ SSE-KMS (اختياريًا)
provider, endpoint, forcePathStyle, accessKeyId, secretAccessKeys3-compatibleforcePathStyle القيمة الافتراضية هي true

كما يُبلغ الوجهة أيضًا عن status (active, unverified أو disabled), lastCheck (أحدث كتابة تجريبية) و lastDelivery.

لا تحتفظ RTC أبدًا بمفاتيح AWS الخاصة بك. تقوم بإنشاء دور في حسابك يمكن أن يتولاه دور التسليم الخاص بـ RTC، مقيدًا بمعرف خارجي فريد خاص بمؤسستك.

  1. استدعاء GET /v1/storage/aws-setup?bucket=<your-bucket> (أضف pathTemplate و kmsKeyArn (إذا كنت تستخدمها)، أو افتح نفس الإعداد في وحدة التحكم.
  2. قم بإنشاء دور IAM. الصق ما تم إرجاعه trustPolicy: يثق principalArn فقط عندما يحمل الطلب الخاص بك externalId.
  3. أرفق ما تم إرجاعه permissionsPolicy. يسمح s3:PutObject و s3:AbortMultipartUpload في المسار الخاص بك، s3:DeleteObject فقط في مجلد التحقق من الصحة، و kms:GenerateDataKey و kms:Encrypt على مفتاح KMS الخاص بك عند تقديمه.
  4. قم بإنشاء الوجهة باستخدام type: "aws-role" ودور roleArn:
{
"type": "aws-role",
"name": "Recordings archive",
"projectId": null,
"bucket": "acme-rtc-recordings",
"region": "us-east-1",
"roleArn": "<your-delivery-role-arn>"
}

يتم إنشاء المعرف الخارجي مرة واحدة لمؤسستك ولا يتغير. عندما available هو false في إجابة الإعداد، وجهات أدوار AWS غير متوفرة بعد، ويؤدي إنشاء واحدة إلى الرد 503 DELIVERY_NOT_CONFIGURED؛ استخدم مفاتيح الوصول في هذه الأثناء.

تخزين متوافق مع S3 باستخدام مفاتيح

Section titled “تخزين متوافق مع S3 باستخدام مفاتيح”

استخدام type: "s3-compatible" لـ Cloudflare R2 أو MinIO أو Wasabi أو Backblaze B2 أو AWS عندما تفضل استخدام مفاتيح الوصول. قم بتسمية خدمتك في provider الحقل، مع إحدى القيم التالية: r2, minio, wasabi, backblaze, aws أو other.

  • endpoint يجب أن يكون مصدر HTTPS على المنفذ 443، بدون مسار أو استعلام أو اسم مستخدم ، خارج CHAMPREP المجالات، ويجب أن يُحل إلى عناوين عامة. تقوم RTC بالتحقق من العنوان مرة أخرى عند كل اتصال. وإلا فإن RTC ترد 400 ENDPOINT_NOT_ALLOWED.
  • امنح المفاتيح حق الوصول للكتابة إلى الحاوية. احذف حق الوصول إلى champrep-rtc-validation/ يسمح المجلد لـ RTC بإزالة كائن الاختبار الخاص به.
  • يتم تشفير المفاتيح أثناء التخزين ولا يتم إرجاعها أبدًا. لا تعرض الوجهة سوى accessKeyIdHint، الأحرف الأربعة الأخيرة من معرّف المفتاح.
  • لتدوير المفاتيح، PATCH accessKeyId و secretAccessKey معًا.
  • عندما لا يكون تخزين المفاتيح متاحًا، يرد RTC 503 CREDENTIALS_UNAVAILABLE؛ استخدم دورًا في AWS في هذه الأثناء.

اختبار التحقق - الكتابة

Section titled “اختبار التحقق - الكتابة”

يقوم RTC باختبار الوجهة عند إنشائها، وعند تغيير منطقتها، أو قالب المسار، أو الدور، أو مفتاح KMS، أو نقطة النهاية، أو نمط المسار، أو المفاتيح، وعند إعادة تشغيلها، وعند استدعاء POST /v1/storage/destinations/{destinationId}/test.

يقوم الاختبار بكتابة كائن بحجم 64 بايت إلى <path prefix>/champrep-rtc-validation/<uuid>.txt ثم يتم إزالتها. إن الإزالة المرفوضة هي مجرد تحذير: السماح s3:DeleteObject في هذا المجلد، أو احذف الكائن بنفسك.

عند فشل الاختبار، يتم حفظ الوجهة على النحو التالي unverified ولا يتلقى أي شيء. lastCheck يحتوي على رمز وجملة:

الرمزالمعنى
ROLE_ASSUME_DENIEDلم يتمكن RTC من تولي الدور (سياسة الثقة أو المعرف الخارجي)
WRITE_DENIEDتم رفض الكتابة
BUCKET_NOT_FOUNDالمخزن غير موجود
WRONG_REGIONيوجد الحاوية في منطقة أخرى
INVALID_ACCESS_KEY, INVALID_SECRET_KEYتم رفض المفاتيح
KMS_DENIEDرفض مفتاح KMS التشفير
ENDPOINT_NOT_ALLOWED, ENDPOINT_NOT_FOUND, ENDPOINT_UNREACHABLEتم رفض نقطة النهاية، أو أنها غير معروفة، أو لا تستجيب
DELIVERY_NOT_CONFIGUREDوجهات أدوار AWS غير متاحة حتى الآن
STORAGE_ERRORخطأ تخزين آخر

قم بإصلاح السبب، ثم أعد الاختبار. تصبح الوجهة active عندما ينجح الاختبار . لا يمكنك إعادة تشغيل الوجهة التي تم إيقاف تشغيلها بواسطة CHAMPREP الدعم (DESTINATION_ADMIN_DISABLED).

يحدد القالب مفتاح الكائن لكل ملف. القيمة الافتراضية هي:

{project}/{yyyy}/{mm}/{dd}/{room}/{recording_id}/{file}
متغيرالقيمة
{project}معرف المشروع
{room}معرف الغرفة
{recording_id}معرف التسجيل
{external_ref}غرفة externalRef; none عندما يكون غائبًا أو غير معتاد
{track_id}معرف المسار
{artifact}أي ملف من ملفات التسجيل
{file}<trackId>.mkv, recording.mp4, audio.m4a، أو لـ النص transcript.json و transcript.vtt
{yyyy}, {mm}, {dd}أجزاء التاريخ

الأسماء المستعارة project_id, projectId, room_id, roomId, recordingId, externalRef و trackId يتم قبول أيضًا.

يجب أن يحتوي القالب على {recording_id} وتنتهي بـ {file}. النص الحرفي قد يستخدم الحروف والأرقام و ! _ . * ' ( ) / -. لا يمكن أن تبدأ بـ / أو تحتوي على //, . أو .. المجلدات. يمكن أن يصل حجم المفتاح إلى 900 بايت كحد أقصى.

  • عندما يكون التسجيل ready، يقوم RTC بنسخ كل ملف من ملفاته (كل مسار، و الملفات المركبة إن وجدت) إلى كل وجهة نشطة في مشروعه. النص النهائي النص يتم تسليمها بنفس الطريقة، مثل transcript.json و transcript.vtt.
  • لا يتم تسليم التسجيلات تلقائيًا إلا تلك التي تنتهي بعد أن تصبح الوجهة نشطة. قم بتسليم التسجيلات السابقة باستخدام إعادة التسليم.
  • يتم إرسال الملفات التي يزيد حجمها عن 16 ميغابايت على أجزاء. يبلغ RTC عن قيمة SHA-256 للبايتات التي أرسلها.
  • يتم إعادة محاولة أي محاولة فاشلة مع فترة انتظار (1، 2، 4 … دقائق، بفاصل زمني لا يتجاوز ساعة واحدة) لمدة 72 ساعة. بعد ذلك، يفشل التسليم و recording.delivery_failed يتم إرسالها.
  • يُحتسب عدد البايتات المرسلة ضمن حصة التنزيل المسموح بها في باقتك.
  • يؤدي إيقاف تشغيل وجهة ما إلى إلغاء عمليات التسليم المعلقة الخاصة بها. كما أن إزالتها تؤدي إلى نفس النتيجة وتؤدي إلى حذف بيانات اعتمادها.

قد يترك العامل الذي توقف في منتصف عملية التحميل أجزاء غير مكتملة في حاويتك. أضف AbortIncompleteMultipartUpload قاعدة دورة الحياة (يوم واحد) إلى المخزن.

اشترك في نقاط نهاية webhook لهذه الأحداث. كل عملية تسليم ملف ترسل حدثًا خاصًا بها.

الحدثdata
recording.deliveredrecordingId, roomId, destinationId, artifact, trackId (لأحد المقاطع)، bucket, key, size, sha256, checksum, etag, deliveredAt
recording.delivery_failedrecordingId, roomId, destinationId, artifact, trackId (لأحد المقاطع)، bucket, key, attempts, error (code, message)

يحتوي التسجيل على ملخص التسليم: delivery.state (pending, delivered, partial أو failed) و pending, delivered و failed يتم احتسابها.

GET /v1/recordings/{recordingId}/deliveries يعود recordingId، ذلك summary و deliveries: كل مهمة مع الحاوية المستهدفة والمفتاح الخاص بها، و نتيجتها (الحجم، SHA-256 و ETag) وآخر خطأ لها.

POST /v1/recordings/{recordingId}/redeliver مع خيار { "destinationId": "…" } يُعيد تشغيل المهام الفاشلة والملغاة والمسلّمة مع فترة زمنية جديدة مدتها 72 ساعة ويُنشئ أي مهام مفقودة.

HTTPالرمزالمعنى
409RECORDING_NOT_READYفقط ready يمكن تسليم التسجيل
409NO_ACTIVE_DESTINATIONلا توجد وجهة نشطة مطبقة على هذا التسجيل
404NO_ACTIVE_DESTINATIONلا توجد وجهة نشطة تحتوي على هذا destinationId

يؤدي حذف التسجيل إلى إرساله إلى سلة المهملات. يتم حذفه تلقائيًا بعد 30 يومًا، و يمكنك استعادته حتى ذلك الحين. كل مكالمة أدناه تحتاج إلى مفتاح مع recordings:write أو جلسة عمل وحدة التحكم الخاصة بك.

إرساله إلى سلة المهملات

Section titled “إرساله إلى سلة المهملات”

DELETE /v1/recordings/{recordingId} يرسل التسجيل إلى سلة المهملات:

{ "id": "…", "status": "trashed", "trashedAt": "2026-11-08T12:00:00.000Z", "reason": "customer", "purgeAt": "2026-12-08T12:00:00.000Z" }
  • يُحذف التسجيل من القائمة و GET /v1/recordings/{recordingId}. GET /v1/recordings?trashed=true يعرض قائمة بالتسجيلات الموجودة في سلة المهملات.
  • تتوقف عمليات التنزيل عن العمل، بما في ذلك روابط التنزيل التي تم إصدارها بالفعل.
  • يتم إلغاء عمليات التسليم الموجودة في قائمة الانتظار.
  • لا يزال يُحتسب ضمن سعة تخزين التسجيلات، ويتم احتساب تكلفته، أثناء وجوده في سلة المهملات.
  • purgeAt يتم الحذف التلقائي بعد: 30 يومًا من إرساله إلى سلة المهملات. يتم تحديد ذلك عند إرسال التسجيل إلى سلة المهملات: أي تغيير لاحق في نافذة سلة المهملات ينطبق فقط على التسجيلات التي تم إرسالها إلى سلة المهملات بعد ذلك. purgeAt هو null بينما يتم إيقاف تشغيل ميزة الحذف التلقائي من سلة المهملات.
  • recording.deleted يتم إرساله.
  • يستجيب التسجيل الذي لا يزال قيد التشغيل أو قيد المعالجة 409 RECORDING_ACTIVE؛ أوقفها أو انتظر.

POST /v1/recordings/{recordingId}/restore يستعيد التسجيل من سلة المهملات. الرد هو التسجيل نفسه، الذي يعود إلى قوائمك وتنزيلاتك كما كان قبل حذفه. recording.restored يتم إرساله. يمكنك استعادة التسجيل حتى يتم حذفه تلقائيًا أو حذفه نهائيًا. عملية الاستعادة التي تأتي متأخرة جدًّا تستجيب 409 RECORDING_PURGED.

يتم إعادة إرسال عمليات التسليم إلى مساحة التخزين الخاصة بك التي تم إلغاؤها عندما انتقل التسجيل إلى سلة المهملات. يتم الاحتفاظ بالتسجيل المستعاد حتى تقوم بحذفه مرة أخرى: لا يؤدي الاحتفاظ به إلى إعادته إلى سلة المهملات.

POST /v1/recordings/{recordingId}/purge يحذف التسجيل الموجود في سلة المهملات نهائيًا. يقبل RTC ذلك على الفور ويجيب 202؛ يكتمل الحذف قريبًا:

{ "id": "…", "status": "deleting", "purgeRequestedAt": "2026-11-08T12:05:00.000Z" }
  • لا يمكن استعادته أبدًا، من اللحظة التي يقبل فيها RTC الطلب.
  • عند إتمام الحذف، يتم مسح ملفاته، ويتوقف احتسابه ضمن سعة تخزين التسجيلات، و recording.purged يتم إرساله.
  • إعادة الطلب آمنة: فهو يرد 202 مرة أخرى أثناء تنفيذ عملية الحذف ، ثم 200 بمجرد الانتهاء من ذلك: { "id": "…", "status": "purged", "purgedAt": "2026-11-08T12:05:30.000Z" }.
  • لا يمكن حذف التسجيلات نهائيًا إلا إذا كانت موجودة في سلة المهملات. أي تسجيلات أخرى إجابات 409 RECORDING_NOT_IN_TRASH: أرسلها إلى سلة المهملات أولاً.

يتم حذف التسجيل نهائيًا عند purgeAt (30 يومًا في سلة المهملات)، بنفس الطريقة، و recording.purged يتم إرساله مع reason: "expired". يمكن لفريق CHAMPREP الدعم أيضًا حذف تسجيل موجود في سلة المهملات في وقت سابق بناءً على طلبك.

النسخ التي تم تسليمها بالفعل إلى سلة التخزين الخاصة بك هي ملكك. إن إرسال التسجيل إلى سلة المهملات، أو حذفه نهائيًا، أو الحذف التلقائي لا يؤدي أبدًا إلى إزالتها.

CHAMPREP يحتفظ بنسخته الخاصة من التسجيل وفقًا لفترة الاحتفاظ الخاصة بخطتك: 7 أيام في الإصدار التجريبي، و30 يومًا في الإصدار المبتدئ، و90 يومًا في الإصدار المتوسع، و365 يومًا في الإصدار التجاري. عند انقضاء تلك المدة، يتم إرسال التسجيل إلى سلة المهملات بنفس الطريقة المذكورة أعلاه، مع reason: "retention": يمكنك استعادته لمدة 30 يومًا، ويتم حذفه تلقائيًا بعد ذلك.

لا ينطبق الاحتفاظ إلا على التسجيلات التي تم إجراؤها بعد أن بدأ RTC في تطبيقه. التسجيلات التي تم إجراؤها قبل ذلك لا تنتهي صلاحيتها بسببه. لا يؤثر الاحتفاظ أبدًا على النسخ الموجودة في سلة التخزين الخاصة بك.

keepCopyDays في الوجهة (من 0 إلى 3650، الافتراضي 7) يسجل المدة التي تريد CHAMPREP الاحتفاظ بنسختها بعد التسليم. تتبع نسخة CHAMPREPاليوم سياسة الاحتفاظ الخاصة بخطتك؛ ولا يؤدي هذا الإعداد إلى إزالتها قبل ذلك.