เจดีเอ

JDA (จาวาดิสคอร์ด API)

ไลบรารีโอเพ่นซอร์สนี้มีไว้สำหรับการใช้งานบอทบน Discord โดยใช้เกตเวย์แบบเรียลไทม์และ REST API มีฟังก์ชันการทำงานตามเหตุการณ์เพื่อใช้บอททุกประเภท ช่วยให้ใช้งานแอปพลิเคชันได้อย่างมีประสิทธิภาพและปรับขนาดได้

ภาพรวม

แนวคิดหลักของ JDA ได้รับการพัฒนาเพื่อทำให้การสร้างแอปที่ปรับขนาดได้เป็นเรื่องง่าย:

1. ระบบเหตุการณ์
   นำเสนอเหตุการณ์ที่เรียบง่ายจาก Gateway API เพื่อตอบสนองต่อเหตุการณ์แพลตฟอร์มใดๆ แบบเรียลไทม์โดยไม่ต้องยุ่งยากมากนัก
2. การกระทำที่เหลือ
   การใช้งานฟังก์ชัน REST API ที่ใช้งานง่ายและปรับขนาดได้ ช่วยให้คุณสามารถเลือกระหว่างการโทรกลับด้วยตัวรวม ฟิวเจอร์ส และการบล็อก ไลบรารียังจัดการขีดจำกัดอัตราที่กำหนดโดย Discord โดยอัตโนมัติ ในขณะที่ยังคงเสนอวิธีแทนที่การใช้งานเริ่มต้น
3. แคชที่ปรับแต่งได้
   แลกเปลี่ยนการใช้หน่วยความจำเพื่อประสิทธิภาพที่ดีขึ้นตามความจำเป็น โดยมีการตั้งค่าล่วงหน้าที่เหมาะสมให้เลือกและปรับแต่ง

คุณสามารถเรียนรู้เพิ่มเติมได้โดยไปที่วิกิของเราหรืออ้างอิง Javadocs ของเรา

- การติดตั้ง

ห้องสมุดนี้มีอยู่ใน Maven Central เวอร์ชันล่าสุดจะแสดงใน GitHub Release เสมอ

เวอร์ชัน 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 Application Dashboard และคว้าโทเค็นบอทของคุณ คุณสามารถดูคำแนะนำทีละขั้นตอนได้ในหน้าวิกิของเรา การสร้าง Discord Bot

?‍♂️ เริ่มต้นใช้งาน

เรามีตัวอย่างมากมายเพื่อแนะนำให้คุณรู้จักกับ JDA คุณยังสามารถดู Wiki เอกสาร และคำถามที่พบบ่อยอย่างเป็นทางการของเราได้

บอททุกตัวที่ JDA ใช้งานเริ่มต้นโดยใช้ JDABuilder หรือ DefaultShardManagerBuilder ตัวสร้างทั้งสองจัดเตรียมชุดการตั้งค่าล่วงหน้าเริ่มต้นสำหรับการใช้งานแคชและเหตุการณ์ที่ต้องการรับ:

• createDefault - เปิดใช้งานแคชสำหรับผู้ใช้ที่ใช้งานในช่องเสียงและแฟล็กแคชทั้งหมด
• createLight - ปิดใช้งานแคชผู้ใช้และแฟล็กแคชทั้งหมด
• create - เปิดใช้งานการแบ่งส่วนสมาชิก แคชผู้ใช้ทั้งหมด และเปิดใช้งานแฟล็กแคชทั้งหมด

เราขอแนะนำให้อ่านคำแนะนำเกี่ยวกับการแคชและจุดประสงค์เพื่อให้เข้าใจถึงการกำหนดค่าบอทของคุณอย่างเหมาะสม ต่อไปนี้เป็นกรณีการใช้งานที่เป็นไปได้บางส่วน:

ตัวอย่าง: การบันทึกข้อความ

บันทึก

ตัวอย่างต่อไปนี้ใช้ Intent ที่มีสิทธิพิเศษ GatewayIntent.MESSAGE_CONTENT ซึ่งต้องเปิดใช้งานอย่างชัดเจนในแดชบอร์ดแอปพลิเคชันของคุณ คุณสามารถหาข้อมูลเพิ่มเติมเกี่ยวกับเจตนาได้ในคู่มือวิกิของเรา

