Essayez d'implémenter un robot Cisco Spark avec AWS Lambda + Amazon API Gateway (Python)

1. Présentation de Cisco Spark Bot

Cisco Spark a une fonction Bot. Au lieu de mentionner et de parler à une personne, lorsque vous mentionnez et parlez à un Bot, le Bot le comprend comme une commande, le traite et renvoie le message résultant (en fait, le Bot ne fait que relayer et le traitement réel est effectué. Un autre programme fait).

Cela dépend de l'idée du type de traitement effectué et du type de résultat renvoyé. Le processus le plus simple ici consiste à créer un bot qui répond au message ping avec pong. Pour la partie de traitement proprement dite, la passerelle d'API AWS Lambda + Amazon sera utilisée.

1-1. Présentation du traitement

1. Mentionnez le Bot et postez un message
2. Le bot envoie (relais) à l'URL cible au format suivant:

• Assurez-vous d'utiliser HTTP POST
• La charge utile utilise un format standard (appelé Envelop)
• Les données atypiques sont placées dans «données» dans Envelop

1. C'est le rôle d'API Gateway d'avoir l'URL cible
2. Lambda lance la réception d'API Gateway en tant que "déclencheur"
3. La réaction au POST de Bot doit être programmée par vous-même dans Lambda

Notez que lorsque le Bot HTTP POST à l'URL cible en 2., la charge utile ** ne contient pas le message lui-même, seulement l'ID de message **. Pour obtenir le message lui-même, vous devez effectuer un HTTP GET de Lambda à Cisco Spark pour obtenir le message correspondant à l'ID. Préparez vous-même ce programme (6 sur la figure). Vous devez également préparer un programme (HTTP POST) qui affiche les résultats dans Cisco Spark (7 sur la figure).

2. Procédure de configuration côté Cisco Spark

2-1. Créer un bot

Vous devez vous connecter en tant qu'utilisateur réel pour créer un bot. Parce que Bot est enregistré en association avec l'utilisateur réel.

Accédez au site suivant et cliquez sur "Créer un robot": https://developer.ciscospark.com/add-app.html

Remplissez les trois éléments suivants sur l'écran suivant:

• Nom d'affichage: le nom du bot
• Nom d'utilisateur du bot: identifiant. Cela peut être le même que le nom du Bot, mais il ne doit pas être dupliqué avec d'autres
• Icône: entrez l'URL de l'image

Si vous le saisissez correctement, le jeton d'accès pour Bot sera affiché, alors notez-le. Il n'expirera pas. Manipuler avec soin.

2-2. Ajouter un bot à la pièce

Ouvrez Cisco Spark, accédez à n'importe quelle salle et ajoutez le bot à la salle de la même manière que vous ajouteriez une personne à une salle (recherchez par le nom du bot, puis ajoutez).

2-3. À propos de Webhook

Lorsque vous publiez un message sur Cisco Spark, le Bot le relaie et le transmet à un autre programme via HTTP POST. Il existe différentes manières de traiter le programme, mais le résultat est généralement renvoyé au Bot (appelé rappel) et affiché sur Cisco Spark. Le mécanisme de rappel par HTTP est appelé Webhook.

L'URL cible est particulièrement importante pour la configuration des webhooks. Le Bot est la destination pour lancer HTTP POST à l'URL spécifiée qui existe sur Internet.

L'URL cible et le programme doivent être préparés par le créateur du Bot. Pour cela, par exemple, vous pouvez utiliser la méthode conventionnelle telle que la préparation d'un serveur, l'installation du système d'exploitation, l'exécution du serveur Web, l'attribution d'une adresse IP, puis l'attribution d'une URL. Comme cela prend beaucoup de temps et d'efforts, nous préparons ici l'URL cible à l'aide d'API Gateway et exécutons le programme réel sur Lambda.

Pour déterminer l'URL cible, vous devez d'abord configurer Lambda + API Gateway. Configurez le webhook Cisco Spark dans 4-1.1.

3. Paramètres latéraux AWS Lambda + Amazon API Gateway

