avant de commencer
Avant de commencer, merci de lire les informations ci-dessous et de suivre toutes les instructions.
Vous pourrez ensuite passer à la section « pour commencer ».
deux choses à faire avant de commencer
sur l'API Manager
deux choses à faire avant de commencer
Pour commencer à tester cette API, assurez-vous d'avoir bien lu et compris la section sur les
Personal APIs (alpha) section
Ensuite, une fois dans l'API Manager, vous pourrez vous inscrire à la Personal Photos API.
|
sur l'API Manager
L'API Manager vous permet de contrôler et de configurer tous les aspects de vos inscriptions aux Personal APIs alpha.
Vous pourrez notamment :
obtenir l'autorisation d'utiliser les API
solliciter votre inscription aux APIs de votre choix
obtenir l'acceptation de votre inscription
puis recevoir votre clé d'accès, vos points de terminaison HTTP, vos exemples de code et la documentation technique
|
|
Les étapes ci-dessous décrivent des aspects importants de l'interface
La première fois que vous vous connecterez à l'API Manager, nous vous demanderons de remplir un formulaire pour nous fournir des informations incluant :
l'URL de votre site Web
le nom de votre site Web
le logo de votre site Web
Ces informations nous aideront à valider votre inscription.
Les informations que vous nous fournirez sur le site Web seront communiquées aux utilisateurs pour leur permettre de définir leurs paramètres en matière de respect de la vie privée et de déterminer s'ils vous autoriseront, vous, le développeur, à accéder à leurs informations personnelles via les Personal APIs.
Vous aurez ensuite accès à un écran vous permettant de solliciter une inscription à n'importe laquelle des API.
Souvenez-vous que vous DEVEZ d'abord 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
Les exemples de codes.
Les instructions d'utilisation relatives à tous ces éléments.
accédez à l' API Manager
pour commencer
Maintenant que vous avez lu la section « avant de commencer » et que l'API Manager vous est plus familière, vous êtes prêt à en savoir plus sur…
comment authentifier l'utilisateur
ajouter un album photos « Hello World »
les méthodes de la Personal Photos API en détail
les codes d'erreur de la Personal Photos API
comment authentifier l'utilisateur
Premièrement, les utilisateurs doivent être authentifiés avant que l'accès à leurs messages 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 de 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.
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.
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 - get the albums of the given user
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 |
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 |
Example |
| album |
code utilisé pour décrire un album |
|
|
| title |
titre de l'album |
string |
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 la 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 |
string |
album 10/12/2006-01 |
| creationDate |
date de création de l'album (date UTC)
|
integer long |
1166212233028 |
(retour aux méthodes de la 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 |
cyphered id of the album to be recovered |
oui |
string |
| token |
user token that is retrieved using the 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 |
Example |
| 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 la 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 la 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 chiffré 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=[MediaObjCypheredId]&
token=[user token]
Example:
[PersonalPhotosV1URL]?action=GetMediaObj&MOB=c0f8aae730f9552e&
token=Hjlkzjlfkzef23423kjlkjr |
paramètres d'entrée
| Name |
Description |
Mandatory |
Type |
| MOB |
media object's cyphered identifier |
yes |
integer |
| token |
user token that is retrieved using the Authentication API |
yes |
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 :
| Name |
Description |
Type |
Example |
| title |
title of the mediaObject |
string |
2005-Porsche-911 |
| creationDate |
creation date of the media object (UTC date) |
integer long |
1145433328663 |
| filename |
name of the file in the filer |
string |
porsche_911.jpg |
| filesize |
size of the file in the filer, in bytes |
integer long |
212117 |
| mimeType |
mime type of object |
string |
image/jpeg |
| width |
width of the image in pixels |
integer |
1920 |
| height |
height of the image in pixels |
integer |
1440 |
| baseURL |
URL to retrieve the photo |
string |
|
accès aux photos
Les méthodes GetMediaObj et GetMediaObjsList renvoient l'Url de base de la photo. Cette 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 la Personal Photos API)
AddMediaObj - ajouter une photo
Cette action ajoute une photo à l'album dont l'identifiant chiffré 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 |
Mandatory |
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 la Personal Photos API)
les 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)
