JDA

JDA (جافا ديسكورد API)

تهدف هذه المكتبة مفتوحة المصدر إلى تنفيذ الروبوتات على Discord باستخدام بوابة الوقت الفعلي وREST API. فهو يوفر وظائف قائمة على الأحداث لتنفيذ الروبوتات من أي نوع، مما يسمح بتطبيقات فعالة وقابلة للتطوير.

ملخص

لقد تم تطوير المفاهيم الأساسية لـ JDA لتسهيل إنشاء تطبيقات قابلة للتطوير:

1. نظام الحدث
   توفير أحداث مبسطة من واجهة API للبوابة، للرد على أي أحداث منصة في الوقت الحقيقي دون الكثير من المتاعب.
2. إجراءات الراحة
   سهولة الاستخدام والتنفيذ القابل للتطوير لوظيفة REST API، مما يتيح لك الاختيار بين عمليات الاسترجاعات مع المجمعات والعقود الآجلة والحظر. تتعامل المكتبة أيضًا مع حدود المعدل التي يفرضها Discord تلقائيًا، مع الاستمرار في تقديم طرق لاستبدال التنفيذ الافتراضي.
3. ذاكرة تخزين مؤقت قابلة للتخصيص
   استخدام ذاكرة التداول للحصول على أداء أفضل عند الضرورة، مع إعدادات مسبقة افتراضية معقولة للاختيار من بينها وتخصيصها.

يمكنك معرفة المزيد من خلال زيارة موقع wiki الخاص بنا أو الرجوع إلى Javadocs الخاص بنا.

؟ تثبيت

هذه المكتبة متاحة على مخضرم المركزي. يتم عرض أحدث إصدار دائمًا في إصدار GitHub.

الحد الأدنى لإصدار Java الذي يدعمه JDA هو Java SE 8 . تستخدم JDA أيضًا JSR 305 لدعم قابلية التشغيل البيني القوية مع Kotlin خارج الصندوق.

جرادل

 repositories {
    mavenCentral()
}

dependencies {
    implementation( " net.dv8tion:JDA: $v ersion " ) { // replace $version with the latest version
      // Optionally disable audio natives to reduce jar size by excluding `opus-java`
      // Gradle DSL:
      // exclude module: 'opus-java'
      // Kotlin DSL:
      // exclude(module="opus-java")
    }
}

مخضرم

< dependency >
    < groupId >net.dv8tiongroupId >
    < artifactId >JDAartifactId >
    < version >$versionversion > 
    
dependency >

؟ إنشاء بوت

لاستخدام هذه المكتبة، يجب عليك إنشاء تطبيق في لوحة تحكم تطبيق Discord والحصول على رمز الروبوت الخاص بك. يمكنك العثور على دليل خطوة بخطوة لهذا الأمر في صفحة الويكي الخاصة بنا إنشاء Discord Bot.

‍♂️ البدء

نحن نقدم عددًا من الأمثلة لتعريفك بـ JDA. يمكنك أيضًا إلقاء نظرة على موقع Wiki الرسمي والوثائق والأسئلة الشائعة.

يبدأ كل روبوت تنفذه JDA باستخدام JDABuilder أو DefaultShardManagerBuilder. يوفر كلا المنشئين مجموعة من الإعدادات المسبقة الافتراضية لاستخدام ذاكرة التخزين المؤقت والأحداث التي يريد تلقيها:

• createDefault - تمكين ذاكرة التخزين المؤقت للمستخدمين النشطين في القنوات الصوتية وجميع علامات ذاكرة التخزين المؤقت
• createLight - تعطيل جميع علامات ذاكرة التخزين المؤقت وذاكرة التخزين المؤقت للمستخدم
• create - تمكين تقسيم الأعضاء وتخزين جميع المستخدمين مؤقتًا وتمكين جميع إشارات ذاكرة التخزين المؤقت

