BigBlueButton 3.x için API dokümantasyonunu görüntülüyorsunuz. Güncel sürüm: BigBlueButton 4.x. Yükseltme mi planlıyorsunuz? Geçiş kılavuzu, API çağrılarınızda yapmanız gereken tüm değişiklikleri listeler.
API Hata Başvurusu
Başarısız BigBlueButton API istekleri standartlaştırılmış bir XML hata yanıtı döndürür. Bu bölüm, BigBlueButton 3.0 kaynak kodunun analizine dayanarak API'nin döndürebileceği hata kodları ve mesajları için bir başvuru kaynağı sunar.
Hata Yanıtı Biçimi
Bir API çağrısı başarısız olduğunda, BigBlueButton üç temel öğe içeren bir XML yanıtı döndürür: bir returncode, makine tarafından okunabilir bir messageKey ve insan tarafından okunabilir bir message. Her hata yanıtı bu yapıyı izler:
<response>
<returncode>FAILED</returncode>
<messageKey>errorKeyHere</messageKey>
<message>A human-readable description of the error.</message>
</response> İstisnalar: nonUniqueVoiceBridge ve clientSettingsOverrideValidationError, messageKey ve message yerine key ve message öğelerini içeren bir errors listesi olarak döndürülür. Oturum tabanlı getJoinUrl, learningDashboard ve stuns uç noktaları hatalara, message içeren ancak messageKey içermeyen JSON yanıtları verir.
returncode hata durumlarında her zaman FAILED olur. Tek istisna, SUCCESS döndüren ancak bir uyarı mesajı anahtarı içeren duplicateWarning durumudur. Entegrasyonunuz yalnızca dönüş kodunu değil, her zaman messageKey alanını kontrol etmelidir.
Kimlik Doğrulama ve Yetkilendirme Hataları
Bu hatalar, bir istek kimliği doğrulanamadığında veya çağrıyı yapan taraf gerekli izinlere sahip olmadığında ortaya çıkar:
messageKey | Mesaj | Tetikleyen Endpoint'ler |
|---|---|---|
checksumError | checksum eşleşmiyor. | Sağlama toplamı gerektiren tüm uç noktalar |
invalidPassword | Sağlanan parola geçersiz. | create, join, end |
guestDeniedAccess | guest policy temelinde erişim reddedildi. | join |
apiNotEnabled | API hizmeti bu sunucuda etkin değil. | Tüm uç noktalar |
Toplantı Yönetimi Hataları
Bu hatalar toplantı oluşturma, katılma ve yönetme ile ilgilidir:
messageKey | Mesaj | Tetikleyen Endpoint'ler |
|---|---|---|
notFound | Bu kimliğe sahip bir toplantı mevcut değil. | getMeetingInfo, end |
invalidMeetingIdentifier | Bu kimliğe sahip bir toplantı mevcut değil. | join |
meetingForciblyEnded | Zorla sonlandırılmış bir toplantıya katılınamaz. | join |
idNotUnique | Bu kimliğe sahip bir toplantı zaten mevcut. | create |
nonUniqueVoiceBridge | Seçilen voice bridge zaten kullanımda. | create |
duplicateWarning | Bu konferans zaten mevcut ve çalışıyor olabilir. returncode değeri SUCCESS | create |
mismatchCreateTimeParam | createTime parametresi mevcut toplantıyla eşleşmiyor. | join |
maxParticipantsReached | Maksimum katılımcı sayısına ulaşıldı. | join |
parentMeetingIDMissing | Breakout room için parentMeetingID belirtilmedi. | create (breakout) |
parentMeetingDoesNotExist | breakout room için üst toplantı bulunamadı. | create (breakout) |
meetingNotFound | Toplantı bulunamadı. | sendChatMessage |
Params required | Geçerli bir rol gönderilmedi veya parola ne moderatör ne de katılımcı parolasıyla eşleşiyor. | join |
clientSettingsOverrideValidationError | İstemci ayarlarını geçersiz kılan yapılandırma, bilinmeyen veya hatalı biçimlendirilmiş anahtarlar içeriyor (yalnızca clientSettingsOverrideStrictValidation etkinleştirildiğinde kontrol edilir). | create |
Parametre Doğrulama Hataları
Bu hatalar, gerekli parametreler eksik olduğunda veya istek verisi doğrulamadan geçemediğinde döndürülür:
messageKey | Mesaj | Tetikleyen Endpoint'ler |
|---|---|---|
missingParamMeetingID | meeting ID sağlanmalıdır. | create, join, isMeetingRunning, end, getMeetingInfo, insertDocument, sendChatMessage |
missingParamFullName | fullName sağlanmalıdır. | join |
missingParamRecordID | recording ID sağlanmalıdır. | updateRecordings, publishRecordings, deleteRecordings, getRecordingTextTracks |
missingParamPublish | publish değeri (true/false) sağlanmalıdır. | publishRecordings |
validationError | Genel doğrulama hatası (çeşitli mesajlar). | Birden fazla uç nokta |
unsupportedContentType | POST isteğinin Content-Type değeri eksik veya desteklenmiyor. | create, join, isMeetingRunning, end, getMeetingInfo, getMeetings, getSessions, insertDocument, sendChatMessage |
emptyError | Alan boş olmamalıdır. | Genel doğrulama |
nullError | Gerekli bir değer eksik. | create, sendChatMessage |
sizeError | Bir parametre, izin verilen uzunluk sınırlarının dışında. | create, join, isMeetingRunning, end, getMeetingInfo, insertDocument, sendChatMessage |
Kayıt Hataları
Bu hatalar kayıt yönetimi ve metin parçası işlemlerine özeldir:
messageKey | Mesaj | Tetikleyen Endpoint'ler |
|---|---|---|
notFound | Kayıt bulunamadı. | updateRecordings, publishRecordings, deleteRecordings |
noRecordings | Belirtilen recording ID için kayıt bulunamadı. | getRecordingTextTracks, putRecordingTextTrack |
empty_uploaded_text_track | Yüklenen text track dosyası boş. | putRecordingTextTrack |
paramError | Parametre {paramName} eksik (dinamik). | putRecordingTextTrack |
invalidKind | Geçersiz kind parametresi — beklenen: subtitles veya captions. | putRecordingTextTrack |
invalidLang | Geçersiz language parametresi. | putRecordingTextTrack |
Oturum ve Kullanıcı Hataları
Bu hatalar oturum ve kullanıcı doğrulaması sırasında oluşur:
messageKey | Mesaj | Tetikleyen Endpoint'ler |
|---|---|---|
userNotFound | Belirtilen user ID için etkin oturum bulunamadı. | join (existingUserID ile) |
Sorun Giderme
Bir API hatasıyla karşılaştığınızda, sorunu teşhis etmek ve çözmek için şu adımları izleyin:
messageKey değerini kontrol edin — hatanın tam nedenini ve hangi uç noktanın bunu tetiklediğini belirlemek için yukarıdaki hata kodu tablolarını kullanın.
Sağlama toplamınızı doğrulayın — en yaygın hata checksumError hatasıdır. Doğru paylaşılan gizli anahtarı ve doğru özet algoritmasını kullandığınızdan, ayrıca sorgu dizesinin tam olarak eşleştiğinden emin olun.
Zorunlu parametreleri kontrol edin — eksik parametre hataları (missingParamMeetingID, missingParamFullName vb.), isteğe zorunlu bir alanın eklenmediğini gösterir.
Toplantı durumunu doğrulayın — notFound veya invalidMeetingIdentifier gibi hatalar, toplantının mevcut olmadığı veya zaten sona erdiği anlamına gelir. Yeniden denemeden önce mevcut durumu doğrulamak için getMeetingInfo kullanın.
Sunucu günlüklerini inceleyin — hata mesajı yeterince spesifik değilse, daha ayrıntılı bilgi için /var/log/bigbluebutton/ içindeki BigBlueButton sunucu günlüklerini kontrol edin.
Bazı hata mesajları dinamiktir ve sorunlu parametrenin adını veya değerini içerir. Hata ayıklamayı kolaylaştırmak için API’den gelen tam XML yanıtını her zaman günlüğe kaydedin.
duplicateWarning message key işlenirken, returncode değerinin FAILED değil, SUCCESS olduğunu unutmayın. Bu, BigBlueButton'ın aynı kimliğe sahip bir toplantının zaten var olduğunu bildirip hata yükseltmek yerine mevcut toplantı verilerini döndürdüğü özel bir durumdur.
Sıkça Sorulan Sorular
BigBlueButton 3.0 kaynak kodundan alınmıştır. Resmî BBB belgelerinde eksiksiz bir hata referansı bulunmaz. Tanımlar, ApiErrors.java, ApiController.groovy ve RecordingController.groovy dahil olmak üzere çeşitli kaynak dosyalara dağılmıştır.messageKey değerleri sürümler arasında genellikle kararlı kalsa da, insan tarafından okunabilir mesaj metni değişebilir. Programatik hata işleme için her zaman mesaj dizesini değil, messageKey değerini kullanın.notFound, getMeetingInfo, end tarafından; invalidMeetingIdentifier, join tarafından; meetingNotFound ise sendChatMessage tarafından kullanılır (toplantı mevcut olduğu hâlde henüz kimse katılmadığında da). isMeetingRunning, bilinmeyen bir toplantı için hiçbir zaman hata vermez; <running>false</running> döndürür.duplicateWarning özel bir durumdur: returncode değeri SUCCESS'dur, ancak messageKey aynı kimliğe sahip bir toplantının zaten mevcut olduğunu bildirir. Uygulamanız, mevcut toplantı parametrelerinin amaçladıklarınızla eşleşip eşleşmediğini kontrol etmelidir. Eşleşiyorsa güvenle devam edebilirsiniz. Aksi takdirde farklı bir meeting ID seçin.shared secret kullanmak, yanlış hash algoritması uygulamak, sorgu dizesini tutarsız URL-encode etmek veya checksum parametresinin kendisini hash girdisine dahil etmek. Hashlediğiniz dizenin şu şekilde oluşturulduğundan emin olun: apiMethodName + queryString + sharedSecret; burada queryString, checksum parametresini içermez.Content-Type başlığı eksik olduğunda veya BigBlueButton tarafından ilgili uç nokta için desteklenmeyen bir içerik türü kullanıldığında döndürülür. Form parametreleri için application/x-www-form-urlencoded kullanın; create, XML biçimindeki bir gövdeyi de kabul eder ve insertDocument yalnızca application/xml veya text/xml kabul eder.messageKey ile karşılaşırsanız daha fazla bilgi için sunucu günlüklerini ve kurulu eklentileri kontrol edin.