Menggunakan API perpesanan - AWS SimSpace Weaver
Mengirim pesanMenerima pesanMembalas pengirim

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Menggunakan API perpesanan

API perpesanan terdapat dalam SDK SimSpace Weaver aplikasi (versi minimum 1.16.0). Pesan didukung dalam C ++, Python, dan integrasi kami dengan Unreal Engine 5 dan Unity.

Ada dua fungsi yang menangani transaksi pesan: SendMessage danReceiveMessages. Semua pesan terkirim berisi tujuan dan muatan. ReceiveMessagesAPI menampilkan daftar pesan yang saat ini berada dalam antrean pesan masuk aplikasi.

C++

Kirim pesan

AWS_WEAVERRUNTIME_API Result<void> SendMessage(
    Transaction& txn,
    const MessagePayload& payload,
    const MessageEndpoint& destination,
    MessageDeliveryType deliveryType = MessageDeliveryType::BestEffort
    ) noexcept;

Menerima pesan

AWS_WEAVERRUNTIME_API Result<MessageList> ReceiveMessages(
    Transaction& txn) noexcept;
Python

Kirim pesan

api.send_message(
 txn, # Transaction
 payload, # api.MessagePayload
 destination, # api.MessageDestination
 api.MessageDeliveryType.BestEffort # api.MessageDeliveryType
)

Menerima pesan

api.receive_messages(
 txn, # Transaction
) -> api.MessageList
Topik

Mengirim pesan

Pesan terdiri dari transaksi (mirip dengan panggilan Weaver API lainnya), payload, dan tujuan.

Muatan pesan

Payload pesan adalah struktur data fleksibel hingga 256 byte. Kami merekomendasikan hal berikut sebagai praktik terbaik untuk membuat muatan pesan Anda.

Untuk membuat payload pesan

  1. Buat struktur data (seperti struct dalam C ++) yang mendefinisikan isi pesan.

  2. Buat payload pesan yang berisi nilai yang akan dikirim dalam pesan Anda.

  3. Buat MessagePayload objek.

Tujuan pesan

Tujuan pesan ditentukan oleh MessageEndpoint objek. Ini termasuk tipe endpoint dan endpoint ID. Satu-satunya jenis endpoint yang saat ini didukung adalahPartition, yang memungkinkan Anda untuk menangani pesan ke partisi lain dalam simulasi. Endpoint ID adalah ID partisi tujuan target Anda.

Anda hanya dapat memberikan 1 alamat tujuan dalam satu pesan. Buat dan kirim beberapa pesan jika Anda ingin mengirim pesan ke lebih dari 1 partisi secara bersamaan.

Untuk panduan tentang cara menyelesaikan titik akhir pesan dari suatu posisi, lihatKiat saat bekerja dengan perpesanan.

Kirim pesan

Anda dapat menggunakan SendMessage API setelah membuat objek tujuan dan muatan.

C++
Api::SendMessage(transaction, payload, destination, MessageDeliveryType::BestEffort);
Python
api.send_message(txn, payload, destination, api.MessageDeliveryType.BestEffort)
Contoh lengkap pengiriman pesan

Contoh berikut menunjukkan bagaimana Anda dapat membangun dan mengirim pesan generik. Contoh ini mengirimkan 16 pesan individual. Setiap pesan berisi muatan dengan nilai antara 0 dan 15, dan centang simulasi saat ini.

C++
// Message struct definition
struct MessageTickAndId
{
    uint32_t id;
    uint32_t tick;
};

Aws::WeaverRuntime::Result<void> SendMessages(Txn& txn) noexcept
{
     // Fetch the destination MessageEndpoint with the endpoint resolver
    WEAVERRUNTIME_TRY(
        Api::MessageEndpoint destination,
        Api::Utils::MessageEndpointResolver::ResolveFromPosition(
        txn,
            "MySpatialSimulation",
            Api::Vector2F32 {231.3, 654.0}
        )
    );
    Log::Info("destination: ", destination);

    WEAVERRUNTIME_TRY(auto tick, Api::CurrentTick(txn));

    uint16_t numSentMessages = 0;
    for (std::size_t i=0; i<16; i++)
    {
        // Create the message that'll be serialized into payload
        MessageTickAndId message {i, tick.value};
        
        // Create the payload out of the struct
        const Api::MessagePayload& payload = Api::Utils::CreateMessagePayload(
            reinterpret_cast<const std::uint8_t*>(&message), 
            sizeof(MessageTickAndId)
        );
        
        // Send the payload to the destination
        Result<void> result = Api::SendMessage(txn, payload, destination);
        if (result.has_failure())
        {
            // SendMessage has failure modes, log them
            auto error = result.as_failure().error();
            std::cout<< "SendMessage failed, ErrorCode: " << error << std::endl;
            continue;
        }
        
        numSentMessages++;
    }

    std::cout << numSentMessages << " messages is sent to endpoint" 
       << destination << std::endl;
    return Aws::WeaverRuntime::Success();
}
Python
# Message data class
@dataclasses.dataclass
class MessageTickAndId:
    tick: int = 0
    id: int = 0
    