نوصي بقراءة الدليل الخاص بالتخزين المؤقت والنوايا للتعرف على كيفية تكوين الروبوت الخاص بك بشكل صحيح. فيما يلي بعض حالات الاستخدام المحتملة:

على سبيل المثال: تسجيل الرسائل

ملحوظة

يستخدم المثال التالي الغرض المميز GatewayIntent.MESSAGE_CONTENT ، والذي يجب تمكينه بشكل صريح في لوحة تحكم التطبيق الخاص بك. يمكنك معرفة المزيد عن النوايا في دليل الويكي الخاص بنا.

ما عليك سوى تسجيل الرسائل إلى وحدة التحكم. الاستفادة من JDABuilder، نقطة الدخول المقصودة للروبوتات الصغيرة التي لا تنوي النمو إلى آلاف النقابات.

بدء تشغيل الروبوت الخاص بك وإرفاق مستمع الحدث، باستخدام المقاصد الصحيحة:

 public static void main ( String [] args ) {
  JDABuilder . createLight ( token , EnumSet . of ( GatewayIntent . GUILD_MESSAGES , GatewayIntent . MESSAGE_CONTENT ))
      . addEventListeners ( new MessageReceiveListener ())
      . build ();
}

يمكن أن يبدو مستمع الحدث الخاص بك كما يلي:

 public class MessageReceiveListener extends ListenerAdapter {
  @ Override
  public void onMessageReceived ( MessageReceivedEvent event ) {
    System . out . printf ( "[%s] %#s: %s n " ,
      event . getChannel (),
      event . getAuthor (),
      event . getMessage (). getContentDisplay ());
  }
}

يمكنك العثور على مثال أكثر شمولاً باستخدام فئةMessageLoggerExample.

على سبيل المثال: بوت أمر القطع

هذا روبوت يستخدم التفاعلات للرد على أوامر المستخدم. على عكس روبوت تسجيل الرسائل، يمكن لهذا الروبوت العمل دون أي نوايا ممكّنة، نظرًا لأن التفاعلات متاحة دائمًا.

 public static void main ( String [] args ) {
  JDA jda = JDABuilder . createLight ( token , Collections . emptyList ())
      . addEventListeners ( new SlashCommandListener ())
      . build ();

  // Register your commands to make them visible globally on Discord:

  CommandListUpdateAction commands = jda . updateCommands ();

  // Add all your commands on this action instance
  commands . addCommands (
    Commands . slash ( "say" , "Makes the bot say what you tell it to" )
      . addOption ( STRING , "content" , "What the bot should say" , true ), // Accepting a user input
    Commands . slash ( "leave" , "Makes the bot leave the server" )
      . setGuildOnly ( true ) // this doesn't make sense in DMs
      . setDefaultPermissions ( DefaultMemberPermissions . DISABLED ) // only admins should be able to use this command.
  );

  // Then finally send your commands to discord using the API
  commands . queue ();
}

يمكن أن يبدو مستمع الحدث الذي يستجيب للأوامر كما يلي:

