Effectuer des appels API S2S depuis PostMan

brainCloud prend en charge deux variétés d'appels S2S : avec et sans sessions explicitement allouées.

Sans session : plus simple, mais moins efficace. Un identifiant de session jetable est automatiquement généré sur le serveur (via l'authentification) et supprimé après l'appel. Cette méthode prend du temps et coûte un nombre d'API supplémentaire.
Basé sur les sessions : plus rapide et moins coûteux ! Prise en charge du regroupement de requêtes. Pour l'utiliser, vous devez d'abord vous authentifier (comme pour l'API client) pour récupérer un identifiant de session, puis l'utiliser lors des appels ultérieurs tout en incrémentant l'identifiant de paquet associé au message.

Remarque : le protocole S2S basé sur les sessions, comme le protocole client, prend en charge le regroupement de plusieurs appels d'API au sein d'une même requête HTTP. Dans la plupart des cas, il est plus pratique de combiner les appels dans un seul script de cloud code.

Globalement, le protocole S2S basé sur les sessions est recommandé pour les applications de production, car il élimine la création redondante de sessions jetables. Il est plus performant et moins coûteux ! Ce tutoriel vous montrera comment simuler les deux types de requêtes via Postman.

Installation de PostMan

Pour installer Postman, il suffit de :

Télécharger depuis https://www.getpostman.com/
Choisissez votre plateforme et terminez le processus d'installation

Prérequis : Configuration des serveurs S2S

Les serveurs entrants doivent être configurés (c'est-à-dire déclarés) dans le tableau de bord brainCloud avant d'effectuer des appels S2S. Cela permet à brainCloud de confirmer que les requêtes proviennent d'un serveur dont vous êtes propriétaire et qu'elles ne sont pas malveillantes.

Lancez le portail brainCloud
Accédez à la page Conception > Serveurs > Mes serveurs . Cliquez sur le bouton [Ajouter un nouveau serveur] .
Sélectionnez Serveur personnalisé dans le menu déroulant Type de serveur.
Donnez un nom à votre serveur, comme "EXAMPLE_SERVER".
La saisie de plages d'adresses IP restreint l'accès aux requêtes provenant des adresses réseau spécifiées. Cette option est fortement recommandée pour les applications de production ! Pour l'instant, vous pouvez laisser les plages vides. Toutes les plages d'adresses IP seront alors acceptées.
Cliquez sur [Appliquer] et notez le secret de votre serveur – vous l’utiliserez plus tard.

Requêtes S2S sans session

Les requêtes sans session sont simples. Chaque requête est totalement indépendante ; aucune sessionIds ou de packetIds à gérer. Cette API est idéale lorsque les appels à brainCloud sont rares.

Pour simuler une requête serveur sans session avec Postman :

Lancez Postman
Ajouter une nouvelle demande
Définissez le type de requête sur POST
Définissez l'URL de la requête sur : "https://sharedprod.braincloudservers.com/s2sdispatcher"
Dans la section Body de la requête, choisissez brut et définissez le type sur JSON (application/json)
Copiez ce JSON dans le body, en définissant l'appId, le serverName et le serverSecret de manière appropriée pour votre application

{  
   "appId":"12142",
   "serverName":"EXAMPLE_SERVER",
   "serverSecret":"b221c2a4-8df9-4937-8f9b-a95e4f71d5b6",
   "service":"globalApp",
   "operation":"READ_PROPERTIES",
   "data":{  
   }
}

Sélectionnez [Envoyer]
Voir la réponse

À moins que vous n’ayez ajouté certaines propriétés, vous verrez une réponse JSON vide.

Pour modifier cela, accédez à la page Conception > Cloud Data > Propriétés globales du portail brainCloud et configurez une ou deux propriétés, puis exécutez à nouveau cette requête. Et voilà !

Requêtes S2S basées sur une session

Les requêtes basées sur une session nécessitent d'abord de demander un élément sessionId à utiliser via l'opération d'authentification. Vous faites ensuite référence à ce sessionId dans les requêtes suivantes, avec un élément incrémental packetId.

Tout d’abord, nous devons nous authentifier pour obtenir un SessionId

Dans Postman, ajoutez une nouvelle demande
Définissez le type de requête sur POST
Utilisez la même URL de requête : "https://sharedprod.braincloudservers.com/s2sdispatcher"
Dans l'onglet Body de la requête, choisissez brut et définissez le type sur JSON (application/json)
Copiez ce JSON dans le body, en définissant l'appId, le serverName et le serverSecret de manière appropriée pour votre application
(aux deux endroits !)
Affichez la réponse et enregistrez la sessionId renvoyé.
Maintenant, faites une deuxième demande, en utilisant cette sessionId et en définissant packetId à 1.
Pour chaque requête suivante, veillez à incrémenter le packetId.
Essayez ceci :

{
  "packetId":0,
  "messages": [
    {
      "service":"authenticationV2",
      "operation":"AUTHENTICATE",
      "data": {
        "appId":"12142",
        "serverName":"EXAMPLE_SERVER",
        "serverSecret":"b221c2a4-8df9-4937-8f9b-a95e4f71d5b6"}
      }
  ]
}

Affichez la réponse et enregistrez la sessionId qui est renvoyée.
Maintenant, faites une deuxième demande, en l'utilisant sessionId et en définissant le packetId à 1.

{
   "sessionId":"df5gelac0mhrpht31ffgtgatoe",
   "packetId":1,
   "messages":[
      {
         "service":"globalEntity",
         "operation":"CREATE_SYSTEM_ENTITY",
         "data":{
            "entityType":"address",
            "timeToLive":null,
            "acl":{
               "other":1
            },
            "data":{
               "street":"1309 Carling"
            }
         }
      }
   ]
}

Pour chaque requête suivante, veillez à incrémenter le packetId. Essayez ceci :

{  
   "sessionId":"df5gelac0mhrpht31ffgtgatoe",
   "packetId":2,
   "messages":[  
      {  
         "service":"globalEntity",
         "operation":"GET_LIST",
         "data":{  
            "where":{  
               "entityType":"address"
            },
            "orderBy":{  
            },
            "maxReturn":50
         }
      }
   ]
}

Alors, vous comprenez l’idée.

Choses importantes à retenir :

Incrémentez toujours le paramètre packetId, sauf en cas de tentatives identiques. Si vous réessayez la même requête suite à une panne de communication, conservez le packetId (cela permet au serveur d'éviter les doublons). Si vous recevez une réponse du serveur, qu'elle soit positive ou négative, incrémentez le paramètre packetId pour votre prochaine requête.

Codes de service et d'exploitation

Les appels d'API documentés dans l'API Ref ( http://getbraincloud.com/apidocs/apiref/?raw#s2s ) sont mappés à des services et opérations discrets sur le serveur.

Les codes, ainsi que les paramètres spécifiques à l'opération (spécifiés dans l'objet JSON data) sont utilisés pour envoyer des commandes au serveur.

Seuls les appels API de la section S2S de la référence API peuvent être utilisés pour les appels S2S.