Effectuer des requêtes authentifiées

L’accès aux endpoints de la X Ads API nécessite que votre application envoie des requêtes Web authentifiées, de manière sécurisée, via TLS vers https://ads-api.x.com.

Les sections suivantes présentent une vue d’ensemble de la création de requêtes API authentifiées, de la configuration de Twurl pour interagir avec l’API, ainsi que de l’adaptation de votre application afin de prendre en charge OAuth 1.0a et d’effectuer des requêtes sur votre compte Ads.

​

Prérequis

Avant d’effectuer des requêtes authentifiées auprès de la X Ads API, vous aurez besoin de :

• d’un compte développeur approuvé
• d’une application approuvée pour l’accès à la X Ads API
• de l’API Key et du secret obtenus via l’interface de gestion des Apps et
• d’access tokens pour un utilisateur ayant accès à un compte X Ads

​

Utilisation de l’API

L’Ads API est accessible à l’adresse https://ads-api.x.com. L’API REST standard et l’Ads API peuvent être utilisées ensemble avec la même App cliente. L’Ads API impose HTTPS ; par conséquent, toute tentative d’accéder à un endpoint via HTTP entraînera un message d’erreur.

L’Ads API renvoie du JSON. Tous les identifiants sont des chaînes et toutes les chaînes sont en UTF‑8. L’Ads API est versionnée et la version est spécifiée comme premier élément du chemin de toute URL de ressource.

https://ads-api.x.com/<version>/accounts

​

Verbes HTTP et codes de réponse typiques

Quatre verbes HTTP sont utilisés dans la X Ads API :

• GET récupère des données 
• POST crée de nouvelles données, telles que des campagnes
• PUT met à jour des données existantes, comme des éléments de ligne
• DELETE supprime des données.

Bien que les suppressions soient permanentes, les données supprimées peuvent toujours être consultées via la plupart des méthodes basées sur GET en incluant explicitement le paramètre with_deleted=true lors de la requête de la ressource. Sinon, les enregistrements supprimés renverront un code HTTP 404.

Une requête réussie renverra une réponse HTTP de la série 200, accompagnée de la réponse JSON représentant l’objet lors de la création, de la suppression ou de la mise à jour d’une ressource.

Lors de la mise à jour de données avec HTTP PUT, seuls les fields spécifiés seront mis à jour. Vous pouvez annuler la définition d’une valeur optionnelle en spécifiant le paramètre avec une chaîne vide. Par exemple, ce groupe de paramètres annulerait toute valeur end_time déjà spécifiée : &end_time=&paused=false.

Voir Error Codes & Responses pour plus de détails sur les réponses d’erreur.

​

Paramètres en ligne

La plupart des URL de ressources comportent un ou plusieurs paramètres en ligne. De nombreuses URL acceptent également des paramètres explicitement déclarés dans la chaîne de requête ou, pour les requêtes POST ou PUT, dans le corps.

Les paramètres en ligne sont signalés par un deux-points préfixé (”:”) dans la section Resource Path de chaque ressource. Par exemple, si le compte sur lequel vous travaillez est identifié par “abc1” et que vous récupérez les campagnes associées à un compte, vous accédez à cette liste via l’URL https://ads-api.x.com/6/accounts/abc1/campaigns. En spécifiant le paramètre en ligne account_id décrit dans l’URL de ressource (https://ads-api.x.com/6/accounts/:account_id/campaigns), vous restreignez la requête aux objets associés uniquement à ce compte.

​

Utilisation des Access Tokens

La X Ads API utilise des requêtes HTTPS signées pour valider l’identité d’une application et obtenir les autorisations accordées à l’utilisateur final pour le compte duquel l’application effectue une requête API, représentées par l’access token de l’utilisateur. Tous les appels HTTP vers la X Ads API doivent inclure un en-tête de requête Authorization (avec OAuth 1.0a) sur le protocole HTTPS.

Vous devrez ajouter la prise en charge de la génération des en‑têtes de requête Authorization OAuth 1.0a dans votre application afin de vous intégrer à la X Ads API. Toutefois, en raison de la complexité de la génération de requêtes signées, nous recommandons fortement aux partenaires d’utiliser une bibliothèque existante qui prend en charge la X API ou implémente la gestion des requêtes OAuth 1.0a — voici une liste de bibliothèques OAuth recommandées et d’exemples de code d’authentification.