{ String content = event.getOption("content", OptionMapping::getAsString); event.reply(content).queue(); }; case "leave" -> { event.reply("I'm leaving the server now!") .setEphemeral(true) // this message is only visible to the command user .flatMap(m -> event.getGuild().leave()) // append a follow-up action using flatMap .queue(); // enqueue both actions to run in sequence (send message -> leave guild) }; default -> return; } } }" style=";text-align:right;direction:rtl">

 public class SlashCommandListener extends ListenerAdapter {
  @ Override
  public void onSlashCommandInteraction ( SlashCommandInteractionEvent event ) {
    switch ( event . getName ()) {
      case "say" -> {
        String content = event . getOption ( "content" , OptionMapping :: getAsString );
        event . reply ( content ). queue ();
      };
      case "leave" -> {
        event . reply ( "I'm leaving the server now!" )
          . setEphemeral ( true ) // this message is only visible to the command user
          . flatMap ( m -> event . getGuild (). leave ()) // append a follow-up action using flatMap
          . queue (); // enqueue both actions to run in sequence (send message -> leave guild)
      };
      default -> return ;
    }
  }
}

يمكنك العثور على مثال أكثر شمولاً باستخدام فئة SlashBotExample.

RestAction

في هذه المكتبة، يتم استخدام واجهة RestAction كمنشئ طلبات لجميع نقاط نهاية API. تمثل هذه الواجهة أداة إنشاء طلبات كسولة، كما هو موضح في هذا المثال البسيط:

 channel . sendMessage ( "Hello Friend!" )
  . addFiles ( FileUpload . fromData ( greetImage )) // Chain builder methods to configure the request
  . queue () // Send the request asynchronously 

مهم

المكالمة النهائية لقائمة queue() ترسل الطلب. يمكنك أيضًا إرسال الطلب بشكل متزامن أو باستخدام العقود الآجلة، راجع دليلنا الموسع في RestAction Wiki.

تدعم واجهة RestAction أيضًا عددًا من عوامل التشغيل لتجنب جحيم رد الاتصال:

• map
  تحويل نتيجة RestAction إلى قيمة مختلفة
• flatMap
  سلسلة RestAction أخرى على النتيجة
• delay
  تأخير عنصر الخطوة السابقة

وكذلك المجمعات مثل:

• and
  يتطلب إكمال RestAction آخر بنجاح، ويعمل بالتوازي
• allOf
  قم بتجميع قائمة بالعديد من الإجراءات في إجراء واحد (راجع أيضًا mapToResult )
• zip
  يشبه and ، ولكنه يجمع النتائج في قائمة

والتكوينات مثل:

• timeout والموعد deadline
  قم بتكوين المدة المسموح بها لبقاء الإجراء في قائمة الانتظار، وقم بإلغائه إذا استغرق وقتًا طويلاً
• setCheck
  قم بإجراء بعض عمليات التحقق قبل إرسال الطلب مباشرة، وقد يكون ذلك مفيدًا عندما يكون في قائمة الانتظار لفترة من الوقت
• reason
  سبب سجل التدقيق لاتخاذ الإجراء

مثال :

it.editMessage(content)) // then edit the message .delay(1, MINUTES, scheduler) // wait another minute .flatMap(Message::delete); // then delete }" style=";text-align:right;direction:rtl">

 public RestAction < Void > selfDestruct ( MessageChannel channel , String content ) {
    return channel . sendMessage ( "The following message will destroy itself in 1 minute!" )
        . addActionRow ( Button . danger ( "delete" , "Delete now" )) // further amend message before sending
        . delay ( 10 , SECONDS , scheduler ) // after sending, wait 10 seconds
        . flatMap (( it ) -> it . editMessage ( content )) // then edit the message
        . delay ( 1 , MINUTES , scheduler ) // wait another minute
        . flatMap ( Message :: delete ); // then delete
}

يمكن بعد ذلك استخدام هذا في الكود:

 selfDestruct ( channel , "Hello friend, this is my secret message" ). queue ();

؟ ملحقات

jda-ktx

تم إنشاؤها وصيانتها بواسطة MinnDevelopment.
يوفر امتدادات Kotlin لـ RestAction والأحداث التي توفر تجربة Kotlin أكثر اصطلاحية.

