Qu'est-ce que c'est et quelles sont ses fonctionnalités ?
La Personal Photos API fournit à votre application un accès en temps réel aux albums photos des clients d'Orange France, vous permettant ainsi de visualiser leurs photos et d'en ajouter de nouvelles avec leur permission.
L'API offre un accès sécurisé et contrôlé aux albums photos de l'utilisateur.
Le diagramme ci-dessous illustre comment cette API peut être intégrée à un site Web :
En un mot, la Personal Photos API vous permet :
de rechercher et d'extraire les informations relatives aux albums et photos contenues dans le compte photos Orange de l'utilisateur ainsi que des liens images vers les photos contenues dans les albums.
d'importer les photos dans l'actuel ou le nouvel album photos Orange.
(haut de page)
avant de démarrer
Pour commencer à tester cette API, assurez-vous d'avoir lu et compris la section sur les Personal APIs (alpha)
Vous remarquerez qu'il est nécessaire de suivre les étapes suivantes :
étape 1 - devenir membre d'Orange Partner
étape 2 - accéder à l'administrator web interface
Ensuite, une fois dans l'administrator web interface, vous pourrez vous inscrire à la Personal Photos API.
Une fois votre inscription validée, vous recevrez un e-mail et un fichier ZIP contenant les éléments suivants :
Votre clé d'accès (SERVICE_ID et SERVICE PWD).
L'URL de l'API (PersonalPhotosV1URL).
Les exemples de codes
Les instructions d'utilisation relatives à tous ces éléments.
en savoir plus sur l'administrator web interface
(haut de page)
comment authentifier l'utilisateur
Premièrement, les utilisateurs doivent être authentifiés avant que l'accès à leurs photos ne soit accordé.
L'authentification est effectuée via l'Authentication API qui renverra un jeton d'utilisateur (user token).
Vous inclurez ensuite ce jeton dans tous les appels de la Personal Photos API.
Ci-dessous, un exemple sur la manière dont l'appel est effectué :
|
Format:
[PersonalPhotosV1URL]?action=[action name]&token=[user token]¶m=[value]...
Example:
[PersonalPhotosV1URL]?action=CreateAlbum&token=Hjlkzjlfkzef23423kjlkjr¶m=value...
|
Si vous souhaitez savoir si votre code a fonctionné, nous pouvons vous fournir un compte de test pour que vous puissiez consulter les résultats comme si vous étiez un client Orange. Une fois votre inscription validée, nous vous montrerons comment en obtenir un.
(haut de page)
ajouter un album photos « Hello World »
Ajouter un album photos « Hello World » au compte photos Orange d'un utilisateur est facile.
Premièrement, recherchez et extrayez un jeton d'utilisateur en utilisant l'Authentication API. Ce jeton d'utilisateur (user token) sera utilisé comme paramètre du « jeton » dans l'appel de la Personal Photos API.
Pour plus d'informations, consultez la section comment authentifier l'utilisateur.
Vous pourrez ensuite appeler la requête suivante (en ajoutant un album « Hello World ») :
|
[PersonalPhotosV1EndPoint]?action=CreateAlbum&title=Hello%20World&token=Hjlkzjlfkzef23423kjlkjr |
Le code ci-dessus créera un nouvel album dénommé « Hello World » dans le compte photos Orange de l'utilisateur. Facile.
(haut de page)
les méthodes de la Personal Photos API en détail
La Personal Photos API offre les méthodes suivantes :
GetAlbumList - obtenir les albums de l'utilisateur donné CreateAlbum - créer un album GetAlbum - rechercher et extraire l'un des albums de l'utilisateur GetMediaObjsList - obtenir la liste de photos d'un album GetMediaObj - obtenir des informations sur une photo AddMediaObj - ajouter une photo
GetAlbumList - obtenir les albums de l'utilisateur donné
Cette action recherche et extrait la liste d'albums de l'utilisateur donné. Elle renvoie un résumé des albums.
Pour appeler l'API, créez l'URL selon le format suivant dans votre application Web et invoquez-le via HTTP GET :
|
Format:
[PersonalPhotosV1URL]?action=GetAlbumsList&token=[user token]
Example:
[PersonalPhotosV1URL]?action=GetAlbumsList&token=Hjlkzjlfkzef23423kjlkjr |
paramètres d'entrée
| Nom |
Description |
Obligatoire |
Type |
| token |
jeton récupéré grâce à l'Authentication API |
Oui |
string |
exemple de réponse
|
<?xml version="1.0" encoding="UTF-8"?>
<action version="2.0" code="3201">
<albums count="3">
<album cypheredId="4f7mr0vqj3wk5">
<title><![CDATA[album 8/2/2006-01]]></title>
<guests count="2"/>
<mediaObjects count="4"/>
</album>
<album cypheredId="2g7x1pi3kuyva">
<title><![CDATA[album 21/3/2006-01]]></title>
<guests count="3"/>
<mediaObjects count="3"/>
</album>
<album cypheredId="1hvdkd3k0womr">
<title><![CDATA[title]]></title>
<guests count="1"/>
<mediaObjects count="12"/>
</album>
</albums>
</action> |
description du code de l'album :
| Nom |
Description |
Type |
Exemple |
| album |
code utilisé pour décrire un album |
|
|
| title |
titre de l'album |
chaîne |
album 8/2/2006-01 |
| guests |
nombre d'invités sur cet album (non utilisé) |
integer |
2 |
| mediaObjects |
nombre d'objets médias dans l'album |
integer |
4 |
(retour aux méthodes de l'Personal Photos API)
Create Album - créez un album
Cette action crée un album. Si l'album existe déjà dans la base de données, il sera automatiquement renommé comme <title>< -n > (où n est un integer).
Pour appeler l'API, créez l'URL selon le format suivant dans votre application Web et invoquez-le via HTTP GET :
|
Format:
[PersonalPhotosV1URL]?action=CreateAlbum&TIT=[album title]&token=[user token]
Example:
[PersonalPhotosV1URL]?action=CreateAlbum&TIT=album%2010/12/2006-01&token=Hjlkzjlfkzef23423kjlkjr |
paramètres d'entrée
| Nom |
Description |
Obligatoire |
Type |
| TIT |
titre de l'album |
oui |
string |
| token |
jeton récupéré grâce à l'Authentication API |
oui |
string |
exemple de réponse
|
<?xml version="1.0" encoding="UTF-8"?>
<action version="2.0" code="100">
<album cypheredId="ny1qpf7uv545">
<title><![CDATA[album 10/12/2006-01]]></title>
<creationDate>1166212233028</creationDate>
</album>
</action> |
description du code de l'album :
| Nom |
Description |
Type |
Exemple |
| album |
code utilisé pour décrire un album |
|
|
| title |
titre de l'album |
chaîne |
album 10/12/2006-01 |
| creationDate |
date de création de l'album (date UTC) |
integer long |
1166212233028 |
(retour aux méthodes de l'Personal Photos API)
GetAlbum - rechercher et extraire l'un des albums de l'utilisateur
Cette action permet à l'utilisateur de rechercher et d'extraire l'un de ses albums en utilisant son identifiant chiffré.
Pour appeler l'API, créez l'URL selon le format suivant dans votre application Web et invoquez-le via HTTP GET :
|
Format:
[PersonalPhotosV1URL]?actionGetAlbum&Album=[Cypheredld]&token=[user token]
Example:
[PersonalPhotosV1URL]?actionGetAlbum&Album=ny1qpf7uv545&token=Hjlkzjlfkzef23423kjlkjr |
paramètres d'entrée
| Nom |
Description |
Obligatoire |
Type |
| album |
identifiant chiffré de l'album à récupérer |
oui |
string |
| token |
jeton récupéré grâce à l'Authentication API |
oui |
string |
exemple de réponse
|
<?xml version="1.0" encoding="UTF-8"?>
<action version="2.0" code="105">
<album cypheredId="ny1qpf7uv545">
<title><![CDATA[album 10/12/2006-01]]></title>
<creationDate>1166212233028</creationDate>
</album>
</action> |
description du code de l'album :
| Nom |
Description |
Type |
Exemple |
| album |
code utilisé pour décrire un album |
|
|
| title |
titre de l'album |
string |
album 10/12/2006-01 |
| creationDate |
date de création de l'album (date UTC) |
integer long |
1166212233028 |
(retour aux méthodes de l'Personal Photos API)
GetMediaObjsList - obtenir la liste de photos d'un album
Cette action recherche et extrait les photos de l'album dont l'identifiant chiffré est passé en paramètre.
Pour appeler l'API, créez l'URL selon le format suivant dans votre application Web et invoquez-le via HTTP GET :
|
Format:
[PersonalPhotosV1URL]?actionGetMediaObjsList&Album=[CypheredId]&token=[user token]
Example:
[PersonalPhotosV1URL]?actionGetMediaObjsList&Album=ny1qpf7uv545
&token=Hjlkzjlfkzef23423kjlkjr |
paramètres d'entrée
| Nom |
Description |
Obligatoire |
Type |
| album |
identifiant chiffré de l'album à récupérer |
oui |
string |
| token |
jeton récupéré grâce à l'Authentication API |
oui |
string |
exemple de réponse
|
<?xml version="1.0" encoding="UTF-8"?>
<action version="2.0" code="3204">
<mediaObjects>
<mediaObject id="5922" cypheredId="c0f8aae730f9552e">
<title><![CDATA[2005-Porsche-911]]></title>
<creationDate>1145433318470</creationDate>
<filename>porsche_911.jpeg</filename>
<filesize>212117</filesize>
<mimeType>image/jpeg</mimeType>
<width>1920</width>
<height>1440</height>
<baseUrl>
http://ephoto.orange.fr/sitdriver?cid=c0f8aae730f9552e&app=ephoto.orange.fr
</baseUrl>
</mediaObject>
<mediaObject id="5923" cypheredId="a8ef26337d8b6c6d">
<title><![CDATA[2005-TechArt]]></title>
<creationDate>1145433328663</creationDate>
<filename>techart.jpeg</filename>
<filesize>162393</filesize>
<mimeType>image/jpeg</mimeType>
<width>1024</width>
<height>768</height>
<baseUrl>
http://ephoto.orange.fr/sitdriver?cid=a8ef26337d8b6c6d&app=ephoto.orange.fr
</baseUrl>
</mediaObject>
</mediaObjects>
</action> |
description du code de l'Objetmédia :
| Nom |
Description |
Type |
Exemple |
| title |
titre de l'Objetmédia |
string |
2005-Porsche-911 |
| creationDate |
date de création de l'objet média (date UTC) |
integer long |
1145433328663 |
| filename |
nom du fichier dans le serveur de fichiers |
string |
porsche_911.jpg |
| filesize |
taille du fichier dans le serveur de fichiers, en octets |
integer long |
212117 |
| mimeType |
type Mime de l'objet |
string |
image/jpeg |
| width |
largeur de l'image en pixels |
integer |
1920 |
| height |
hauteur de l'image en pixels |
integer |
1440 |
| baseURL |
URL pour rechercher et extraire la photo |
string |
|
(retour aux méthodes de l'Personal Photos API)
GetMediaObj - obtenir des informations sur une photo
Cette méthode recherche et extrait des informations sur une photo en passant l'identifiant de la photo dans l'URL. L'identifiant de la photo peut être recherché et extrait en utilisant la méthode GetMediaObjsList.
Pour appeler l'API, créez l'URL selon le format suivant dans votre application Web et invoquez-le via HTTP GET :
|
Format:
[PersonalPhotosV1URL]?action=GetMediaObj&MOB=[MediaObjId]&token=[user token]
Example:
[PersonalPhotosV1URL]?action=GetMediaObj&MOB=5922&token=Hjlkzjlfkzef23423kjlkjr |
paramètres d'entrée
| Nom |
Description |
Obligatoire |
Type |
| MOB |
identifiant de l'objet média |
oui |
integer |
| token |
jeton récupéré grâce à l'Authentication API |
oui |
string |
exemple de réponse
|
<?xml version="1.0" encoding="UTF-8"?>
<action version="2.0" code="3205">
<mediaObject id="5922" cypheredId="c0f8aae730f9552e">
<title><![CDATA[2005-Porsche-911]]></title>
<creationDate>1145433318470</creationDate>
<filename>porsche_911.jpeg</filename>
<filesize>212117</filesize>
<mimeType>image/jpeg</mimeType>
<width>1920</width>
<height>1440</height>
<baseUrl>
http://ephoto.orange.fr/sitdriver?cid=c0f8aae730f9552e&app=papi
</baseUrl>
</mediaObject>
</action> |
description du code de l'Objetmédia :
| Nom |
Description |
Type |
Exemple |
| title |
titre de l'Objetmédia |
string |
2005-Porsche-911 |
| creationDate |
date de création de l'Objetmédia (date UTC) |
integer long |
1145433328663 |
| filename |
nom du fichier dans le serveur de fichiers |
string |
porsche_911.jpg |
| filesize |
taille du fichier dans le serveur de fichiers en octets |
integer long |
212117 |
| mimeType |
type Mime de l'objet |
string |
image/jpeg |
| width |
largeur de l'image en pixels |
integer |
1920 |
| height |
hauteur de l'image en pixels |
integer |
1440 |
| baseURL |
URL de la photo |
string |
|
accès aux photos
Les méthodes GetMediaObj et GetMediaObjsList renvoient l'Url de base de la photo. C'est url peut être invoquée directement depuis votre site ou téléchargée.
Par ailleurs, vous pouvez demander que des modifications (ex. redimensionnement) soient apportées à la photo. Dans ce cas, des paramètres additionnels doivent être ajoutés à l'URL de base :
largeur : largeur maximale en pixels
hauteur : hauteur maximale en pixels
Pour obtenir un meilleur temps de réponse, nous vous encourageons vivement à utiliser des vignettes de 100 x 100 et de 500 x 500 pixels paramétrées à l'avance.
(retour aux méthodes de l'Personal Photos API)
AddMediaObj - ajouter une photo
Cette action ajoute une photo à l'album dont l'identifiant chiffré est est passé en paramètre. Cette requête contient le fichier image à transférer sur le serveur de photos.
Les formats suivants sont acceptés :
image: JPEG, GIF, BMP, PNG
Pour appeler l'API, créez l'URL selon le format suivant dans votre application Web et invoquez-le via HTTP POST :
|
Exemple:
Content-Type: multipart/form-data;
boundary=---------------------------41184676334
Content-Length: 29277
-----------------------------41184676334
Content-Disposition: form-data; name="action"
AddMediaObj
-----------------------------41184676334
Content-Disposition: form-data; name="Album"
582ba38athhqv
-----------------------------41184676334
Content-Disposition: form-data; name="F_title"
title
-----------------------------41184676334
Content-Disposition: form-data; name="token"
Hjlkzjlfkzef23423kjlkjr
-----------------------------41184676334
Content-Disposition: form-data; name="F"; filename="picture.jpg"
Content-Type: image/jpeg |
paramètres d'entrée
| Nom |
Description |
Obligatoire |
Type |
| Album |
identifiant chiffré de l'album
si aucun album n'est spécifié, l'album boîte de réception sera utilisé |
non |
string |
| F |
fichier à transférer |
oui |
string |
| F_title |
titre du fichier à transférer |
oui |
string |
| token |
jeton récupéré grâce à l'Authentication API |
oui |
string |
exemple de réponse
|
<?xml version="1.0" encoding="UTF-8"?>
<action version="2.0" code="3201">
<albums count="3">
<album cypheredId="4f7mr0vqj3wk5">
<title><![CDATA[album 8/2/2006-01]]></title>
<guests count="2"/>
<mediaObjects count="4"/>
</album>
<album cypheredId="2g7x1pi3kuyva">
<title><![CDATA[album 21/3/2006-01]]></title>
<guests count="3"/>
<mediaObjects count="3"/>
</album>
<album cypheredId="1hvdkd3k0womr">
<title><![CDATA[title]]></title>
<guests count="1"/>
<mediaObjects count="12"/>
</album>
</albums>
</action> |
(retour aux méthodes de l'Personal Photos API)
(haut de page)
codes d'erreur de la Personal Photos API
Lorsqu'une erreur se produit, la réponse contient les paramètres suivants :
|
<?xml version="1.0" encoding="UTF-8"?>
<action version="2.0" code="200">
<error-code>1106</error-code>
<error-msg>
Owner unknown [GUID = mail jsmith@orange.fr]
</error-msg>
</action> |
Ci-dessous, un tableau des erreurs les plus significatives :
| Code |
Statut |
Description |
| 200 |
OK |
La requête HTTP a abouti.
Pour une requête GET : l'entité correspondant à la ressource demandée est envoyée dans la réponse.
Pour une requête POST : une entité contenant le résultat de l'action est envoyé dans la réponse. |
| 400 |
Mauvaise requête |
La requête HTTP n'a pas pu être comprise par le serveur à cause d'une mauvaise syntaxe. |
| 404 |
Introuvable |
Le serveur n'a rien trouvé qui correspond à l'adresse demandée (URL). |
| 500 |
Erreur serveur interne |
Le serveur a rencontré une condition inattendue qui l'a empêché d'accomplir la requête. |
(haut de page)
