PHP Examples
Visión general
Todos los ejemplos de código de esta sección utilizan las siguientes clases.
La clase Request utiliza cURL para realizar las peticiones a la API.
La clase Response contiene la respuesta de la API y la información del código de estado devuelto.
class Request {
/**
* @var resource
*/
protected $_request;
/**
* @var integer
*/
protected $_method;
/**
* @var string
*/
protected $_url;
/**
* @var array
*/
protected $_headers = array(
'Content-type: application/json'
);
/**
* @var string|array
*/
protected $_params;
/**
* @var object Response
*/
protected $_reponse;
/**
* Constructor
*
* @param string $url
* @param string $method
* @param array $params
*/
public function __construct($url, $method, $params = array()) {
$this->_url = $url;
// Set the method
$this->_method = $method;
// Set the params
$this->_params = $params;
}
/**
* Determine the Request method
*
* @param string $method
*/
private function setMethod() {
switch($this->_method) {
case 'GET':
break;
case 'POST':
curl_setopt($this->_request, CURLOPT_POST, 1);
break;
case 'PUT':
curl_setopt($this->_request, CURLOPT_CUSTOMREQUEST, 'PUT');
break;
case 'DELETE':
curl_setopt($this->_request, CURLOPT_CUSTOMREQUEST, 'DELETE');
break;
}
}
/**
* Add authorization header
*
* @param string $type
* @param string $token
*/
public function setAuthorizationHeader($type, $token) {
$authorization = $type . ' ' . $token;
$this->_headers[] = 'Authorization: ' . $authorization;
}
/**
* Add body to request
*/
private function addBody() {
if($this->_method != 'GET' && empty($this->_params) == false) {
if(is_array($this->_params)) {
// JSON Encode the array
$this->_params = json_encode($this->_params);
}
curl_setopt($this->_request, CURLOPT_POSTFIELDS, $this->_params);
// Add a content-length header
$this->_headers[] = 'Content-length: ' . strlen($this->_params);
}
}
/**
* Add a query string to the request
*/
private function addQueryString() {
if($this->_method == 'GET' && is_array($this->_params) && count($this->_params) > 0) {
$query_string = '?';
foreach($this->_params as $param => $value) {
$query_string = $query_string . $param . '=' . $value . '&';
}
trim($query_string, '&');
$this->_url = $this->_url . $query_string;
}
else {
if(is_array($this->_params) && count($this->_params) > 0 && strpos($this->_url, '{') !== false) {
// Pattern match params against the url
foreach($this->_params as $param => $value) {
$this->_url = preg_replace('/{' . $param . '}/', $value, $this->_url);
}
}
}
}
/**
* Send the request
*/
public function send() {
// Initialise cUrl request
$this->_request = curl_init();
// Return the response as a string
curl_setopt($this->_request, CURLOPT_RETURNTRANSFER, 1);
// Add a query string
$this->addQueryString();
// Set the URL
curl_setopt($this->_request, CURLOPT_URL, $this->_url);
// Set request method
$this->setMethod();
// Add a body
$this->addBody();
if(empty($this->_headers) == false) {
// Set the headers
curl_setopt($this->_request, CURLOPT_HTTPHEADER, $this->_headers);
}
// Disable SSL checks
curl_setopt($this->_request, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($this->_request, CURLOPT_SSL_VERIFYHOST, false);
// Send the request and store the body
$this->_response = new Response(curl_exec($this->_request));
// Set the status code
$this->_response->setStatusCode(curl_getinfo($this->_request, CURLINFO_HTTP_CODE));
// Close the connection
curl_close($this->_request);
}
/**
* Get the response
*
* @return object
*/
public function getResponse() {
return $this->_response;
}
}
class Response {
/**
* @var array
*/
protected $_reason_phrases = array(
//Informational 1xx
100 => "Continue",
101 => "Switching Protocols",
// Successful 2xx
200 => "OK",
201 => "Created",
202 => "Accepted",
203 => "Non-Authoritative Information",
204 => "No Content",
205 => "Reset Content",
206 => "Partial Content",
// Redirection 3xx
300 => "Multiple Choices",
301 => "Moved Permanently",
302 => "Found",
303 => "See Other",
304 => "Not Modified",
305 => "Use Proxy",
306 => "(Unused)",
307 => "Temporary Redirect",
// Client Error 4xx
400 => "Bad Request",
401 => "Unauthorized",
402 => "Payment Required",
403 => "Forbidden",
404 => "Not Found",
405 => "Method Not Allowed",
406 => "Not Acceptable",
407 => "Proxy Authentication Required",
408 => "Request Timeout",
409 => "Conflict",
410 => "Gone",
411 => "Length Required",
412 => "Precondition Failed",
413 => "Request Entity Too Large",
414 => "Request-URI Too Long",
415 => "Unsupported Media Type",
416 => "Requested Range Not Satisfiable",
417 => "Expectation Failed",
// Server Error 5xx
500 => "Internal Server Error",
501 => "Not Implemented",
502 => "Bad Gateway",
503 => "Service Unavailable",
504 => "Gateway Timeout",
505 => "HTTP Version Not Supported"
);
/**
* @var integer
*/
protected $_status_code;
/**
* @var string
*/
protected $_body;
/**
* Constructor
*
* @param string $body
*/
public function __construct($body) {
$this->_body = $body;
}
/**
* Constructor
*
* @param string $status_code
*/
public function setStatusCode($status_code) {
$this->_status_code = $status_code;
}
/**
* Get status code
*
* @return integer
*/
public function getStatusCode() {
return $this->_status_code;
}
/**
* Get body
*
* @return string
*/
public function getBody() {
return $this->_body;
}
/**
* Get body JSON Decoded
*
* @return object|null
*/
public function getBodyDecoded() {
return json_decode($this->_body);
}
/**
* Get reason phrase
*
* @return string|boolean
*/
public function getReasonPhrase() {
if(array_key_exists($this->_status_code, $this->_reason_phrases)) {
return $this->_reason_phrases[$this->_status_code];
}
else {
return false;
}
}
}
Inicio de sesión
Hay dos opciones para solicitar la ruta login:
- con nombre de usuario y contraseña
- con token api (token de acceso)
Ejemplo de inicio de sesión con parámetros de nombre de usuario y contraseña.
<?php
// Include Request and Response classes
$url = 'https://api.example.com/v2/login';
$params = array(
'username' => 'sample_username',
'password' => 'sample_password'
);
// Create a new Request object
$request = new Request($url, 'POST', $params);
// Send the request
$request->send();
// Get the Response object
$response = $request->getResponse();
if($response->getStatusCode() == 200) {
// Retrieve the session token details
$token = $response->getBodyDecoded();
print_r($token);
}
else {
echo $response->getStatusCode() . PHP_EOL;
echo $response->getReasonPhrase() . PHP_EOL;
echo $response->getBody() . PHP_EOL;
}
?>
Ejemplo de inicio de sesión con token de API (token de acceso)
<?php
// Include Request and Response classes
$url = 'https://api.example.com/v2/login';
$params = array(
'api_token' => 'sample_token_2bb447abb71b69368901a....'
);
// Create a new Request object
$request = new Request($url, 'POST', $params);
// Send the request
$request->send();
// Get the Response object
$response = $request->getResponse();
if($response->getStatusCode() == 200) {
// Retrieve the session token details
$token = $response->getBodyDecoded();
print_r($token);
}
else {
echo $response->getStatusCode() . PHP_EOL;
echo $response->getReasonPhrase() . PHP_EOL;
echo $response->getBody() . PHP_EOL;
}
?>
Autenticación
Cada solicitud de contenido relacionado con el usuario requiere que se establezca un encabezado Authorization, cuyo valor contenga el tipo de token y el token de sesión recibidos de la solicitud de inicio de sesión de la API.
Una solicitud /login válida a la API devolverá la siguiente carga json.
{
"token": "",
"type": "",
"expires_in": 0
}
El token de sesión debe incluirse en todas las solicitudes de contenido relacionadas con el usuario que se realicen posteriormente a la API.
El tipo se antepone al símbolo, separado por un espacio.
Bearer 4e63518d383d8fcaefb516fe708b893727463031
El expires_in es el tiempo en segundos que el token será válido. Cuando este tiempo expire, será necesario obtener un nuevo token a través de la petición /login.
Ejemplo de obtención y configuración del encabezado de autorización con nombre de usuario y contraseña
<?php
// Include Request and Response classes
// Login
$url = 'https://api.example.com/v2/login';
$params = array(
'username' => 'sample_username',
'password' => 'sample_password'
);
// Create a new Request object
$request = new Request($url, 'POST', $params);
// Send the request
$request->send();
// Get the Response object
$response = $request->getResponse();
if($response->getStatusCode() == 200) {
// Retrieve the session token details
$token = $response->getBodyDecoded();
// Get Campaigns
$url = 'https://api.example.com/v2/campaigns';
// Create a new Request object
$request = new Request($url, 'GET');
// Set the Authorization Header
$request->setAuthorizationHeader($token->type, $token->token);
// Send the request
$request->send();
// Get the Response object
$response = $request->getResponse();
if($response->getStatusCode() == 200) {
// Retrieve the campaigns
$campaigns = $response->getBodyDecoded();
foreach($campaigns->result as $campaign) {
// Display the campaign names
echo $campaign->name . PHP_EOL;
}
}
else {
// Campaigns request error
echo $response->getStatusCode() . PHP_EOL;
echo $response->getReasonPhrase() . PHP_EOL;
echo $response->getBody();
}
}
else {
// Invalid Login
echo $response->getStatusCode() . PHP_EOL;
echo $response->getReasonPhrase() . PHP_EOL;
echo $response->getBody();
}
?>
Ejemplo de obtención y configuración del encabezado de autorización con token de API
<?php
// Include Request and Response classes
// Login
$url = 'https://api.example.com/v2/login';
$params = array(
'api_token' => 'sample_token_2bb447abb71b69368901a....'
);
...
?>
Colecciones
A continuación se muestra un ejemplo de solicitud para obtener la colección Browsers.
<?php
// Include Request and Response classes
$url = 'https://api.example.com/v2/collections/browsers';
// Create a new Request object
$request = new Request($url, 'GET');
// Set the Authorization Header retrieved from earlier Login request
$request->setAuthorizationHeader($token->type, $token->token);
// Send the request
$request->send();
// Get the Response object
$response = $request->getResponse();
if($response->getStatusCode() == 200) {
$browsers = $response->getBodyDecoded();
foreach($browsers as $browser) {
echo $browser->id . ': ' . $browser->name . PHP_EOL;
}
}
else {
// Collection not found
echo $response->getStatusCode() . PHP_EOL;
echo $response->getReasonPhrase() . PHP_EOL;
echo $response->getBody();
}
?>
Estadísticas
A continuación se muestra un ejemplo de solicitud de un anunciante a statistics/a/date.
En caso de que se defina el valor additional_group_by, la solicitud se agrupará por el campo de ruta principal y el/los extra(s).
Ejemplo de estadísticas por fecha filtradas por el ID de campaña 1234.
<?php
// Include Request and Response classes
$url = 'https://api.example.com/v2/statistics/a/date';
// Specify the campaign id
$params = array(
'campaignid' => 1234
);
$request = new Request($url, 'GET', $params);
// Set the Authorization Header, retrieved from earlier Login request
$request->setAuthorizationHeader($token->type, $token->token);
// Send the request
$request->send();
// Get the response object
$response = $request->getResponse();
if($response->getStatusCode() == 200) {
$statistics = $response->getBodyDecoded();
foreach($statistics->result as $statistic) {
echo $statistic->ddate . ': ' . $statistic->value . PHP_EOL;
}
}
else {
// Campaign statistics not found
echo $response->getStatusCode() . PHP_EOL;
echo $response->getReasonPhrase() . PHP_EOL;
echo $response->getBody();
}
?>
Ejemplo de estadísticas por fecha con agrupación adicional por campaña.
<?php
// Include Request and Response classes
$url = 'https://api.example.com/v2/statistics/a/date';
// Specify the campaign id
$params = array(
'additional_group_by' => 'campaign'
);
$request = new Request($url, 'GET', $params);
// Set the Authorization Header, retrieved from earlier Login request
$request->setAuthorizationHeader($token->type, $token->token);
// Send the request
$request->send();
// Get the response object
$response = $request->getResponse();
if($response->getStatusCode() == 200) {
$statistics = $response->getBodyDecoded();
foreach($statistics->result as $statistic) {
echo $statistic->ddate . ' - ' . $statistic->idcampaign . ': ' . $statistic->value . PHP_EOL;
}
}
else {
// Campaign statistics not found
echo $response->getStatusCode() . PHP_EOL;
echo $response->getReasonPhrase() . PHP_EOL;
echo $response->getBody();
}
?>
post /estadisticas/a/global
Get global advertiser statistics
Ejemplo 1 de estadísticas globales
Ejemplo de solicitud de estadísticas globales.
Sólo el parámetro group_by es obligatorio. Los valores por defecto para los otros parámetros se pueden encontrar Aquí.
Tenga en cuenta que las rutas de estadísticas globales (statistics/a/global, statistics/p/global) tienen un formato de parámetros diferente.
<?php
// Include Request and Response classes
$url = 'https://api.example.com/v2/statistics/a/global';
// Specify the group_by
$params = [
"group_by" => ["date"]
];
$request = new Request($url, 'POST', $params);
// Set the Authorization Header, retrieved from earlier Login request
$request->setAuthorizationHeader($token->type, $token->token);
// Send the request
$request->send();
// Get the response object
$response = $request->getResponse();
if($response->getStatusCode() == 200) {
$statistics = $response->getBodyDecoded();
foreach($statistics->result as $statistic) {
echo 'Date: ' . $statistic->group_by->date->date . ' - Impressions: ' . $statistic->impressions .' - Cost: ' . $statistic->cost . PHP_EOL;
}
}
else {
// Campaign statistics not found
echo $response->getStatusCode() . PHP_EOL;
echo $response->getReasonPhrase() . PHP_EOL;
echo $response->getBody();
}
?>
Ejemplo 2 de estadísticas globales
Obtenga estadísticas por fecha, incluida la suma total.
<?php
// Include Request and Response classes
$url = 'https://api.example.com/v2/statistics/a/global';
// Specify the campaign id
$params = [
"filter" => [
"date_from" => "2019-01-10",
"date_to" => "2019-01-31",
],
"totals" => 1,
"group_by" => ["date"]
];
$request = new Request($url, 'POST', $params);
// Set the Authorization Header, retrieved from earlier Login request
$request->setAuthorizationHeader($token->type, $token->token);
// Send the request
$request->send();
// Get the response object
$response = $request->getResponse();
if($response->getStatusCode() == 200) {
$statistics = $response->getBodyDecoded();
foreach($statistics->result as $statistic) {
echo 'Date: ' . $statistic->group_by->date->date . ' - Impressions: ' . $statistic->impressions .' - Cost: ' . $statistic->cost . PHP_EOL;
}
echo 'Total cost:' . $statistics->result_total->cost . PHP_EOL;
}
else {
// Campaign statistics not found
echo $response->getStatusCode() . PHP_EOL;
echo $response->getReasonPhrase() . PHP_EOL;
echo $response->getBody();
}
?>
Ejemplo 3 de estadísticas globales
Obtenga estadísticas por campaña y país filtradas por fecha específica ordenadas por impresiones.
<?php
// Include Request and Response classes
$url = 'https://api.example.com/v2/statistics/a/global';
$params = [
"filter" => [
"date_from" => "2019-01-30",
"date_to" => "2019-01-30",
],
"group_by" => ["country_iso", "campaign_id"],
"order_by" => [
["field" => "impressions", "order" => "desc"]
]
];
$request = new Request($url, 'POST', $params);
// Set the Authorization Header, retrieved from earlier Login request
$request->setAuthorizationHeader($token->type, $token->token);
// Send the request
$request->send();
// Get the response object
$response = $request->getResponse();
if($response->getStatusCode() == 200) {
$statistics = $response->getBodyDecoded();
foreach($statistics->result as $statistic) {
echo 'Country: ' . $statistic->group_by->country_iso->country_iso . ' - Campaign ID: ' . $statistic->group_by->campaign_id->id .' - Cost: ' . $statistic->cost . PHP_EOL;
}
}
else {
// Campaign statistics not found
echo $response->getStatusCode() . PHP_EOL;
echo $response->getReasonPhrase() . PHP_EOL;
echo $response->getBody();
}
?>
Ejemplo 4 de estadísticas globales
Obtenga estadísticas de editores por zona y país filtradas por sistema operativo específico.
<?php
// Include Request and Response classes
$url = 'https://api.example.com/v2/statistics/p/global';
$params = [
"filter" => [
"date_from" => "2019-01-30",
"date_to" => "2019-01-30",
"operating_system_id" => [11, 12]
],
"group_by" => ["zone_id", "country_iso"]
];
$request = new Request($url, 'POST', $params);
// Set the Authorization Header, retrieved from earlier Login request
$request->setAuthorizationHeader($token->type, $token->token);
// Send the request
$request->send();
// Get the response object
$response = $request->getResponse();
if($response->getStatusCode() == 200) {
$statistics = $response->getBodyDecoded();
foreach($statistics->result as $statistic) {
echo ' Zone ID:' . $statistic->group_by->zone_id->id . ' - Country: ' . $statistic->group_by->country_iso->country_iso .' - Revenue: ' . $statistic->revenue . PHP_EOL;
}
}
else {
// Campaign statistics not found
echo $response->getStatusCode() . PHP_EOL;
echo $response->getReasonPhrase() . PHP_EOL;
echo $response->getBody();
}
?>