เพียงบันทึกข้อความไปยังคอนโซล การใช้ JDABuilder ซึ่งเป็นจุดเริ่มต้นสำหรับบอทขนาดเล็กที่ไม่ได้ตั้งใจจะขยายเป็นพันกิลด์

เริ่มต้นบอทของคุณและแนบ Event Listener โดยใช้จุดประสงค์ที่ถูกต้อง:

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

Listener กิจกรรมของคุณอาจมีลักษณะดังนี้:

 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

ตัวอย่าง: บอทคำสั่ง Slash

นี่คือบอทที่ใช้การโต้ตอบเพื่อตอบสนองต่อคำสั่งของผู้ใช้ ต่างจากบอทบันทึกข้อความตรงที่บอทนี้สามารถทำงานได้โดยไม่ต้องเปิดใช้งานใดๆ เนื่องจากการโต้ตอบจะพร้อมใช้งานอยู่เสมอ

 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 ();
}

Listener เหตุการณ์ที่ตอบสนองต่อคำสั่งอาจมีลักษณะดังนี้:

{ 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; } } }">

 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 จะถูกใช้เป็นตัวสร้างคำขอสำหรับตำแหน่งข้อมูล 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 }">

 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() } }">

 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

ลาวาเพลเยอร์

สร้างโดย sedmelluq และตอนนี้ดูแลโดยชุมชน lavalink
Lavaplayer เป็นไลบรารียอดนิยมที่ใช้โดย Music Bots ที่สร้างใน Java มันเข้ากันได้สูงกับ JDA และ Discord4J และอนุญาตให้เล่นเสียงจาก YouTube, Soundcloud, Twitch, Bandcamp และผู้ให้บริการอื่น ๆ
ไลบรารีสามารถขยายไปยังบริการอื่น ๆ ได้อย่างง่ายดายโดยการใช้ AudioSourceManager ของคุณเองและลงทะเบียน เราขอแนะนำให้ใช้ udpqueue นอกเหนือจาก lavaplayer เพื่อหลีกเลี่ยงปัญหาการพูดติดอ่างที่เกิดจากการหยุด GC ชั่วคราว

ขอแนะนำให้อ่านส่วนการใช้งานของ Lavaplayer เพื่อทำความเข้าใจการใช้งานที่เหมาะสม
Sedmelluq จัดเตรียมการสาธิตในพื้นที่เก็บข้อมูลของเขาซึ่งนำเสนอตัวอย่างการใช้งานสำหรับ JDA: https://github.com/lavalink-devs/lavaplayer/tree/master/demo-jda

udpqueue (ส่วนขยายของ jda-nas)

สร้างและดูแลโดย sedmelluq และขยายโดย MinnDevelopment
จัดเตรียมการใช้งานดั้งเดิมสำหรับ JDA Audio Send-System เพื่อหลีกเลี่ยงไม่ให้ 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 อย่าลืมวางสาขาของคุณออกจากสาขา หลัก ของเรา (หรือสาขาที่มีคุณลักษณะ) และสร้าง PR ของคุณลงในสาขา เดียวกัน นั้น

โปรดปฏิบัติตามแนวทางการมีส่วนร่วมของเรา

อย่าคาดหวังว่าคำขอดึงของคุณจะได้รับความสนใจในทันที บางครั้งอาจใช้เวลานานกว่าจะได้รับคำตอบ คุณสามารถเข้าร่วมเซิร์ฟเวอร์ Discord ของเราและถามใน #lib-dev ก่อนที่จะเริ่มทำงานในการประชาสัมพันธ์ใหม่ เพื่อรับคำติชมทันทีจากสมาชิกชุมชนของเรา

ทำลายการเปลี่ยนแปลง

เนื่องจากธรรมชาติของ Discord API ไลบรารี่จะแนะนำการเปลี่ยนแปลงที่ไม่สมบูรณ์เป็นประจำเพื่อให้สามารถนำคุณสมบัติใหม่ๆ มาใช้ได้อย่างรวดเร็ว เราพยายามทำให้การเปลี่ยนแปลงที่ทำลายล้างเหล่านี้เกิดขึ้นน้อยที่สุด แต่ไม่สามารถหลีกเลี่ยงได้ทั้งหมด

การเปลี่ยนแปลงที่แตกหักส่วนใหญ่จะส่งผลให้มีเวอร์ชันย่อย เล็กน้อย ( 5.1.2 → 5.2.0 )