• Cette section décrit [Utilisation d'AWS Lambda avec Amazon API Gateway (via HTTPS à la demande)](http://docs.aws.amazon.com/ja_jp/lambda/latest/dg/with-on-demand-https- En utilisant le didacticiel dans example.html) comme informations de base, nous avons personnalisé les étapes nécessaires pour prendre en charge Cisco Spark Bot.

• On suppose que les paramètres AWS Management Console et AWS CLI ont été définis et sont accessibles. S'il n'est pas terminé, reportez-vous à l '«Étape 1» de cet article. Veuillez compléter le réglage en vous référant à ": Préparation".

3-1. Créer un package de déploiement pour Python

Un package de déploiement est une version compressée des deux suivants sous forme de fichier zip:

• Programme Lambda (cette fois Python3.6)
• Bibliothèque utilisée par le ci-dessus

Suivez les étapes ci-dessous pour créer:

1. Connectez-vous à l'AWS CLI.
2. Créez un programme Python pour Lambda. Le nom de fichier doit être le même que le nom de la fonction Lambda (LF4CiscoSpark). Ici, créez l'exemple de programme suivant:

$ vi LF4CiscoSpark.py
---
from __future__ import print_function

import boto3
import json
import requests
import logging

logger = logging.getLogger()
logger.setLevel(logging.INFO)

access_code = ''        #Entrez le code d'accès au bot
botDisplayName = ''     #Entrez le nom du bot

def sendSparkGET(event):
    url = 'https://api.ciscospark.com/v1/messages/{0}'.format(event.get('data')['id'])
    headers = {
        'Authorization' : 'Bearer ' + access_code,
        'Content-Type' : 'application/json'
    }
    r1 = requests.get(url, headers = headers)
    return json.loads(r1.text)

def sendSparkPOST(event,message_detail):
    url = 'https://api.ciscospark.com/v1/messages/'
    headers = {
        'Authorization' : 'Bearer ' + access_code,
        'Content-Type' : 'application/json'
    }
    payload = {
      "roomId" : event.get('data')['roomId'],
      "text" : 'pong'
    }
    r1 = requests.post(url, headers = headers, data = json.dumps(payload))
    return True

def handler(event, context):
    print("Received event: " + json.dumps(event, indent=2))

    message_detail = sendSparkGET(event)
    bot_command = message_detail['text']
    
    bot_commands = {
        botDisplayName + 'ping' : lambda x, y : sendSparkPOST(x, y)
    }

    if bot_command in bot_commands:
        return bot_commands[bot_command](event,message_detail)
    else:
        raise ValueError('Unrecognized operation')
---

3. Les requêtes sont importées dans le programme ci-dessus, mais elles ne sont pas incluses par défaut dans l'environnement d'exécution Lambda. Si vous souhaitez utiliser une bibliothèque non standard, vous devez inclure le fichier de la bibliothèque correspondante (requêtes) dans le package de déploiement. Les fichiers correspondants doivent normalement être dans site-packages, donc commencez par compresser le répertoire site-packages / requests:

$ zip LF4CiscoSpark.zip -r /(path-to-site-packages)/site-packages/requests

4. Ensuite, ajoutez le LF4CiscoSpark.py que vous venez de créer au fichier zip:

$ zip -g LF4CiscoSpark.zip LF4CiscoSpark.py

À propos du programme

Mentionnez le Bot et envoyez un message "ping", et le Bot répondra "pong". Si vous souhaitez utiliser une commande autre que "ping", décrivez le processus dans bot_commands.

• sendSparkGET ()… Correspond à 6 dans la figure «1-1. Vue d'ensemble du traitement»
• sendSparkPOST ()… Correspond à 7 dans la figure «1-1. Vue d'ensemble du traitement»

3-2. Créer un rôle IAM

IAM est un mécanisme qui contrôle les ressources AWS auxquelles les utilisateurs peuvent accéder et comment elles peuvent être utilisées. En tant que procédure de configuration générale, 1) créez un rôle, 2) créez une stratégie et 3) associez une stratégie à un rôle. Puisque la politique utilise la politique standard cette fois, il n'est pas nécessaire d'effectuer 2). Lorsque la procédure est terminée, vous verrez une chaîne appelée Role ARN. Cela est nécessaire pour créer la fonction Lambda à l'étape suivante.