val time = measureTime { event.reply("Pong!").await() // suspending }.inWholeMilliseconds event.hook.editOriginal("Pong: $time ms").queue() } }" style=";text-align:right;direction:rtl">

 fun main () {
    val jda = light( BOT_TOKEN )
    
    jda.onCommand( " ping " ) { event ->
        val time = measureTime {
            event.reply( " Pong! " ).await() // suspending
        }.inWholeMilliseconds

        event.hook.editOriginal( " Pong: $time ms " ).queue()
    }
}

هناك عدد من الأمثلة المتوفرة في ملف README.

لافابلاير

تم إنشاؤه بواسطة sedmeluq ويتم صيانته الآن بواسطة مجتمع Lavalink
Lavaplayer هي المكتبة الأكثر شعبية التي تستخدمها Music Bots التي تم إنشاؤها في Java. إنه متوافق للغاية مع JDA وDiscord4J ويسمح بتشغيل الصوت من YouTube وSoundcloud وTwitch وBandcamp والمزيد من مقدمي الخدمة.
يمكن توسيع المكتبة بسهولة لتشمل المزيد من الخدمات عن طريق تنفيذ برنامج AudioSourceManager الخاص بك وتسجيله. نوصي أيضًا باستخدام udpqueue بالإضافة إلى lapplayer، لتجنب مشكلات التأتأة الناتجة عن توقف GC مؤقتًا.

يوصى بقراءة قسم الاستخدام في Lavaplayer لفهم التنفيذ الصحيح.
قدم Sedmelluq عرضًا توضيحيًا في مستودعه والذي يقدم مثالًا لتطبيق JDA: https://github.com/avalink-devs/avaplayer/tree/master/demo-jda

udpqueue (امتداد لـ jda-nas)

تم إنشاؤه وصيانته بواسطة sedmeluq وتم توسيعه بواسطة MinnDevelopment
يوفر تطبيقًا أصليًا لنظام إرسال الصوت JDA لتجنب توقف GC مؤقتًا مما قد يتسبب في حدوث مشكلات في تشغيل الصوت المستمر.

لاحظ أن نظام الإرسال هذا ينشئ عميل UDP إضافي مما يتسبب في توقف استقبال الصوت عن العمل بشكل صحيح، نظرًا لأن Discord يعرّف عميل UDP المرسل على أنه جهاز الاستقبال.

 JDABuilder builder = JDABuilder . createDefault ( BOT_TOKEN )
    . setAudioSendFactory ( new NativeAudioSendFactory ());

لافالينك

تم إنشاؤها بواسطة Freya Arbjerg ويتم صيانتها الآن بواسطة مجتمع Lavalink.

Lavalink هي عقدة إرسال صوتية مستقلة تعتمد على Lavaplayer. تم تصميم Lavalink مع وضع قابلية التوسع في الاعتبار، ويسمح ببث الموسيقى عبر العديد من الخوادم. وهو يدعم معظم ميزات Lavaplayer.

يتم استخدام Lavalink من قبل العديد من الروبوتات الكبيرة، بالإضافة إلى مطوري الروبوتات الذين لا يمكنهم استخدام مكتبة Java مثل Lavaplayer. إذا كنت تخطط لتقديم الموسيقى على نطاق أصغر باستخدام JDA، فمن الأفضل غالبًا استخدام Lavaplayer مباشرة لأنه أسهل.

Lavalink-Client هو عميل Lavalink الرسمي لـ JDA.

المساهمة في JDA

إذا كنت ترغب في المساهمة في JDA، فتأكد من إنشاء فرعك خارج فرعنا الرئيسي (أو فرع الميزات) وإنشاء العلاقات العامة الخاصة بك في نفس الفرع.

يرجى اتباع إرشادات المساهمة الخاصة بنا.

لا تتوقع أن يحظى طلب السحب الخاص بك باهتمام فوري، ففي بعض الأحيان سيستغرق الأمر وقتًا طويلاً للحصول على رد. يمكنك الانضمام إلى خادم Discord الخاص بنا والاستفسار عن #lib-dev قبل البدء في العمل على علاقات عامة جديدة، للحصول على المزيد من التعليقات الفورية من أعضاء مجتمعنا.

كسر التغييرات

نظرًا لطبيعة Discord API، ستقدم المكتبة بانتظام تغييرات جذرية للسماح بالتبني السريع للميزات الأحدث. نحن نحاول إبقاء هذه التغييرات الطارئة في حدها الأدنى، لكن لا يمكننا تجنبها تمامًا.

ستؤدي معظم التغييرات العاجلة إلى حدوث تغيير طفيف في الإصدار ( 5.1.2 → 5.2.0 ).