지원 종료 공지: 2026 AWS 년 5월 20일에에 대한 지원이 종료됩니다 AWS SimSpace Weaver. 2026년 5월 20일 이후에는 SimSpace Weaver 콘솔 또는 SimSpace Weaver 리소스에 더 이상 액세스할 수 없습니다. 자세한 내용은 [AWS SimSpace Weaver 지원 종료를 참조하세요](https://docs.aws.amazon.com/simspaceweaver/latest/userguide/simspaceweaver-end-of-support.html).

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# 메시징 APIs 사용
<a name="working-with_messaging_using"></a>

메시징 APIs는 SimSpace Weaver 앱 SDK(최소 버전 1.16.0)에 포함되어 있습니다. 메시징은 C\+\+, Python 및 Unreal Engine 5 및 Unity와의 통합에서 지원됩니다.

메시지 트랜잭션을 처리하는 함수는 `SendMessage` 및 입니다`ReceiveMessages`. 전송된 모든 메시지에는 대상과 페이로드가 포함됩니다. `ReceiveMessages` API는 현재 앱의 인바운드 메시지 대기열에 있는 메시지 목록을 반환합니다.

------
#### [ C\+\+ ]

**메시지 전송**

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

**메시지 수신**

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

------
#### [ Python ]

**메시지 전송**

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

**메시지 수신**

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

------

**주제**
+ [메시지 보내기](#working-with_messaging_using_send)
+ [메시지 수신](#working-with_messaging_using_receive)
+ [발신자에게 회신](#working-with_messaging_using_reply)

## 메시지 보내기
<a name="working-with_messaging_using_send"></a>

메시지는 트랜잭션(다른 Weaver API 호출과 유사), 페이로드 및 대상으로 구성됩니다.

### 메시지 페이로드
<a name="working-with_messaging_using_send_payload"></a>

메시지 페이로드는 최대 256바이트의 유연한 데이터 구조입니다. 메시지 페이로드를 생성하는 모범 사례로 다음을 사용하는 것이 좋습니다.

**메시지 페이로드를 생성하려면**

1. 메시지 내용을 정의하는 데이터 구조(예: `struct` C\+\+의 )를 생성합니다.

1. 메시지에 보낼 값이 포함된 메시지 페이로드를 생성합니다.

1. `MessagePayload` 객체를 생성합니다.

### 메시지 대상
<a name="working-with_messaging_using_send_destination"></a>

메시지의 대상은 `MessageEndpoint` 객체에 의해 정의됩니다. 여기에는 엔드포인트 유형과 엔드포인트 ID가 모두 포함됩니다. 현재 지원되는 유일한 엔드포인트 유형은 시뮬레이션의 다른 파티션으로 메시지를 보낼 수 `Partition`있는 입니다. 엔드포인트 ID는 대상 대상의 파티션 ID입니다.

메시지에는 대상 주소를 하나만 제공할 수 있습니다. 둘 이상의 파티션에 동시에 메시지를 보내려면 여러 메시지를 생성하고 전송합니다.

위치에서 메시지 엔드포인트를 확인하는 방법에 대한 지침은 섹션을 참조하세요[메시징 작업 시 팁](working-with_messaging_tips.md).

### 메시지 전송
<a name="working-with_messaging_using_send_send"></a>

대상 및 페이로드 객체를 생성한 후 `SendMessage` API를 사용할 수 있습니다.

------
#### [ C\+\+ ]

```
Api::SendMessage(transaction, payload, destination, MessageDeliveryType::BestEffort);
```

------
#### [ Python ]

```
api.send_message(txn, payload, destination, api.MessageDeliveryType.BestEffort)
```

------

**메시지 전송의 전체 예**  
다음 예제에서는 일반 메시지를 구성하고 전송하는 방법을 보여줍니다. 이 예제에서는 16개의 개별 메시지를 보냅니다. 각 메시지에는 값이 0과 15 사이인 페이로드와 현재 시뮬레이션 틱이 포함되어 있습니다.

**Example**  

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

```
# 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
```

## 메시지 수신
<a name="working-with_messaging_using_receive"></a>

SimSpace Weaver 는 파티션의 인바운드 메시지 대기열로 메시지를 전송합니다. `ReceiveMessages` API를 사용하여 대기열에서 메시지가 포함된 `MessageList` 객체를 가져옵니다. `ExtractMessage` API로 각 메시지를 처리하여 메시지 데이터를 가져옵니다.

**Example**  

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

```
# 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
```

## 발신자에게 회신
<a name="working-with_messaging_using_reply"></a>

수신된 모든 메시지에는 메시지의 원래 발신자에 대한 정보가 포함된 메시지 헤더가 포함되어 있습니다. message.header.source\_endpoint를 사용하여 회신을 보낼 수 있습니다.

**Example**  

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

```
# 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
```