Download Slides - liminal

BlueVia
LIMINAL
Si usted quiere desarrollar con Bluevia y Java,
esto es lo primero que debe saber
Mario Linares Vásquez
mario.linares@liminal-it.con
Junio 30 de 2011
BlueVia
Network as a Service - NaaS
Llamadas.
Mensajes.
Ubicación de los equipos.
Perfil de los usuarios y los equipos.
Facturación.
NaaS: información y servicios de la red
(network intelligence)
son ofrecidos a los usuarios y a terceros.
Network as a Service - NaaS
Que información poseen los operadores de móviles ?
BlueVia
Telco 2.0 business model
Application Service Providers
APIs
Telco
Network as a Service - NaaS
Usuarios
BlueVia
Modelo de desarrollo
REST
OAUTH
SDK para Java
AGENDA
Documentación
MODELO
de desarrollo
BlueVia
en
s
o
i
c
i
v
r
se
n
e
m
u
s
.
con
s
e
a
u
n
q
o
s
s
r
e
pe
ion
e
c
d
a
c
n
i
l
ó
i
p
c
a
a
e
m
d
r
o
o
f
l
l
n
i
o
r
r
e
ad
esa
d
d
e
l
u
e
q
a
s
r
ú
a
p
ob
o
t
a
í
p
r
e
e
c
j
n
a
s
o
n
e
oc
v
m
e
o
u
n
m
o
n
U
,c
a
c
i
n
ó
f
e
l
te
e
d
d
e
r
la
APIs y SDKs
webservices
REST
autorización
OAUTH
Diferentes lenguajes de programación.
BlueVia
OAUTH
• El acceso a los recursos de la
red es autorizado por los
usuarios mediante OAUTH.
Con OAUTH, los datos identidad (login, password)
de los usuarios permanecen privados y no son
compartidos con las aplicaciones BlueVia.
App
SDK
BlueVia
Internet
MMS
Send API
MMS
Receive API
SMS
Receive API
SMS
Send API
Location
API
User
Context
API
Advertising
API
App
SDK
BlueVia
MMS
Send API
MMS
Receive API
SMS
Receive API
SMS
Send API
Location
API
User
Context
API
Advertising
API
REST
Internet
BlueVia
App
BlueVia
MMS
Send API
MMS
Receive API
SMS
Receive API
SMS
Send API
Internet
Location
API
User
Context
API
Advertising
API
BlueVia
SMS Send API
SMS Receive API
MMS Receive API
MMS Send API
Advertising API
User Context API
Location API
BlueVia
Desarrolladores
El modelo de desarrollo, incluye
1. Registro en Bluevia: https://bluevia.com/en/user/register.
2. Obtener API Keys
BlueVia
Desarrolladores
Un API key es requerida por cada aplicación, con el fin de usar las APIS Bluevia.
De acuerdo con el tipo de Key (Test o Comercial) las APIs se pueden utilizar en modo
SANDBOX:
Ambiente para pruebas que no
genera tráfico en la red.
LIVE:
ambiente que usa la red
de telefónica de forma real.
BlueVia
Desarrolladores Bluevia
BlueVia
Desarrolladores Bluevia
BlueVia
Escenarios de desarrollo
Test API Key
Commercial API Key
Sandbox
Fase inicial de desarrollo
Pruebas de la aplicación
Simulación de error
No genera tráfico
Pruebas antes de iniciar el proceso de
acreditación de la aplicación o antes de
subir a una App Store.
Live
Pruebas con desarrolladores registrados
y que tengan crédito
para uso de las APIS.
Transacciones sobre la red de acuerdo
con el modelo comercial seleccionado.
REST
•
representational state transfer.
BlueVia
Métodos protocolo HTTP
Método (Verbo)
Uso
OPTIONS
Retorna los métodos soportados por el servidor
GET
Solicita una representación de un recurso
HEAD
Igual que GET pero sin cuerpo
POST
Envía datos para ser procesados
PUT
Envía una representación de un recurso
DELETE
Elimina el recurso
TRACE
Solicita retorno del mensaje enviado
CONNECT
Convierte el request a un tunel TCP/IP
BlueVia
Códigos de estado HTTP
Código
Descripción
1xx
Información
2xx
Éxito
3xx
Redirección
4xx
Error del cliente
5xx
Error del servidor
BlueVia
Mensaje HTTP - Request
POST /services/REST/SMS/outbound/requests?version=v1 HTTP/1.1
Authorization: OAuth
realm="https://api.bluevia.com",
oauth_consumer_key="Gjqq11099SE",
oauth_token="4bf499a1ecaac050dfaddfef87f99e3a",
oauth_signature_method="HMAC-SHA1",
oauth_signature="8I4319SRY0zLjv15RwqpuF7%2BOso%3D",
oauth_timestamp="1291898799",
oauth_nonce="15339077371968105486410263075"
Content-Type: application/xml
Host: api.bluevia.com:443
<?xml version="1.0" encoding="UTF-8"?>
<tns:smsText >
<tns:address>
<tns1:phoneNumber>524794786537</tns1:phoneNumber>
</tns:address>
<tns:message>This is a text message</tns:message>
<tns:originAddress>
<tns1:alias>4bf499a1ecaac050dfaddfef87f99e3a</tns1:alias>
</tns:originAddress>
</tns:smsText>
BlueVia
Mensaje HTTP - Request
Métod
o
HTTP
POST /services/REST/SMS/outbound/requests?version=v1 HTTP/1.1
Authorization: OAuth
realm="https://api.bluevia.com",
oauth_consumer_key="Gjqq11099SE",
oauth_token="4bf499a1ecaac050dfaddfef87f99e3a",
oauth_signature_method="HMAC-SHA1",
oauth_signature="8I4319SRY0zLjv15RwqpuF7%2BOso%3D",
oauth_timestamp="1291898799",
oauth_nonce="15339077371968105486410263075"
Content-Type: application/xml
Host: api.bluevia.com:443
<?xml version="1.0" encoding="UTF-8"?>
<tns:smsText >
<tns:address>
<tns1:phoneNumber>524794786537</tns1:phoneNumber>
</tns:address>
<tns:message>This is a text message</tns:message>
<tns:originAddress>
<tns1:alias>4bf499a1ecaac050dfaddfef87f99e3a</tns1:alias>
</tns:originAddress>
</tns:smsText>
BlueVia
Mensaje HTTP - Request
Request
URI
POST /services/REST/SMS/outbound/requests?version=v1 HTTP/1.1
Authorization: OAuth
realm="https://api.bluevia.com",
oauth_consumer_key="Gjqq11099SE",
oauth_token="4bf499a1ecaac050dfaddfef87f99e3a",
oauth_signature_method="HMAC-SHA1",
oauth_signature="8I4319SRY0zLjv15RwqpuF7%2BOso%3D",
oauth_timestamp="1291898799",
oauth_nonce="15339077371968105486410263075"
Content-Type: application/xml
Host: api.bluevia.com:443
<?xml version="1.0" encoding="UTF-8"?>
<tns:smsText >
<tns:address>
<tns1:phoneNumber>524794786537</tns1:phoneNumber>
</tns:address>
<tns:message>This is a text message</tns:message>
<tns:originAddress>
<tns1:alias>4bf499a1ecaac050dfaddfef87f99e3a</tns1:alias>
</tns:originAddress>
</tns:smsText>
BlueVia
Mensaje HTTP - Request
Versión
HTTP
POST /services/REST/SMS/outbound/requests?version=v1 HTTP/1.1
Authorization: OAuth
realm="https://api.bluevia.com",
oauth_consumer_key="Gjqq11099SE",
oauth_token="4bf499a1ecaac050dfaddfef87f99e3a",
oauth_signature_method="HMAC-SHA1",
oauth_signature="8I4319SRY0zLjv15RwqpuF7%2BOso%3D",
oauth_timestamp="1291898799",
oauth_nonce="15339077371968105486410263075"
Content-Type: application/xml
Host: api.bluevia.com:443
<?xml version="1.0" encoding="UTF-8"?>
<tns:smsText >
<tns:address>
<tns1:phoneNumber>524794786537</tns1:phoneNumber>
</tns:address>
<tns:message>This is a text message</tns:message>
<tns:originAddress>
<tns1:alias>4bf499a1ecaac050dfaddfef87f99e3a</tns1:alias>
</tns:originAddress>
</tns:smsText>
BlueVia
Mensaje HTTP - Request
Heade
rs
POST /services/REST/SMS/outbound/requests?version=v1 HTTP/1.1
Authorization: OAuth
realm="https://api.bluevia.com",
oauth_consumer_key="Gjqq11099SE",
oauth_token="4bf499a1ecaac050dfaddfef87f99e3a",
oauth_signature_method="HMAC-SHA1",
oauth_signature="8I4319SRY0zLjv15RwqpuF7%2BOso%3D",
oauth_timestamp="1291898799",
oauth_nonce="15339077371968105486410263075"
Content-Type: application/xml
Host: api.bluevia.com:443
<?xml version="1.0" encoding="UTF-8"?>
<tns:smsText >
<tns:address>
<tns1:phoneNumber>524794786537</tns1:phoneNumber>
</tns:address>
<tns:message>This is a text message</tns:message>
<tns:originAddress>
<tns1:alias>4bf499a1ecaac050dfaddfef87f99e3a</tns1:alias>
</tns:originAddress>
</tns:smsText>
BlueVia
Mensaje HTTP - Request
POST /services/REST/SMS/outbound/requests?version=v1 HTTP/1.1
Authorization: OAuth
realm="https://api.bluevia.com",
oauth_consumer_key="Gjqq11099SE",
oauth_token="4bf499a1ecaac050dfaddfef87f99e3a",
oauth_signature_method="HMAC-SHA1",
oauth_signature="8I4319SRY0zLjv15RwqpuF7%2BOso%3D",
oauth_timestamp="1291898799",
oauth_nonce="15339077371968105486410263075"
Content-Type: application/xml
Host: api.bluevia.com:443
Cuerpo
mensadjel
e
<?xml version="1.0" encoding="UTF-8"?>
<tns:smsText >
<tns:address>
<tns1:phoneNumber>524794786537</tns1:phoneNumber>
</tns:address>
<tns:message>This is a text message</tns:message>
<tns:originAddress>
<tns1:alias>4bf499a1ecaac050dfaddfef87f99e3a</tns1:alias>
</tns:originAddress>
</tns:smsText>
BlueVia
Mensaje HTTP – Request/Response
POST /services/REST/SMS/outbound/requests?version=v1 HTTP/1.1
Authorization: OAuth
realm="https://api.bluevia.com",
oauth_consumer_key="Gjqq11099SE",
oauth_token="4bf499a1ecaac050dfaddfef87f99e3a",
oauth_signature_method="HMAC-SHA1",
oauth_signature="8I4319SRY0zLjv15RwqpuF7%2BOso%3D",
oauth_timestamp="1291898799",
oauth_nonce="15339077371968105486410263075"
Content-Type: application/xml
Host: api.bluevia.com:443
Internet
<?xml version="1.0" encoding="UTF-8"?>
<tns:smsText >
<tns:address>
<tns1:phoneNumber>524794786537</tns1:phoneNumber>
</tns:address>
<tns:message>This is a text message</tns:message>
<tns:originAddress>
<tns1:alias>4bf499a1ecaac050dfaddfef87f99e3a</tns1:alias>
</tns:originAddress>
</tns:smsText>
SMS
Send API
HTTP/1.1 201 Created
Location: https://api.bluevia.com/services/REST/SMS/outbound/requests/
10001022134544108250/deliverystatus
Content-Length: 0
BlueVia
REST
Representational State Transfer.
Estilo arquitectónico para aplicaciones distribuidas.
El uso de un conjunto limitado de operaciones, con una
semántica uniforme, es suficiente para construir cualquier
tipo de aplicación.
BlueVia
REST
Representational State Transfer.
• Los estados de un proceso pueden ser modelados como recursos.
• Información semántica sobre los pasos del proceso de negocio
están embebidos en las URIs.
BlueVia
CRUD Web services
Bajo el estilo REST, las operaciones CRUD son suficientes
para construir cualquier tipo de aplicación.
Método HTTP
URI
Uso
GET
/message
Consultar estado
POST
/message/{id}
Crear/enviar
PUT
/message/{id}
Actualizar
DELETE
/message/{id}
Eliminar
BlueVia
CRUD Web services - POST
Servidor
Cliente
POST /services/message HTTP/1.1
….
Host: test.com
http://test.com/services/message
El mensaje
201 Created
Location http://test.com/services/message/12345
400 Bad request
500 Internal error
Exito
Error
BlueVia
URLs para APIs de Bluevia
h"ps://api.bluevia.com/services/REST/SMS/outbound/requests/
10001022145853108719/deliverystatus?version=v1&alt=json
• URI de acceso a Bluevia
BlueVia
URLs para APIs de Bluevia
hDps://api.bluevia.com/services/REST/SMS/outbound/requests/
10001022145853108719/deliverystatus?version=v1&alt=json
• URI de acceso a Bluevia.
• Identificador del API.
BlueVia
URLs para APIs de Bluevia
hDps://api.bluevia.com/services/REST/SMS/outbound/
requests/10001022145853108719/deliverystatus?
version=v1&alt=json
• URI de acceso a Bluevia.
• Identificador del API.
• Operación.
BlueVia
URLs
URLs para
para APIs
APIs de
de Bluevia
Bluevia
hDps://api.bluevia.com/services/REST/SMS/outbound/requests/
10001022145853108719/deliverystatus?version=v1&alt=json
•
•
•
•
URI de acceso a Bluevia.
Identificador del API.
Operación.
Identificador del recurso.
BlueVia
URLs para APIs de Bluevia
hDps://api.bluevia.com/services/REST/SMS/outbound/
requests/10001022145853108719/deliverystatus?
version=v1&alt=json
•
•
•
•
•
URI de acceso a Bluevia.
Identificador del API.
Operación.
Identificador del recurso.
Parámetros.
Mas info en
https://bluevia.com/en/knowledge/APIs.API-Guides
https://bluevia.com/en/knowledge/APIs.API-Reference
BlueVia
URLs para APIs de Bluevia
hDps://api.bluevia.com/services/REST/SMS/outbound/requests/
10001022145853108719/deliverystatus?version=v1&alt=json
•
•
•
•
•
URI de acceso a Bluevia.
Identificador del API.
Operación.
Identificador del recurso.
Parámetros.
Mas info en
https://bluevia.com/en/knowledge/APIs.API-Guides
https://bluevia.com/en/knowledge/APIs.API-Reference
BlueVia
APIs - Formatos de Mensaje
Los mensajes en métodos POST y PUT pueden enviarse utilizando XML, JSON o URL encoded:
POST /services/REST/SMS/outbound/requests?version=v1 HTTP/1.1
Content-Type: application/xml
Host: api.bluevia.com:443
<?xml version="1.0" encoding="UTF-8"?>
<tns:smsText xmlns:tns="http://www.telefonica.com/schemas/UNICA/REST/sms/v1/"
xmlns:tns1=http://www.telefonica.com/schemas/UNICA/REST/common/v1
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.telefonica.com/schemas/UNICA/REST/sms/v1/
UNICA_API_REST_sms_types_v1_0.xsd ">
<tns:address>
<tns1:phoneNumber>52200009</tns1:phoneNumber>
</tns:address>
<tns:message>This is a text message</tns:message>
<tns:originAddress>
<tns1:alias>30c8db243ad31380e90f3fd650af9351</tns1:alias>
</tns:originAddress>
</tns:smsText>
XML
BlueVia
APIs - Formatos de Mensaje
JSON
POST /services/REST/SMS/outbound/requests?version=v1 HTTP/1.1
Content-­‐Type: applicaQon/json
Host: api.bluevia.com:443
{"smsText": {
"address": {"phoneNumber": "52200009"},
"message": "This is a text message",
"originAddress": {"alias": "30c8db243ad31380e90f3fd650af9351"},
}}
POST /services/REST/SMS/outbound/requests?version=v1 HTTP/1.1
Content-­‐Type: applicaQon/x-­‐www-­‐form-­‐urlencoded
Host: api.bluevia.com:443
address.phoneNumber=52200009&message=This+is+a+text
+message&originAddress.alias=30c8db243ad31380e90f3fd650af9351
URL
BlueVia
APIs – Códigos de respuesta y error
Código
Descripción
200 OK
Éxito. Respuesta _pica para GET y DELETE
201 Created
Recurso creado exitosamente (POST, PUT)
202 Accepted
Solicitud aceptada para procesamiento.
204 No Content
Éxito, pero la respuesta no requiere contenido.
Código error
Descripción
400
Mensaje request con formato inválido
401
AutenQcación requerida
403
El servicio no puede cumplir con la solicitud, violación de acuerdos de nivel de servicio.
404
El servicio no puede cumplir con la solicitud, violación de acuerdos de nivel de servicio.
OAUTH
BlueVia
OAUTH
OAUTH permite compartir recursos privados
(fotos, listas de contactos, números de cuentas,
etc) alojados en sitios, de tal forma que otras
aplicaciones los puedan utilizar sin almacenar
o solicitar las credenciales privadas.
Ejemplo: una aplicación para mensajería SMS/MMS por internet requiere una autorización para poder realizar la facturación a nombre del propietario del número que envía el mensaje.
La aplicación no es del proveedor de mensajería
BlueVia
OAUTH - Definiciones
• Proveedor del servicio/Servidor: sitio o web services
donde se encuentran los recursos.
• Usuario : el propietario de los recursos.
• Consumidor/Cliente: la aplicación que quiere acceder
a los recursos.
• Token: mecanismo diferente a las credenciales del usuario,
que son usados para acceder a los recursos.
• Puede ser de tipo Request o Access.
BlueVia
OAUTH
1. Request token
Aplicación
Servidor
2. Solicita autorización
3. Se autentica y da autorización para el acceso
Propietario
BlueVia
OAUTH
4. Access token
5. Acceso a los recursos
BlueVia
OAUTH - Ejemplo
hDp://enviaunsms.com
EnviaUnSMS.com
Su número
Enviar a
Mensaje
Ok
Un usuario quiere enviar un SMS (con cargo a su cuenta)
a través de una aplicación web
BlueVia
OAUTH - Ejemplo
hDp://
EnviaUnSMS.com
Su número
Enviar a
Mensaje
Ok
La aplicación solicita “unathorized request token”
al proveedor del servicio
BlueVia
OAUTH - Ejemplo
hDp://
EnviaUnSMS.com
Su número
Enviar a
Mensaje
Ok
La aplicación redirecciona el flujo a la página del servicio de autorización hDp://autorizando.com
BlueVia
connect
Autorización
Userna
Passwor
hDp://autorizando.
BlueVia
OAUTH - Ejemplo
EnviaUnSMS.com
BlueVia
connect
Autorización
Username
Password
hDp://autorizando.com
El usuario da la autorización
EnviaUnSMS.com
BlueVia
connect
Autorización
Autoriza a enviaunsms.com para
Enviar SMSs ?
BlueVia
OAUTH - Ejemplo
hDp://
EnviaUnSMS.com
Su número
Enviar a
Mensaje
hDp://autorizando.com
La aplicación obQene “authorized request token”
EnviaUnSMS.com
BlueVia
connect
Autorización
Autoriza a enviaunsms.com para
Enviar SMSs ?
BlueVia
OAUTH - Ejemplo
hDp://
EnviaUnSMS.com
Su número
Enviar a
Mensaje
La aplicación solicita un “access token” con el “authorized request token”
BlueVia
OAUTH - Ejemplo
hDp://
EnviaUnSMS.com
Su número
Enviar a
Mensaje
Con el access token, la aplicación solicita al servidor
del proveedor de mensajería, el envío del mensaje
SDK
BlueVia
SDK para Java
BlueVia
SDK para Java
Paquete
Descripción
com.bluevia.examples
Ejemplos de invocación de las APIs
com.bluevia.java.directory
Clases para invocar API – user context
com.bluevia.java.gap
Clases para invocar API -advertisement
com.bluevia.java.location
Clases para invocar API - location
com.bluevia.java.mms
Clases para invocar API - MMS
com.bluevia.java.oauth
Clases para invocar API de autenticación
com.bluevia.java.sms
Clases para invocar API - SMS
com.telefonica.schemas.unica.rest.*
Clases generadas por Java XML binding (JAXB),
para los esquemas de los tipos.
BlueVia
SDK para Java - Funcionalidades
OAUTH
• Solicitar RequestToken y AccessToken.
ADVERTISEMENT
• Consultar un Ad • (un Ad se compone de un elemento creativo y una interacción).
BlueVia
SDK para Java – Ejemplo OAUTH
BlueVia
SDK para Java - Funcionalidades
SMS/MMS
• Envío de SMS/MMS a múlRples desRnos.
• Verificar estado del envío de SMS/MMS:
– La aplicación solicita el envío de noRficaciones sobre el estado.
– La aplicación explícitamente consulta el estado.
Posibles estados: DeliveredToNetwork, DeliveryUncertain, DeliveryImpossible, MessageWaiQng, DeliverdToTerminal, DeliveryNoQficaQonUnsupported.
• Recepción de SMS/MMS por demanda o a través de noRficaciones.
• Recepción de adjuntos en MMS.
BlueVia
SDK para Java – Ejemplo SMS
BlueVia
SDK para Java - Funcionalidades
DIRECTORY/USER CONTEXT
• Consultar información personal del usuario.
• Consultar perfil del usuario.
• Consultar información de la red.
• Consultar información del equipo.
LOCATION
• Consultar información de localización del equipo.
DOCUMENTACIÓN
BlueVia
Documentación
• Guía de inicio
https://bluevia.com/en/knowledge/getStarted
• Guía del desarrollador APIs
https://bluevia.com/en/knowledge/APIs.API-Guides
• Manual de referencia APIs
https://bluevia.com/en/knowledge/APIs.API-Reference
• Documentación propia de cada SDK
Mario Linares Vásquez
mario.linares@liminal-it.com
GRACIAS
LIMINAL-IT.com