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 à l'API Personal Content.
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 à l'API Personal Content.
Une fois votre inscription validée, nous vous enverrons un e-mail et un fichier ZIP contenant :
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 contenu « Hello World » (image HelloWorld.jpg)
les méthodes de l'API Personal Content en détail
les codes d'erreur de l'API Personal Content
comment authentifier l'utilisateur
Premièrement, les utilisateurs doivent être authentifiés avant que l'accès à leurs contenus soit accordé.
L'authentification est effectuée via l'Authentication API qui renverra un jeton d'utilisateur.
Vous inclurez ensuite le jeton dans tous les appels de l'API Personal Content.
L'ajout d'un contenu se fait en deux étapes (décrites ci-après) :
appel de l'API Personal Content pour récupérer l'URL d'upload sur le service "Mes Données"
upload du contenu, directement sur le service "Mes Données"
Ci-dessous, un exemple sur la manière dont le premier appel est effectué:
|
Format :
[PersonalContentV1URL]?action=[action name]&token=[user token]¶m=[value]
Exemple :
[PersonalContentV1URL]?action=getContentUploadURL&token=Hjlkzjlfkzef23423kjlkjr¶m=value…
NB : cet exemple met l'accent sur la manière de passer le jeton utilisateur dans les requêtes Personal Content. Pour le détail fonctionnel de l'API (détails des paramètres d'entrée et leurs valeurs possibles), voir ci-dessous.
|
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 contenu "Hello World " (image HelloWorld.jpg)
Ajouter un contenu « Hello World » au service "Mes Données" d'un client Orange est facile.
Premièrement, récupérez un jeton d'utilisateur en utilisant l'Authentication API. Ce jeton d'utilisateur sera utilisé comme paramètre « jeton » lors de l'appel de l'API Personal Content.
Pour plus d'informations, consultez la section comment authentifier l'utilisateur
Vous pourrez ensuite appeler la requête suivante pour obtenir une URL d'upload sur le service MesDonnées, pour y ajouter un contenu "HelloWorld" (une image par exemple) :
|
[PersonalContentV1URL]?action=getContentUploadURL&token=Hjlkzjlfkzef23423kjlkjr &content_name=HelloWorld.jpg&content_size=31163 |
En réponse, en cas de succès, l'API Personal Content fournira une réponse XML contenant :
un cookie "downloadUploadKey"
une URL de chargement
|
<?xml version="1.0" encoding="UTF-8"?>
<getContentUploadURLResponse>
<url><![CDATA[ url_value ]]></url>
<cookie>
<name>downloadUploadKey</name>
<value>cookie_value</value>
</cookie>
</getContentUploadURLResponse> |
Pour déposer votre contenu dans l'espace de stockage du client, il ne vous reste plus qu'à l'envoyer via un POST HTTP sur l'URL de chargement, en passant le cookie downloadUploadKey dans la requête. Pour plus de détails, les conditions techniques sont précisées dans la section ci-aprés.
Avec ces deux appels, vous aurez ajouté le contenu de l'image HelloWorld aux données de l'utilisateur Orange. Facile.
les méthodes de l'API Personal Content en détail
Récupération d'une URL d'upload du contenu sur l'espace de stokage "Mes Données" d'un utilisateur :
L'API Personal Content offre une méthode "getContentUploadURL" pour récupérer une URL d'upload d'un contenu dans la zone de stockage "Mes Données" d'un client Orange.
La réponse de cette méthode consiste en l'URL d'upload, et en un cookie downloadUploadKey.
Une fois en possession de ces éléments, il vous suffit, dans un deuxième temps, d'uploader votre contenu sur cette URL, en passant le cookie en en-tête HTTP, selon le formalisme décrit ci-après.
getContentUploadURL
getContentUploadURL
Pour appeler la méthode getContentUploadURL, créez l'URL selon le format suivant dans votre application Web et invoquez-la via l'opération HTTP GET (attention, le protocole est HTTPS) :
|
Format:
[PersonalContentV1URL]?action=[action name]&token=[user token]&content_name=[content_name]&content_size=[content_size]
Exemple:
[PersonalContentV1URL]?action=getContentUploadURL&token=Hjlkzjlfkzef23423kjlkjr &content_name=HelloWorld.jpg&content_size=31163
|
paramètres d'entrée
| Name |
Description |
Obligatoire |
Type |
| action |
le nom de la méthode Personal Content : getContentUploadURL |
Oui |
String |
| token |
le jeton utilisateur récupéré en invoquant l'API d'Authentification |
Oui |
String |
| content_name |
le nom du fichier à "uploader" |
Oui |
String |
| content_size |
la taille (en octets) du fichier à "uploader" |
Oui |
Integer |
exemple de réponse
S'il n'y a pas de problème, la réponse contiendra :
une URL d'upload sur le service "Mes Données",
ainsi qu'un cookie "downloadUploadKey" . Ce cookie est fournis dans le corps de la réponse.
Ci-dessous, un exemple de réponse pour cette méthode getContentUploadURL :
|
HTTP/1.1 200 OK
Content-Language: en-US
<?xml version="1.0" encoding="UTF-8"?>
<getContentUploadURLResponse>
<url><![CDATA[ url_value ]]></url>
<cookie>
<name>downloadUploadKey</name>
<value>cookie_value</value>
</cookie>
</getContentUploadURLResponse>
|
Dépose du contenu dans la zone de stockage "Mes Données" de l'utilisateur :
Pour déposer votre contenu dans l'espace de stockage du client, il ne vous reste plus qu'à envoyer ce contenu au format binaire, via un paramètre "file_content" dans une requête POST (multipart/form-data) sur l'URL HTTPS récupérée ci-dessus, en incluant le cookie downloadUploadKey en en-tête HTTP.
Attention, pour des raisons de sécurité, cette URL est limitée dans le temps, et n'est pas rejouable. Si le délai est dépassé ou s'il y a une erreur, il vous faudra redemander une URL.
Ci-dessous, un exemple de requête d'upload :
|
POST [UploadURL] HTTP/1.1
Connection: keep-alive
Content-Type: multipart/form-data; boundary=BPziGQhPkiFc_L0GBcrC7wBLAAoudpAFRJBc
Content-Length: [message length]
Cookie: downloadUploadKey=[cookie_value]
--BPziGQhPkiFc_L0GBcrC7wBLAAoudpAFRJBc
Content-Disposition: form-data; name="file_content"; filename="HelloWorld.jpg"
Content-Type: image/jpg
Content-Transfer-Encoding: binary
[actual file content, not shown here]
--BPziGQhPkiFc_L0GBcrC7wBLAAoudpAFRJBc--
|
En cas de succès, la réponse sera la suivante (le kit client contient le schéma XSD de cette réponse):
|
<storagexmlengine>
<uploadcontentdirectlyresponse>
<content>
<id>6174</id>
<parent_id>3449</parent_id>
<name>HelloWorld</name>
<commentary/>
<file_format/>
<file_size>31163</file_size>
<creation_date>2007-10-31T16:39:57.000+01:00</creation_date>
<last_modification_date>2007-10-31T16:39:57.000+01:00
</last_modification_date>
</content>
</uploadcontentdirectlyresponse>
</storagexmlengine> |
les codes d'erreurs de l'API Personal Content
Méthode getContentUploadURL
Lorsqu'une erreur se produit, une réponse est retournée au client au format HTTP, code 500. Le corps de la réponse contient un flux XML qui détaille l'erreur:
|
<?xml version="1.0"? encoding="UTF-8" >
<getContentUploadURLResponse>
<error>
<code> [code d'erreur] </code>
<detail> [message d'erreur] </detail>
</error>
</getContentUploadURLResponse> |
Les champs "code" et "detail" sont de type chaînes de caractères.
A noter: l'erreur MD804 rajoute un élément <url> aux éléments existants <url> et <detail>
Ci-dessous, un tableau décrivant les erreurs les plus significatives:
| Code d'erreur |
Message |
PA003 |
Invalid input parameter "content_name" |
| PA004 |
Invalid input parameter "content_size" |
| PA900 |
Personal Content API internal error : [code] |
| MD113 |
Your "Mes donnees" service account has been deactivated. Please contact the service administrator. |
| MD327 |
Insufficient available space |
| MD803 |
User suspended. Please contact the "Mes Données" service administrator. |
| MD804 |
User unknown. The Orange user should activate first their "Mes Données" service. (*)
The response format will be :
<?xml version="1.0"? encoding="UTF-8" >
<getContentUploadURLResponse>
<error>
<code> [error code] </code>
<detail> [error message] </detail>
</error>
<url> mes données portal url </url>
</getContentUploadURLResponse> |
|
(*)Actuellement, le service n'est pas activé implicitement. Le client.doit rediriger l'utilisateur Orange vers le portail "Mes Données" afin d'activer explicitement le service
upload du contenu
Lors du deuxième appel (chargement du contenu sur l'URL renvoyée par la méthode getContentUploadURL), les erreurs qui peuvent survenir sont renvoyées au format HTTP 400.
Le format des erreurs est le suivant:
<?xml version="1.0"?>
<mum>
<action>uploadcontent</action>
<parameters>request_parameters</parameters>
<response>
<message>error_details</message>
</response>
</mum> |
La liste des erreurs possibles est la suivante :
Erreur lors de la création d'un fichier temporaire [tmp file name]
Erreur lors de l'écriture du fichier dans le répertoire temporaire
Erreur lors de la récupération d'information sur le fichier temporaire
Le paramètre [param name] est introuvable dans [code]
Impossible de créer le contenu
Erreur lors du chargement du contenu.
La méthode HTTP doit être POST
Url de preprocess invalide
Url de postprocess invalide
(back to top)