Notez que nous pouvons assister les partenaires qui rencontrent des erreurs d’authentification lorsqu’ils utilisent une bibliothèque reconnue, mais nous ne pouvons pas prendre en charge les implémentations OAuth personnalisées.

​

HTTP et OAuth

Comme pour l’API REST X v1.1, l’Advertising API nécessite l’utilisation d’OAuth 1.0a et de HTTPS. Des API Keys peuvent être obtenues via la console de gestion des Apps. Des access tokens doivent également être utilisés pour représenter « l’utilisateur actuel ». L’utilisateur actuel est un compte X disposant de fonctionnalités publicitaires.

Il est fortement recommandé aux partenaires d’utiliser une bibliothèque OAuth plutôt que d’écrire la leur. Nous pouvons aider au débogage si vous utilisez une bibliothèque reconnue, mais pas si vous développez votre propre implémentation OAuth. Consultez les bibliothèques disponibles.

L’API est stricte avec HTTP/1.1 et OAuth. Assurez-vous d’encoder correctement les caractères réservés dans les URL et les corps de requêtes POST avant de préparer les chaînes de base de signature OAuth. L’Advertising API, en particulier, utilise le caractère « : » pour spécifier l’heure et « , » pour fournir une collection d’options. Ces deux caractères font partie de cet ensemble réservé :

Symbole	Encodé en URL
!	%21
#	%23
$	%24
&	%26
’	%27
(	%28
)	%29
*	%2A
+	%2B
,	%2C
/	%2F
:	%3A
;	%3B
=	%3D
?	%3F
@	%40
[	%5B
]	%5D

​

Effectuer votre première requête API avec Twurl

X entretient un outil en ligne de commande, Twurl, qui prend en charge les en-têtes d’autorisation OAuth 1.0a et constitue une alternative à cURL. Twurl offre un moyen simple d’effectuer des requêtes API authentifiées et d’explorer la X Ads API avant d’ajouter l’authentification à votre application.

Après avoir installé et autorisé Twurl, vous pouvez rapidement générer des access tokens et effectuer des requêtes authentifiées vers la X Ads API.

twurl -H "ads-api.x.com" "/5/accounts/"

Prenez le temps de vous familiariser avec Twurl et l’API en suivant ce tutoriel pas à pas pour créer une campagne via l’API.

​

Tests avec Postman

Pour celles et ceux qui ne sont pas à l’aise avec les outils en ligne de commande, nous proposons également une collection Postman pour les endpoints de la X Ads API.

Postman est l’un des outils de développement d’API les plus populaires du secteur aujourd’hui. Il s’agit d’un client HTTP doté d’une excellente interface utilisateur qui simplifie l’envoi de requêtes API complexes et améliore la productivité.

Pour installer Postman et commencer à utiliser la collection Postman pour la X Ads API, veuillez consulter notre guide de configuration.

​

Étendre votre application pour effectuer des requêtes authentifiées

Après vous être familiarisé avec l’envoi de requêtes à la X Ads API à l’aide de Twurl, il est temps d’ajouter à votre application la prise en charge de la création d’en-têtes d’authentification OAuth 1.0a.

Les en-têtes d’authentification OAuth 1.0a contiennent des informations qui vérifient l’identité de l’application et de l’utilisateur, et qui empêchent également toute altération de la requête. Votre application devra créer un nouvel en-tête Authorization pour chaque requête à l’API. De nombreux langages disposent de bibliothèques open source qui prennent en charge la création de cet en-tête d’authentification pour effectuer des requêtes à l’API X.

Voici quelques exemples en C#, PHP, Ruby et Python — exemples de code.

​

Implémentation personnalisée

Certains scénarios requièrent d’implémenter l’authentification OAuth 1.0a sans recourir à une bibliothèque open source. Autoriser une requête fournit des instructions détaillées pour mettre en place la création de l’en-tête Authorization. Nous recommandons vivement d’utiliser une bibliothèque maintenue par la communauté.

Aperçu général :

1. Rassembler 7 paires clé/valeur pour l’en-tête — commençant par oauth_
2. Générer une signature OAuth 1.0a HMAC-SHA1 à l’aide de ces paires clé/valeur
3. Construire l’en-tête Authorization en utilisant les valeurs ci-dessus