Effettuare richieste autenticate

Per accedere agli endpoint della X Ads API, l’applicazione deve inviare richieste web autenticate in modo sicuro tramite TLS a https://ads-api.x.com.

Le sezioni seguenti offrono una panoramica sull’esecuzione di richieste API autenticate, sulla configurazione di Twurl per interagire con l’API e su come estendere l’applicazione per supportare OAuth 1.0a ed effettuare richieste per il proprio account Ads.

​

Requisiti

Prima di inviare richieste autenticate alla X Ads API, sono necessari:

• un account sviluppatore approvato
• un’app approvata per l’accesso alla X Ads API
• API Key e secret ottenuti tramite l’interfaccia di gestione dell’App e
• access tokens per un utente con accesso a un account X Ads

​

Utilizzo dell’API

L’Ads API è accessibile all’indirizzo https://ads-api.x.com. La REST API standard e l’Ads API possono essere usate insieme con la stessa App client. L’Ads API richiede HTTPS; pertanto, i tentativi di accedere a un endpoint tramite HTTP genereranno un messaggio di errore.

La X Ads API restituisce dati in formato JSON. Tutti gli identificatori sono stringhe e tutte le stringhe sono in UTF-8. L’Ads API è versionata e la versione è specificata come primo elemento del percorso in qualsiasi URL di risorsa.

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

​

Verbi HTTP e codici di risposta tipici

Nella X Ads API sono utilizzati quattro verbi HTTP:

• GET recupera i dati
• POST crea nuovi dati, ad esempio campagne
• PUT aggiorna dati esistenti, ad esempio line item
• DELETE rimuove i dati.

Sebbene le eliminazioni siano permanenti, i dati eliminati possono comunque essere visualizzati dalla maggior parte dei metodi basati su GET includendo il parametro esplicito with_deleted=true quando si richiede la risorsa. In caso contrario, i record eliminati restituiranno un HTTP 404.

Una richiesta eseguita correttamente restituirà una risposta HTTP della serie 200 insieme al payload JSON che rappresenta l’oggetto quando si crea, si elimina o si aggiorna una risorsa.

Quando si aggiornano i dati con HTTP PUT, verranno aggiornati solo i fields specificati. È possibile annullare l’impostazione di un valore facoltativo specificando il parametro con una stringa vuota. Ad esempio, questo gruppo di parametri annullerà qualsiasi end_time già specificato: &end_time=&paused=false.

Consulta Error Codes & Responses per ulteriori dettagli sulle risposte di errore.

​

Parametri in linea

La maggior parte degli URL delle risorse include uno o più parametri in linea. Molti URL accettano anche parametri dichiarati esplicitamente nella stringa query o, per le richieste POST o PUT, nel body.

I parametri in linea sono indicati da due punti anteposti (”:”) nella sezione Resource Path di ciascuna risorsa. Ad esempio, se l’account su cui stai lavorando fosse identificato come "abc1" e stessi recuperando le campagne associate a un account, accederesti a tale elenco utilizzando l’URL https://ads-api.x.com/6/accounts/abc1/campaigns. Specificando il parametro in linea account_id descritto nell’URL della risorsa (https://ads-api.x.com/6/accounts/:account_id/campaigns), limiterai l’ambito della richiesta agli oggetti associati esclusivamente a quell’account.

​

Utilizzo degli Access Tokens

La X Ads API utilizza richieste HTTPS firmate per convalidare l’identità di un’applicazione e per ottenere le autorizzazioni concesse all’utente finale per conto del quale l’applicazione effettua richieste API, rappresentate dall’access token dell’utente. Tutte le chiamate HTTP alla X Ads API devono includere l’intestazione di richiesta Authorization (utilizzando OAuth 1.0a) sul protocollo HTTPS.

