[PYTHON] Compréhension du mécanisme Twilio # 2-Structure des données de flux de communication
Cet article est une continuation de l'article suivant. Certains termes sont définis de manière unique dans la série d'articles, il est donc recommandé de les lire en premier. Compréhension du mécanisme Twilio # 1 --Introduction
Cette section décrit le flux de communication lors de l'utilisation de Twilio et la structure de données à envoyer et à recevoir.
―― 1. Introduction ―― 1. Définition de la structure de base et des termes lors de l'utilisation de Twilio ―― 2. Environnement vérifié cette fois ―― 2. ** Structure des données du flux de communication ← Maintenant ici **
- ** 1. Transfert de jeton d'authentification / capacité **
- ** 2. Appel (appel entrant) depuis un téléphone externe vers un client Twilio **
- ** 3. Appel du client Twilio vers un téléphone externe (OutgoingCall) ** --3-1. Procédure pas à pas d'implémentation d'AWS API Gateway + Lambda (Partie 1) ―― 1. Implémentation du traitement API Server (Python sur AWS Lambda) --2 paramètres de la passerelle API --3-2. Procédure pas à pas d'implémentation AWS API Gateway + Lambda (partie 2) ―― 3. Implémentation et déploiement de Twilio Client ―― 4. Contrôle de fonctionnement!
Le client Twilio à réaliser cette fois visait à pouvoir faire la même chose qu'un téléphone normal. Les spécifications spécifiques sont les suivantes.
--Ce que tu peux faire --Depuis Twilio Client, vous pouvez passer un appel téléphonique général en spécifiant n'importe quel numéro (appel sortant)
- Vous pouvez passer un appel vers Twilio Client à partir d'un téléphone ordinaire (appel entrant)
- Spécifications du client Twilio --Seul le numéro de téléphone Twilio est conservé comme valeur qui s'identifie. Il ne conserve pas son propre nom de client.
- Implémenté en HTML / JavaScript et placé sur S3.
On suppose que les paramètres tels que le numéro de téléphone sont les suivants.
| Paramètres | valeur | Explication / Remarques |
|---|---|---|
| Numéro de téléphone Twilio | 050-3123-4567 | Le numéro de téléphone attribué au client Twilio. Veuillez acheter à l'avance sur la console Twilio. |
| Client Name | DeviceId_0001 | Le nom utilisé pour identifier et contrôler le client Twilio dans le serveur Twilio. |
| Téléphone externe | 090-5987-6543 | Téléphone à l'extérieur de Twilio. Veuillez utiliser votre propre téléphone portable. |
Transfert de jeton d'authentification / capacité
Flux de traitement
Tout d'abord, regardez la figure ci-dessous.
Le flux de traitement est le suivant.
--1-1. Demande d'obtention d'un jeton de capacité
- Le client Twilio demande au serveur API d'obtenir un jeton de capacité. --API Server authentifie et autorise si nécessaire sur la base des informations envoyées par le client Twilio. --1-2. Renvoi du jeton de capacité --API Server génère un jeton de capacité et le renvoie au client Twilio.
- À ce stade, des informations telles que ce que vous pouvez faire avec le jeton de capacité (vous pouvez passer / recevoir des appels), le nom du client du client Twilio et la date d'expiration seront fournies. --1-3. Configuration du client Twilio
- Le client Twilio exécutera le processus de configuration nécessaire après avoir reçu avec succès le jeton de capacité.
- Pour JavaScript, exécutez Twilio.Device.setup. (https://www.twilio.com/docs/api/client/device#method-reference)
- Pour Android, exécutez Twilio # createDevice pour créer un objet Device. (https://jp.twilio.com/docs/api/client/android/Twilio#createDevice_String__DeviceListener_) --Il semble que le jeton de capacité soit transmis au serveur Twilio lors de l'exécution du processus de configuration. Il semble que le jeton de capacité soit vérifié par Twilio Server et que le succès ou l'échec soit renvoyé à Twilio Client. (* Les détails ne sont pas confirmés)
La mise en œuvre de la méthode de communication entre 1-1 et 1-2 est entièrement à la discrétion de l'utilisateur. Il est également possible d'utiliser HTTP / HTTPS et d'autres protocoles pour la communication.
La structure des données est également complètement arbitraire. Les informations envoyées par le client Twilio peuvent inclure un nom d'utilisateur, un mot de passe et d'autres informations pour identifier le client Twilio. Il est également possible de réaliser une authentification / autorisation arbitraire. Le jeton de capacité est requis comme informations renvoyées par API Server, mais toute autre information peut être retournée.
Dans cette vérification, la demande et la réponse ont été implémentées dans JSON. La structure de données spécifique est la suivante.
La demande était simplement un numéro de téléphone Twilio. Si le numéro de téléphone Twilio spécifié a déjà été obtenu, l'authentification est réussie.
"+81-50-1234-9876"}
La réponse a été le jeton de capacité et le succès ou l'échec du processus.
#### **`{"capabilityToken": capabilityToken, "success": True}`**
La communication 1-3 n'a pas été vérifiée. Les détails sont inconnus. Dans le cas du client JavaScript, il semble que WebSocket soit utilisé pour envoyer des informations telles que Capability Token au serveur Twilio. La configuration initiale est effectuée à partir de divers SDK fournis par Twilio, les utilisateurs n'ont donc généralement pas besoin d'en être conscients. \ # Cependant, je pense qu'il peut y avoir des cas où ces informations sont nécessaires lors du dépannage.
Création de jetons de capacité / structure de données
Le serveur API utilise la bibliothèque d'assistance de Twilio pour générer des jetons de capacité.
L'explication est basée sur l'implémentation en Python 2.7. On suppose que les bibliothèques nécessaires sont déjà installées et disponibles. https://www.twilio.com/docs/libraries/python#help En outre, il est supposé que le compte Twilio a été ouvert et que le SID du compte et le jeton d'authentification ont été confirmés, et que l'application TwiML a été créée et que le SID de l'application a été confirmé.
from twilio.util import TwilioCapability
import json
def generate_capability_token(twilio_phone_number):
#Définissez les paramètres requis.
twilio_account_sid = "{{twilio_accound_sid}}" #Spécifiez le SID de votre compte Twilio.
twilio_auth_token = "{{twilio_account_auth_token}}" #Spécifiez le jeton d'authentification associé à votre compte Twilio.
twilio_app_sid = "{{twilio_app_sid}}" #Spécifiez l'application Sid créée à l'avance.
expiration_time_for_capability_token = 3600 #Spécifie la date d'expiration du jeton de capacité.
#Générez un jeton de capacité et accordez les autorisations requises.
capability = TwilioCapability(twilio_account_sid, twilio_auth_token)
capability.allow_client_incoming(get_client_name_by_phone_number(twilio_phone_number)) #Obtient le nom du client Twilio en fonction du numéro de téléphone Twilio spécifié. avoir_client_name_by_phone_nombre est une fonction que vous avez implémentée individuellement.
capability.allow_client_outgoing(twilio_app_sid)
capabilityToken = capability.generate(expiration_time_for_capability_token)
#Conversion à la structure par défaut et retour.
res = {"capabilityToken": capabilityToken, "success": True}
return json.dumps(res)
Fondamentalement, il sera mis en œuvre selon le document suivant. Generate Capability Tokens http://twilio-python.readthedocs.io/en/latest/usage/token-generation.html
Après avoir généré la capacité Twilio en fonction du SID du compte Twilio et du jeton d'authentification, accordez des autorisations avec les méthodes allow_client_incoming et allow_client_outgoing. Enfin, vous pouvez générer un jeton de capacité en exécutant la méthode de génération de capacité Twilio. Vous pouvez spécifier la date d'expiration en secondes comme argument.
Les détails du jeton de capacité peuvent être trouvés dans les documents suivants.
Twilio Client: Capability Tokens https://www.twilio.com/docs/api/client/capability-tokens
Le jeton de capacité est au format JWT (Json Web Token). Aucune communication avec Twilio Server n'est requise pour la génération. Bien que cela n'ait pas été vérifié, il est présumé que les informations nécessaires sont converties en JSON, une signature électronique est générée avec Auth Token et donnée, puis un décodage Base64 est effectué.
Les points importants ici sont les suivants.
- ** L'autorité pour passer un appel depuis le client Twilio est différente de l'autorité pour recevoir un appel depuis le client Twilio **
- ** L'autorité de passer un appel depuis le client Twilio doit être spécifiée dans le sid App de l'application TwiML **
- ** L'autorisation de recevoir des appels avec Twilio Client doit être spécifiée par le nom du client **
Voyons ensuite comment Twilio Client passe des appels vers d'autres téléphones.
Appel depuis un téléphone externe vers un client Twilio (appel entrant)
Flux de traitement
Tout d'abord, regardez la figure ci-dessous.
Souvenez-vous également de l'URL que vous avez définie lorsque vous avez créé votre compte Twilio et obtenu votre numéro de téléphone.
L'URL spécifiée dans "UN APPEL ENTREE" sera utilisée lors de la réception d'un appel.
Le flux de traitement est le suivant. ** Pour obtenir TwiML, l'URL définie dans le numéro de téléphone Twilio du destinataire est utilisée. ** **
--2-1. Appeler Twilio Client à partir d'un téléphone réel
- À partir d'un téléphone réel, appelez le numéro de téléphone Twilio associé au client Twilio. --Bien entendu, vous ne pouvez pas spécifier le nom du client Twilio lors d'un appel. ―― 2-2. Demande d'acquisition TwiML de Twilio Server vers API Server --Twilio Server émet une requête HTTP comme spécifié dans "UN APPEL ENTREE" du numéro de téléphone qui était la cible de l'appel.
- Les paramètres importants passés sont le numéro de téléphone source et le numéro de téléphone Twilio du destinataire. --2-3. Renvoyer TwiML du serveur API au serveur Twilio --API Server doit obtenir le nom du client qui lui est associé en fonction du numéro de téléphone Twilio passé en paramètre.
- Dès que le nom du client est obtenu, TwiML sera généré et renvoyé. ―― 2-4. Twilio Server exécute le contenu écrit en TwiML. --TwiML vous demandera de connecter le téléphone au nom de client spécifié. --Connectez le téléphone appelant au client Twilio.
TwiML à renvoyer depuis API Server
Le TwiML renvoyé par API Server dans le n ° 2-3 est le suivant. Ce TwiML signifie appeler le client Twilio spécifié.
<?xml version="1.0\" encoding="UTF-8"?>
<Response>
<Dial timeout="60">
<Client>DeviceId_0001</Client>
</Dial>
</Response>
Le numéro de téléphone Twilio lui-même ne peut pas être spécifié dans l'élément \
Par conséquent, le serveur API doit acquérir le nom du client en fonction des informations sur le numéro de téléphone Twilio du destinataire au numéro 2-3. Il est préférable de sauvegarder les informations d'association dans DB etc. à l'avance et de les acquérir lorsque TwiML est généré.
De plus, TwiML peut effectuer divers contrôles. Veuillez consulter le document officiel pour plus de détails.
https://www.twilio.com/docs/api/twiml/dial https://www.twilio.com/docs/api/twiml/client
Requête HTTP POST du serveur Twilio
Les demandes de Twilio Server à API Server sont un peu spéciales. De plus, je n'ai trouvé aucune information détaillée dans la documentation officielle. Ce qui suit est une explication basée sur les informations capturées par le paquet.
La figure ci-dessus est une capture de paquet d'une requête HTTP POST de Twilio Server. Les points sont les suivants.
--Content-Type: doit être application / x-www-form-urlencoded
- Le paramètre est une paire de valeurs clés concaténée avec "&" dans le corps de la requête HTTP et spécifiée sur une ligne (format comme le paramètre GET). --Chaque paramètre du corps de la requête HTTP doit être encodé en URL
Regardons les détails de chaque paramètre. Le numéro de téléphone de l'expéditeur est "090-5987-6543" et le numéro de téléphone Twilio du destinataire est "050-3123-4567".
| Paramètres | Description (basée sur des suppositions) |
|---|---|
| AccountSid=AC3xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | Le SID de votre compte Twilio. |
| ApiVersion=2010-04-01 | Est-ce la version API de Twilio? |
| Called=%2B815031234567 | Numéro de téléphone Twilio du destinataire. E.Format 164. Il semble que la même valeur que To sera saisie. |
| CalledCity= | |
| CalledCountry=JP | |
| CalledState= | |
| CalledVia=05031234567 | inconnue. Est-il utilisé lorsque l'appel est transféré dans Twilio? |
| CalledZip= | |
| Caller=%2B819059876543 | Le numéro de téléphone du téléphone appelant. Il semble que la même valeur que From soit entrée. |
| CallerCity= | |
| CallerCountry=JP | |
| CallerState= | |
| CallerZip= | |
| CallSid=CA86nnnnnnnnnnnnnnnnnnnnnnnnnnnnnn | S'agit-il d'un identifiant unique attribué à l'appel? |
| CallStatus=ringing | |
| Direction=inbound | Est-ce la direction de l'appel? |
| ForwardedFrom=05031234567 | inconnue. Est-il utilisé lorsque l'appel est transféré dans Twilio? |
| From=%2B819059876543 | Le numéro de téléphone du téléphone appelant. E.Format 164. Il semble que la même valeur que l'appelant sera entrée. |
| FromCity= | |
| FromCountry=JP | |
| FromState= | |
| FromZip= | |
| To=%2B815031234567 | Numéro de téléphone Twilio du destinataire. Il semble que la même valeur que Appelé sera entrée. |
| ToCity= | |
| ToCountry=JP | |
| ToState= | |
| ToZip= |
Il y a quatre paramètres importants ici: Appelant / De / Appelé / À. Dans API Server, générez TwiML en fonction de ces informations.
L'application Quick Start de Python semble utiliser Caller comme information source et To comme information sur le destinataire. Par conséquent, l'implémentation de l'API de retour TwiML pour les appels entrants doit également utiliser ce paramètre.
https://github.com/TwilioDevEd/client-quickstart-python
Appel du client Twilio vers un téléphone externe (OutgoingCall)
Flux de traitement
Tout d'abord, regardez la figure ci-dessous.
Souvenez-vous également de l'URL que vous avez définie lorsque vous avez configuré votre compte Twilio et créé l'application TwiML.
Le flux de traitement est le suivant. ** Pour obtenir TwiML, l'URL définie dans l'application TwiML est utilisée. ** **
--3-1. Faire une demande sortante depuis Twilio Client
- À partir du client Twilio, faites une demande pour passer un appel.
- À ce stade, vous pouvez ajouter n'importe quel paramètre de Twilio Client.
- Pour Android, exécutez la méthode de connexion de l'objet Device généré lors de la configuration. (https://www.twilio.com/docs/api/client/android/device#connect_java_util_Map__ConnectionListener_)
- Pour JavaScript, exécutez la méthode Twilio.Device.connect. (https://www.twilio.com/docs/api/client/device#connect) --3-2. Demande d'acquisition TwiML du serveur Twilio au serveur API --Twilio Server émet une requête HTTP comme spécifié dans "REQUEST URL" de l'application TwiML associée à CapabilityToken.
- Les paramètres importants passés sont le nom de client du client Twilio, le numéro de téléphone de destination et les paramètres transmis par le client Twilio. --3-3 Renvoyer TwiML du serveur API au serveur Twilio. --API Server doit obtenir le numéro de téléphone Twilio source et le numéro de téléphone de destination en fonction des informations passées en paramètre.
- Dès que vous obtenez les informations dont vous avez besoin, TwiML sera généré et renvoyé. --3-4 Twilio Server exécute le contenu écrit en TwiML.
- Connectez l'appel de Twilio Client au téléphone réel.
TwiML à renvoyer depuis API Server
Le TwiML renvoyé par API Server au n ° 3-3 est le suivant. Le numéro de téléphone Twilio appelant est "050-3123-4567" et le numéro de téléphone appelant est "090-5987-6543".
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Dial timeout="60" callerId="+81-50-3123-4567">
<Number>+81-90-5987-6543</Number>
</Dial>
</Response>
Dans l'élément \
Requête HTTP POST du serveur Twilio
Aucune information détaillée n'a été trouvée dans la documentation officielle. Ce qui suit est une explication basée sur les informations capturées par le paquet.
Regardons les détails de chaque paramètre. Les paramètres suivants sont ajoutés lorsque la connexion est exécutée à partir du client Twilio.
--callerPhoneNumber: Le numéro de téléphone de l'appelant qui vous est associé. --callOutgoingPhoneNumber: Le numéro de téléphone réel à appeler.
| Paramètres | Description (basée sur des suppositions) |
|---|---|
| AccountSid=AC3exxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | Le SID de votre compte Twilio. |
| ApiVersion=2010-04-01 | Est-ce la version API de Twilio? |
| ApplicationSid=AP75zzzzzzzzzzzzzzzzzzzzzzzzzzzzzz | SID de l'application TwiML associé à CapabilityToken |
| Called= | |
| Caller=client%3ADeviceId_0001 | Client Nom du client Twilio source. |
| CallSid=CA06nnnnnnnnnnnnnnnnnnnnnnnnnnnnnn | S'agit-il d'un identifiant unique attribué à l'appel? |
| CallStatus=ringing | |
| Direction=inbound | |
| From=client%3ADeviceId_0001 | Client Nom du client Twilio source. Il semble que la même valeur que Caller sera entrée. |
| To= | |
| callerPhoneNumber=%2B81-50-3123-4567 | Paramètres personnalisés spécifiés dans le client Twilio |
| callOutgoingPhoneNumber=%2B81-90-5987-6543 | Paramètres personnalisés spécifiés dans le client Twilio |
Par défaut, Appelant et De sont définis sur Nom du client. Si vous le souhaitez, vous pouvez spécifier les paramètres requis dans l'implémentation du client Twilio. Comme mentionné ci-dessus, le serveur API peut renvoyer une valeur arbitraire dans la communication lorsque le client Twilio acquiert le jeton de capacité, vous pouvez donc également passer les paramètres nécessaires au moment de la connexion ici.
finalement
C'est tout pour le flux de communication et la structure des données. À partir de maintenant, nous allons enfin commencer à mettre en œuvre. Procédure pas à pas de mise en œuvre d'AWS API Gateway + Lambda (partie 1)