Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# Communication par canal de données entre une application et un client Web
Les canaux de données vous permettent de communiquer en toute sécurité des messages arbitraires entre votre application Amazon GameLift Streams et le client Web (le JavaScript code s'exécutant dans le navigateur Web de l'utilisateur final). Cela permet aux utilisateurs finaux d'interagir avec l'application diffusée par Amazon GameLift Streams, via le navigateur Web dans lequel ils visionnent le flux.
Voici quelques exemples de cas d'utilisation de canaux de données dans Amazon GameLift Streams :
+ Les utilisateurs peuvent ouvrir URLs l'application dans leur navigateur local.
+ Les utilisateurs peuvent transmettre le contenu du presse-papiers à l'application dans les deux sens.
+ Les utilisateurs peuvent télécharger du contenu depuis leur machine locale vers l'application.
+ Les développeurs peuvent implémenter une interface utilisateur dans le navigateur qui envoie des commandes à l'application.
+ Les utilisateurs peuvent transmettre des schémas pour contrôler l'affichage des couches de visualisation.
## Fonctionnalités
**Limites de taille des messages**
Le SDK Web Amazon GameLift Streams impose une limite de taille maximale de 64 Ko (65536 octets) par message. Cela garantit que les limites de taille des messages sont compatibles avec la plupart des navigateurs et que la communication a un faible impact sur la bande passante totale du flux.
**Métriques**
Les mesures relatives à l'utilisation de vos canaux de données sont envoyées à votre compte AWS à la fin d'une session de streaming. Pour plus d'informations, reportez-vous [Canaux de données](monitoring-cloudwatch.md#monitoring-data-channels) à la section *Monitoring Amazon GameLift Streams*.
## Utilisation des canaux de données
Le SDK Web Amazon GameLift Streams fournit la `sendApplicationMessage` fonction qui envoie un message sous forme de tableau d'octets à l'application. Le message est traité par une fonction de rappel `clientConnection.applicationMessage` que vous définissez.
Si le client envoie des messages avant que l'application ne se connecte au port du canal de données, les messages sont mis en file d'attente. Ensuite, lorsque l'application se connecte, elle reçoit les messages. Toutefois, si l'application envoie des messages avant que le client ne se connecte au port du canal de données, les messages sont perdus. L'application doit vérifier l'état de connexion des clients avant d'envoyer un message.
## Du côté du client
Écrivez le code suivant dans votre application cliente Web.
1. Définissez la fonction de rappel pour recevoir les messages entrants de l'application.
```
function streamApplicationMessageCallback(message) {
console.log('Received ' + message.length + ' bytes of message from
Application');
}
```
1. Réglez `clientConnection.applicationMessage` sur votre fonction de rappel.
```
clientConnection: {
connectionState: streamConnectionStateCallback,
channelError: streamChannelErrorCallback,
serverDisconnect: streamServerDisconnectCallback,
applicationMessage: streamApplicationMessageCallback,
}
```
1. Appelez la `GameLiftStreams.sendApplicationMessage` fonction pour envoyer des messages à votre application. Vous pouvez l'appeler à tout moment, tant que la session de diffusion est active et que l'entrée est jointe.
À titre d'exemple, reportez-vous à l'exemple de client Amazon GameLift Streams Web SDK, qui montre comment configurer un canal de données simple côté client.
## Du côté de l'application
Écrivez la logique suivante dans votre application.
### Étape 1. Connectez-vous au port du canal de données
Lorsque votre application démarre, connectez-vous au port `40712` activé`localhost`. Votre application doit conserver cette connexion pendant toute la durée de son exécution. Si l'application ferme la connexion, elle ne peut pas être rouverte.
### Étape 2. Écoutez les événements
Un événement commence par un en-tête de taille fixe, suivi de données associées de longueur variable. Lorsque votre application reçoit un événement, analysez-le pour récupérer les informations.
**Format d’événement**
+ **En-tête** : un en-tête de 4 octets sous la forme `abcc`
+ `a`: octet d'identifiant du client. Cela permet d'identifier une connexion client spécifique, dans le cas de connexions multiples (en raison d'une déconnexion ou d'une reconnexion).
+ `b`: octet de type d'événement. `0`- le client est connecté, `1` - le client est déconnecté, `2` - un message est envoyé par le client. D'autres types d'événements peuvent être reçus lors des futures mises à jour du service Amazon GameLift Streams et doivent être ignorés.
+ `cc`: longueur des données d'événement associées. Cela est représenté par 2 octets dans un ordre big-endian (le premier octet est le plus significatif). Si le type d'événement est 2, les données de l'événement représentent le contenu du message envoyé par le client.
+ **Données** : Les octets restants contiennent les données de l'événement, telles qu'un message client. La longueur des données est indiquée `cc` dans l'en-tête.
**Pour écouter les événements**
1. Lisez les quatre octets d'en-tête pour récupérer l'identifiant du client, le type d'événement et la longueur des données d'événement.
1. Lisez les données d'événement de longueur variable, quels que soient l'identifiant du client et le type d'événement, conformément à la longueur décrite dans l'en-tête. Il est important de lire les données de manière inconditionnelle afin que les données d'événements ne soient jamais laissées dans la mémoire tampon, où elles pourraient être confondues avec l'en-tête de l'événement suivant. Ne faites pas d'hypothèses sur la longueur des données en fonction des types d'événements.
1. Prenez les mesures appropriées en fonction du type d'événement, s'il est reconnu par votre application. Cette action peut inclure l'enregistrement d'une connexion entrante ou d'une déconnexion, ou l'analyse du message du client et le déclenchement de la logique de l'application.
### Étape 3. Transmettre des messages au client
L'application doit transmettre les messages avec le même format d'en-tête à quatre octets que celui utilisé pour les événements entrants.
**Pour transmettre un message au client**
1. Écrivez l'en-tête avec les propriétés suivantes :
1. `a`: octet d'identifiant du client. Si votre message est une réponse à un message client, il doit utiliser le même identifiant client que le message client entrant, afin d'éviter des situations de course telles que l'envoi d'une réponse depuis une ancienne connexion client à un client récemment reconnecté. Si votre application envoie un message non sollicité au client, elle doit définir l'identifiant du client de manière à ce qu'il corresponde à l'événement de « connexion client » le plus récent (type d'événement 0).
1. `b`: Le type d'événement des messages sortants doit toujours être 2. Le client ignore les messages contenant d'autres types d'événements.
1. `cc`: longueur du message, en octets.
1. Écrivez les octets du message.
Le message est livré au client spécifié, sauf si le client se déconnecte. Lorsqu'un client déconnecté se reconnecte, un nouvel identifiant client est attribué par le biais d'un événement client connecté. Tous les messages non remis correspondant à l'ancien identifiant client sont supprimés.
**Example**
Le pseudo-code suivant illustre la logique de communication des messages côté application. Pour un exemple complet d'utilisation de Winsock, reportez-vous à la section [Complete Winsock Client Code](https://learn.microsoft.com/en-us/windows/win32/winsock/complete-client-code) dans la documentation de Windows Sockets 2.
```
connection = connect_to_tcp_socket("localhost:40712")
loop:
while has_pending_bytes(connection):
client_id = read_unsigned_byte(connection)
event_type = read_unsigned_byte(connection)
event_length = 256 * read_unsigned_byte(connection)
event_length = event_length + read_unsigned_byte(connection)
event_data = read_raw_bytes(connection, event_length)
if message_type == 0:
app_process_client_connected(client_id)
else if message_type == 1:
app_process_client_disconnected(client_id)
else if message_type == 2:
app_process_client_message(client_id, event_data)
else:
log("ignoring unrecognized event type")
while app_has_outgoing_messages():
target_client_id, message_bytes = app_next_outgoing_message()
message_length = length(message_bytes)
write_unsigned_byte(connection, target_client_id)
write_unsigned_byte(connection, 2)
write_unsigned_byte(connection, message_length / 256)
write_unsigned_byte(connection, message_length mod 256)
write_raw_bytes(connection, message_bytes)
```