POST /secure/send de l’API REST avec un transport binaire : le même login, les
mêmes champs, la même tarification et le même débit, la même approbation des sender IDs et des
modèles, la même vérification de routage, la même règle de retry client_ref et la même limite de
débit par compte. Une fois accepté, un message envoyé sur gRPC ne se distingue pas d’un message
envoyé sur REST.
Il ajoute une chose que REST n’a pas : un flux d’accusés. Demandez des accusés sans donner de
webhook et ils vous attendent dans une file durable que vous lisez sur la même connexion — aucun
endpoint à faire tourner de votre côté.
gRPC est désactivé tant que votre fournisseur ne l’active pas. Une passerelle qui n’a pas été
configurée pour gRPC répond à chaque appel
UNAVAILABLE avec le code d’erreur GRPC_DISABLED. Si
vous voyez cela, l’API existe mais n’est pas activée sur la plateforme que vous appelez — demandez
l’adresse gRPC à votre fournisseur.Quand le choisir
Une requête fait quelques dizaines d’octets de protobuf au lieu d’un corps JSON, et
SendStream envoie de nombreux
messages sur un seul flux sans attendre chaque réponse. Ni l’un ni l’autre ne change ce que vous avez
le droit d’envoyer ni à quelle vitesse : REST et gRPC partagent la limite de messages par seconde de
votre compte, donc déplacer du trafic de l’un vers l’autre ne vous en donne pas davantage.
SMPP reste la troisième voie d’entrée, et elle est encore distincte — voir
Binding.
Trois services
Se connecter
Votre fournisseur vous donne un hôte et un port. Sur une passerelle sans rien devant elle, le port est généralement 8090 ; derrière le proxy TLS d’un fournisseur, c’est souvent 443.
gRPC a besoin de HTTP/2 de bout en bout. Si les appels échouent au niveau du transport avant que la
passerelle ne réponde, quelque chose entre vous et elle parle HTTP/1.1.
Le contrat
Le contrat est un seul fichier,fireflo.proto, package protobuf fireflo.v1. Il est reproduit
intégralement sur Le fichier proto.
Il est figé à partir de 0.15.9 de la même manière que l’API REST est figée : les numéros de champs
ne sont jamais réutilisés ni renumérotés, rien n’est retiré, et les ajouts arrivent sous forme de
nouveaux champs optionnels, de nouveaux messages et de nouvelles méthodes. Un client généré à partir du
fichier 0.15.9 continue de fonctionner avec toute passerelle ultérieure ; il ne voit simplement pas ce
qui a été ajouté après lui.
Obtenir le proto
Chacune de ces voies vous donne le même fichier :-
Depuis la passerelle elle-même. La réflexion serveur est activée par défaut, donc un outil qui la
parle n’a besoin d’aucun fichier :
Votre fournisseur a pu désactiver la réflexion ; utilisez alors l’une des deux autres voies.
- Depuis ce site : Le fichier proto, à copier ou télécharger.
-
Auprès de votre fournisseur, sous le nom
fireflo.proto.
protoc avec le plugin gRPC,
buf generate, python -m grpc_tools.protoc, ou le plugin protobuf de Gradle ou de Maven. Le fichier
définit go_package (fireflo/v1;fireflov1) et csharp_namespace (FireFlo.V1) ; en Java, les
classes générées sont dans le package fireflo.v1. Il n’importe que google/protobuf/timestamp.proto,
que toute distribution protobuf fournit.
Limites qui s’appliquent à chaque appel
Votre fournisseur peut modifier chacune de ces valeurs ; les chiffres ci-dessus sont les valeurs par
défaut.
Pour aller plus loin
Authentification et sessions
Connectez-vous une fois, portez le jeton, reconnectez-vous sur SESSION_EXPIRED.
Envoyer des messages
Send et SendStream, chaque champ à côté de son nom REST.
Erreurs et codes de statut
Statut REST, code gRPC, code d’erreur, et que faire.
Accusés de livraison sur gRPC
Subscribe, Pull et Ack — au moins une fois.
Exemples
grpcurl, Python, Java et Go.
Le fichier proto
Le contrat complet.