1. Connectez-vous à la console IAM (https://console.aws.amazon.com/iam/).
2. Cliquez sur "Rouler".
3. Cliquez sur Créer un nouveau rôle.
4. Assurez-vous que le rôle de service AWS est sélectionné.
5. Cliquez sur Sélectionner en regard d'AWS Lambda.
6. Entrez lambda dans le champ intitulé "Filtre"
7. Vérifiez la stratégie appropriée parmi les stratégies standard affichées. Ici, sélectionnez AWSLambdaBasicExecutionRole. Remarque) Il est important de sélectionner une stratégie appropriée pour la sécurité. Il existe une liste des stratégies standard AWS sur ici, recherchez donc le nom de la stratégie avec "AWSLambda" et sélectionnez celle qui est plus appropriée que AWSLambdaBasicExecutionRole. Vous devez faire attention à "Action" et comparer.
8. Le "nom du rôle" est lambda-gateway-execution-role.
9. Cliquez sur Créer un rôle.
10. Cliquez sur le rôle d'exécution de passerelle lambda que vous venez de créer (le nom du rôle au lieu de le vérifier)
11. Notez le rôle ARN (chaîne commençant par arn :). Ceci est nécessaire pour créer la fonction Lambda à l'étape suivante

3-3. Créer une fonction Lambda

1. Connectez-vous à l'AWS CLI.
2. Créez une fonction lambda avec la commande suivante. Pour arn:, spécifiez celui obtenu à l'étape précédente, et pour la région et le profil, spécifiez ceux qui conviennent. Il semble que le nom du fichier zip et le nom du gestionnaire doivent être les mêmes que le nom de la fonction.

$ aws lambda create-function --region us-west-2 \
--function-name LF4CiscoSpark \
--zip-file fileb://LF4CiscoSpark.zip \
--role arn:xxxxxxxxxxxxxxxxxx \
--handler LF4CiscoSpark.handler \
--runtime python3.6 \
--profile adminuser

• Lors de la mise à jour du code:

$ aws lambda update-function-code \
--function-name LF4CiscoSpark \
--zip-file fileb://LF4CiscoSpark.zip

3-4. Créer une passerelle API

Cette fois, nous utiliserons l'AWS CLI pour créer API Gateway. Il y a quelques étapes, mais il est plus facile de comprendre si vous travaillez en vérifiant les résultats du travail dans la CLI un par un sur la console AWS.

3-4-1. Création d'une API

1. Connectez-vous à l'AWS CLI.
2. Créez une API nommée API4CiscoSpark avec la commande suivante. Si la création réussit, un ID d'API sera généré pour identifier l'API.

• Lorsque l'API est générée, la ressource racine est également générée en même temps. Suivez les étapes ci-dessous pour créer une ressource enfant pour la ressource racine, mais vous avez également besoin de l'ID de la ressource racine pour cela.