Per integrare la tua applicazione con la X Ads API, dovrai aggiungere il supporto per generare le intestazioni di richiesta Authorization di OAuth 1.0a. Tuttavia, data la complessità della generazione di richieste firmate, consigliamo vivamente ai partner di utilizzare una libreria esistente che supporti la X API o che implementi la gestione delle richieste OAuth 1.0a: ecco un elenco di librerie OAuth consigliate e di esempi di codice per l’autenticazione.

Nota: possiamo assistere i partner che riscontrano errori di autenticazione utilizzando una libreria nota, ma non possiamo supportare implementazioni OAuth personalizzate.

​

HTTP & OAuth

Come per X REST API v1.1, la Advertising API richiede l’uso sia di OAuth 1.0a sia di HTTPS. Le API Key possono essere ottenute tramite la app management console. Gli Access Tokens devono inoltre essere utilizzati per rappresentare l’“utente corrente”. L’utente corrente è un account X con funzionalità pubblicitarie.

Si raccomanda vivamente ai partner di utilizzare una libreria OAuth, invece di scriverne una propria. Possiamo fornire supporto al debug quando si utilizza una libreria nota, ma non possiamo farlo se implementate OAuth in proprio. Consultate le librerie che potete utilizzare.

L’API è rigorosa con HTTP 1.1 e OAuth. Assicuratevi di codificare correttamente i caratteri riservati all’interno degli URL e dei corpi delle richieste POST prima di preparare le base string della firma OAuth. In particolare, la Advertising API usa i caratteri “:” quando si specifica l’ora e “,” quando si fornisce una raccolta di opzioni. Entrambi i caratteri rientrano nell’insieme riservato:

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

​

Effettuare la tua prima richiesta API con Twurl

X mantiene uno strumento da riga di comando, Twurl, che supporta le intestazioni di autorizzazione OAuth 1.0a ed è un’alternativa a cURL. Twurl offre un modo semplice per inviare richieste API autenticate ed esplorare la X Ads API prima di aggiungere l’autenticazione alla tua applicazione.

Dopo aver installato e autorizzato Twurl, puoi generare rapidamente access token e inviare richieste autenticate alla X Ads API.

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

Dedica un po’ di tempo a familiarizzare con Twurl e l’API seguendo questo tutorial passo per passo per creare una campagna tramite l’API.

​

Test con Postman

Per chi non ha familiarità con gli strumenti da riga di comando, mettiamo anche a disposizione una raccolta Postman per gli endpoint della X Ads API.

Postman è uno degli strumenti di sviluppo API più popolari nel settore. È un client HTTP con un’ottima interfaccia utente che semplifica la creazione di richieste API complesse e aumenta la produttività.

Per installare Postman e iniziare a usare la raccolta Postman della X Ads API, consulta la nostra guida alla configurazione.

​

Estendere la tua applicazione per effettuare richieste autenticate

Dopo aver acquisito familiarità con le richieste alla X Ads API utilizzando Twurl, è il momento di aggiungere alla tua applicazione il supporto per la creazione delle intestazioni di autenticazione OAuth 1.0a.

Le intestazioni di autenticazione OAuth 1.0a includono informazioni che verificano l’identità dell’applicazione e dell’utente e impediscono la manomissione della richiesta. La tua applicazione dovrà creare una nuova intestazione Authorization per ogni richiesta API. Molti linguaggi dispongono di librerie open source che consentono di generare questa intestazione di autorizzazione per effettuare richieste API a X.

Ecco alcuni esempi in C#, PHP, Ruby e Python — esempi di codice.

​

Implementazione personalizzata

Esistono alcuni scenari che richiedono di implementare l’autenticazione OAuth 1.0a senza il supporto di una libreria open source. Autorizzare una richiesta fornisce istruzioni dettagliate per implementare la creazione dell’header Authorization. Consigliamo vivamente di utilizzare una libreria supportata dalla community.

Schema generale:

1. Raccogli 7 coppie chiave/valore per l’header, tutte con prefisso oauth_
2. Genera una firma OAuth 1.0a HMAC-SHA1 utilizzando tali coppie chiave/valore
3. Crea l’header Authorization utilizzando i valori sopra indicati