# send messages
def _send_messages(self, txn):
    tick = api.current_tick(txn)
    num_messages_to_send = 16

    # Fetch the destination MessageEndpoint with the endpoint resolver
    destination = api.utils.resolve_endpoint_from_domain_name_position(
       txn,
       "MySpatialSimulation",
       pos
   )
    Log.debug("Destination_endpoint = %s", destination_endpoint)

   for id in range(num_messages_to_send):
       # Message struct that'll be serialized into payload
        message_tick_and_id = MessageTickAndId(id = id, tick = tick.value)
        
       # Create the payload out of the struct
        message_tick_and_id_data = struct.pack(
           '<ii',
           message_tick_and_id.id,
           message_tick_and_id.tick
       )
        payload = api.MessagePayload(list(message_tick_and_id_data))

        # Send the payload to the destination
        Log.debug("Sending message: %s, endpoint: %s",
           message_tick_and_id,
           destination
       )
        api.send_message(
           txn,
           payload,
           destination,
           api.MessageDeliveryType.BestEffort
       )

    Log.info("Sent %s messages to %s", num_messages_to_send, destination)
    return True

Menerima pesan

SimSpace Weavermengirimkan pesan ke antrian pesan masuk partisi. Gunakan ReceiveMessages API untuk mendapatkan MessageList objek yang berisi pesan dari antrian. Proses setiap pesan dengan ExtractMessage API untuk mendapatkan data pesan.

C++
Result<void> ReceiveMessages(Txn& txn) noexcept
{
     // Fetch all the messages sent to the partition owned by the app
    WEAVERRUNTIME_TRY(auto messages, Api::ReceiveMessages(txn));
    std::cout << "Received" << messages.messages.size() << " messages" << std::endl;
    for (Api::Message& message : messages.messages)
    {
        std::cout << "Received message: " << message << std::endl;

         // Deserialize payload to the message struct
        const MessageTickAndId& receivedMessage 
            = Api::Utils::ExtractMessage<MessageTickAndId>(message);
        std::cout << "Received MessageTickAndId, Id: " << receivedMessage.id 
            <<", Tick: " << receivedMessage.tick << std::endl;
    }

    return Aws::WeaverRuntime::Success();
}
Python
# process incoming messages
def _process_incoming_messages(self, txn):
    messages = api.receive_messages(txn)
    for message in messages:
        payload_list = message.payload.data
        payload_bytes = bytes(payload_list)
        message_tick_and_id_data_struct 
           = MessageTickAndId(*struct.unpack('<ii', payload_bytes))

        Log.debug("Received message. Header: %s, message: %s", 
                    message.header, message_tick_and_id_data_struct)

    Log.info("Received %s messages", len(messages))
    return True

Membalas pengirim

Setiap pesan yang diterima berisi header pesan dengan informasi tentang pengirim asli pesan. Anda dapat menggunakan message.header.source_endpoint untuk mengirim balasan.

C++
Result<void> ReceiveMessages(Txn& txn) noexcept
{
     // Fetch all the messages sent to the partition owned by the app
    WEAVERRUNTIME_TRY(auto messages, Api::ReceiveMessages(txn));
    std::cout << "Received" << messages.messages.size() << " messages" << std::endl;
    for (Api::Message& message : messages.messages)
    {
        std::cout << "Received message: " << message << std::endl;

         // Deserialize payload to the message struct
        const MessageTickAndId& receivedMessage 
            = Api::Utils::ExtractMessage<MessageTickAndId>(message);
        std::cout << "Received MessageTickAndId, Id: " << receivedMessage.id 
            <<", Tick: " << receivedMessage.tick << std::endl;
        
        // Get the sender endpoint and payload to bounce the message back
        Api::MessageEndpoint& sender = message.header.source_endpoint;
        Api::MessagePayload& payload = message.payload;
        Api::SendMessage(txn, payload, sender);
    }

    return Aws::WeaverRuntime::Success();
}
Python
# process incoming messages
def _process_incoming_messages(self, txn):
    messages = api.receive_messages(txn)
    for message in messages:
        payload_list = message.payload.data
        payload_bytes = bytes(payload_list)
        message_tick_and_id_data_struct 
           = MessageTickAndId(*struct.unpack('<ii', payload_bytes))

        Log.debug("Received message. Header: %s, message: %s", 
                    message.header, message_tick_and_id_data_struct)
       # Get the sender endpoint and payload 
       # to bounce the message back
       sender = message.header.source_endpoint
       payload = payload_list
       api.send_message(
           txn,
           payload_list,
           sender,
           api.MessageDeliveryType.BestEffort

    Log.info("Received %s messages", len(messages))
    return True