$ aws apigateway create-rest-api \
--name API4CiscoSpark \
--region us-west-2 \
--profile adminuser
(Résultat d'exécution ci-dessous)
{
    "name": "API4CiscoSpark",
    "createdDate": 1501839827,
    "id": ""				           # API ID
}

Résultat d'affichage de la console AWS (API Gateway):

3. Découvrez l'ID de la ressource racine de l'API:

$ aws apigateway get-resources \
--rest-api-id (API ID)
(Résultat d'exécution ci-dessous)
{
    "items": [
        {
            "path": "/",
            "id": ""			       # ROOT RESOURCE ID
        }
    ]
}

3-4-2. Création de ressources enfants API

1. Créez une ressource enfant Resource4CiscoSpark de l'API API4CiscoSpark avec la commande suivante:

$ aws apigateway create-resource \
--rest-api-id (API ID) \
--parent-id (ROOT RESOURCE ID) \
--path-part Resource4CiscoSpark
(Résultat d'exécution ci-dessous)
{
    "pathPart": "Resource4CiscoSpark",
    "parentId": "",
    "path": "/Resource4CiscoSpark",
    "id": ""			                # RESOURCE ID
}

Résultat d'affichage de la console AWS (API Gateway):

3-4-3. Création d'une méthode

1. Ajoutez une méthode POST à la ressource Resource4CiscoSpark avec la commande suivante:

$ aws apigateway put-method \
--rest-api-id (API ID) \
--resource-id (RESOURCE ID) \
--http-method POST \
--authorization-type NONE

Résultat d'affichage de la console AWS:

3-4-4. Définir la fonction Lambda comme destination de la méthode POST

1. Définissez la fonction Lambda comme destination de la méthode POST à l'aide de la commande suivante. Entrez le numéro à 12 chiffres de votre numéro de compte AWS dans (Numéro de compte):

$ aws apigateway put-integration \
--rest-api-id (API ID) \
--resource-id (RESOURCE ID) \
--http-method POST \
--type AWS \
--integration-http-method POST \
--uri arn:aws:apigateway:(region):lambda:path/2015-03-31/functions/arn:aws:lambda:(region):(Numéro de compte):function:LF4CiscoSpark/invocations

Résultat d'affichage de la console AWS (API Gateway):

3-4-5. Définissez la réponse de la méthode POST sur JSON

1. Définissez la réponse de la méthode POST sur JSON avec la commande suivante. Ce paramètre spécifie le type de réponse renvoyé par la méthode API.

$ aws apigateway put-method-response \
--rest-api-id (API ID) \
--resource-id (RESOURCE ID) \
--http-method POST \
--status-code 200 \
--response-models "{\"application/json\": \"Empty\"}"

3-4-6. Définissez la réponse intégrée de la méthode POST sur JSON

1. Définissez la réponse intégrée de la méthode POST sur JSON avec la commande suivante. Avec ce paramètre Spécifie le type de réponse renvoyé par la fonction Lambda.

$ aws apigateway put-integration-response \
--rest-api-id (API ID) \
--resource-id (RESOURCE ID) \
--http-method POST \
--status-code 200 \
--response-templates "{\"application/json\": \"\"}"

Résultat d'affichage de la console AWS (API Gateway):

3-4-7. Déployer l'API

1. Déployez l'API créée à l'étape appelée prod (production = environnement de production) avec la commande suivante:

$ aws apigateway create-deployment \
--rest-api-id (API ID) \
--stage-name prod

Résultat d'affichage de la console AWS (API Gateway):

L'URL répertoriée à droite de Appel d'une URL est l'URL cible des webhooks Cisco Spark.

3-4-8. Spécifier API Gateway comme déclencheur pour Lambda

$ aws lambda add-permission \
--function-name LF4CiscoSpark \
--statement-id apigateway \
--action lambda:InvokeFunction \
--principal apigateway.amazonaws.com \
--source-arn "arn:aws:execute-api:us-west-2:(Numéro de compte):(API ID)/prod/POST/Resource4CiscoSpark"

Résultat d'affichage de la console AWS (* AWS Lambda *):

4. Achèvement du réglage et du contrôle de fonctionnement

4-1. Configuration d'un webhook dans Cisco Spark

Pour configurer un webhook, exécutez HTTP PUT dans les conditions suivantes:

• URL:
• Spécifiez https://api.ciscospark.com/v1/webhooks
• Entête
• 'Authorization': 'Bearer' + code d'accès au bot
• 'Content-Type': spécifiez 'application / json'
• Charge utile
• 'name': nommer arbitrairement le webhook
• 'targetUrl': URL cible définie dans Amazon API Gateway
• 'resource': spécifiez 'message'
• 'event': Cette fois, nous allons créer un webhook, alors spécifiez 'créé'
• 'filter': 'roomId =' suivi du roomId auquel appartient le bot

roomId peut être étudié depuis ici.

import requests

access_code = ''                       #Entrez le code d'accès ici

url = 'https://api.ciscospark.com/v1/webhooks'
headers = {
    'Authorization' : 'Bearer ' + access_code,
    'Content-Type' : 'application/json'
}

r = requests.put(url, headers = headers)

{
  'name' : 'My Awesome Webhook',
  'targetUrl' : 'https://example.com/mywebhook',
  'resource' : 'messages',
  'event' : 'created',
  'filter' : 'roomId=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
}

4-2. Contrôle de fonctionnement

Mentionnez le Bot dans Cisco Spark et tapez "ping" et le Bot retournera "pong".

(Supplément) Pour générer le journal API Gateway

1. Ouvrez le service API Gateway dans la console AWS.
2. Cliquez sur Nom d'API (API4CiscoSpark)> Étape> prod pour afficher l'onglet Paramètres.
3. Cochez «Activer les journaux CloudWatch». Définissez le "niveau de journalisation".
4. "Enregistrer les modifications"

5. Vous pouvez vérifier le journal sur CloudWatch