Примеры на PHP

Обзор

Все примеры кода в этом разделе используют следующие классы.

Класс Request использует cURL для выполнения запросов к API.

Класс Response содержит ответ API и информацию о возвращенном коде состояния.

Классы Request и Response

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;

        /**
         * Конструктор
         *
         * @param   string      $url
         * @param   string      $method
         * @param   array       $params
         */
        public function __construct($url, $method, $params = array()) {

            $this->_url = $url;

            // Установить метод
            $this->_method = $method;

            // Установить параметры
            $this->_params = $params;
        }

        /**
         * Определить метод Request
         *
         * @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;
            }
        }

        /**
         * Добавить заголовок авторизации
         *
         * @param   string  $type
         * @param   string  $token
         */
        public function setAuthorizationHeader($type, $token) {

            $authorization = $type . ' ' . $token;

            $this->_headers[] = 'Authorization: ' . $authorization;
        }

        /**
         * Добавить тело запроса
         */
        private function addBody() {

            if($this->_method != 'GET' && empty($this->_params) == false) {

                if(is_array($this->_params)) {
                    // Закодировать массив в JSON
                    $this->_params = json_encode($this->_params);
                }

                curl_setopt($this->_request, CURLOPT_POSTFIELDS, $this->_params);

                // Добавить заголовок Content-Length
                $this->_headers[] = 'Content-length: ' . strlen($this->_params);
            }
        }

        /**
         * Добавить строку запроса к запросу
         */
        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) {
                    // Сопоставить параметры с URL
                    foreach($this->_params as $param => $value) {
                        $this->_url = preg_replace('/{' . $param . '}/', $value, $this->_url);
                    }
                }
            }
        }

        /**
         * Отправить запрос
         */
        public function send() {

            // Инициализировать запрос cUrl
            $this->_request = curl_init();

            // Вернуть ответ в виде строки
            curl_setopt($this->_request, CURLOPT_RETURNTRANSFER, 1);

            // Добавить строку запроса
            $this->addQueryString();

            // Установить URL
            curl_setopt($this->_request, CURLOPT_URL, $this->_url);

            // Установить метод запроса
            $this->setMethod();

            // Добавить тело
            $this->addBody();

            if(empty($this->_headers) == false) {
                // Установить заголовки
                curl_setopt($this->_request, CURLOPT_HTTPHEADER, $this->_headers);
            }

            // Отключить проверки SSL
            curl_setopt($this->_request, CURLOPT_SSL_VERIFYPEER, false);
            curl_setopt($this->_request, CURLOPT_SSL_VERIFYHOST, false);

            // Отправить запрос и сохранить тело
            $this->_response = new Response(curl_exec($this->_request));

            // Установить код состояния
            $this->_response->setStatusCode(curl_getinfo($this->_request, CURLINFO_HTTP_CODE));

            // Закрыть соединение
            curl_close($this->_request);
        }

        /**
         * Получить ответ
         *
         * @return object
         */
        public function getResponse() {

            return $this->_response;
        }
    }

    class Response {

        /**
         * @var array
         */
        protected $_reason_phrases = array(
            // Информационные 1xx
            100 => "Продолжать",
            101 => "Переключение протоколов",

            // Успешные 2xx
            200 => "ОК",
            201 => "Создано",
            202 => "Принято",
            203 => "Информация не является авторитетной",
            204 => "Нет содержимого",
            205 => "Сбросить содержимое",
            206 => "Частичное содержимое",

            // Перенаправление 3xx
            300 => "Множественный выбор",
            301 => "Перемещено навсегда",
            302 => "Найдено",
            303 => "См. другое",
            304 => "Не изменено",
            305 => "Использовать прокси",
            306 => "(Не используется)",
            307 => "Временное перенаправление",

            // Ошибка клиента 4xx
            400 => "Неверный запрос",
            401 => "Не авторизован",
            402 => "Требуется оплата",
            403 => "Запрещено",
            404 => "Не найдено",
            405 => "Метод не разрешен",
            406 => "Неприемлемо",
            407 => "Требуется аутентификация прокси",
            408 => "Время ожидания запроса истекло",
            409 => "Конфликт",
            410 => "Удалено",
            411 => "Требуется длина",
            412 => "Предварительное условие не выполнено",
            413 => "Слишком большой размер запроса",
            414 => "Слишком длинный URI запроса",
            415 => "Неподдерживаемый тип медиа",
            416 => "Запрошенный диапазон не может быть удовлетворен",
            417 => "Ожидание не выполнено",

            // Ошибка сервера 5xx
            500 => "Внутренняя ошибка сервера",
            501 => "Не реализовано",
            502 => "Плохой шлюз",
            503 => "Сервис недоступен",
            504 => "Время ожидания шлюза истекло",
            505 => "Версия HTTP не поддерживается"
        );

        /**
         * @var integer
         */
        protected $_status_code;

        /**
         * @var string
         */
        protected $_body;

        /**
         * Конструктор
         *
         * @param   string      $body
         */
        public function __construct($body) {

            $this->_body = $body;
        }

        /**
         * Конструктор
         *
         * @param   string      $status_code
         */
        public function setStatusCode($status_code) {

            $this->_status_code = $status_code;
        }

        /**
         * Получить код состояния
         *
         * @return  integer
         */
        public function getStatusCode() {

            return $this->_status_code;
        }

        /**
         * Получить тело
         *
         * @return  string
         */
        public function getBody() {

            return $this->_body;
        }

        /**
         * Получить тело, декодированное из JSON
         *
         * @return  object|null
         */
        public function getBodyDecoded() {

            return json_decode($this->_body);
        }

        /**
         * Получить фразу причины
         *
         * @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;
            }
        }
    }

Вход

Есть два варианта запросить вход маршрут:

• с именем пользователя и паролем
• с API-токеном (токеном доступа)

Пример входа с параметрами имени пользователя и пароля.

<?php

    // Подключить классы Request и Response

    $url = 'https://api.example.com/v2/login';

    $params = array(
        'username'  => 'sample_username',
        'password'  => 'sample_password'
    );

    // Создать новый объект Request
    $request = new Request($url, 'POST', $params);

    // Отправить запрос
    $request->send();

    // Получить объект Response
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        // Получить данные сессионного токена
        $token = $response->getBodyDecoded();

        print_r($token);
    }
    else {

        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody() . PHP_EOL;
    }
?>

Пример входа с API-токеном (токеном доступа)

<?php

    // Подключить классы Request и Response

    $url = 'https://api.example.com/v2/login';

    $params = array(
            'api_token'  => 'sample_token_2bb447abb71b69368901a....'
        );

    // Создать новый объект Request
    $request = new Request($url, 'POST', $params);

    // Отправить запрос
    $request->send();

    // Получить объект Response
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        // Получить данные сессионного токена
        $token = $response->getBodyDecoded();

        print_r($token);
    }
    else {

        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody() . PHP_EOL;
    }
?>

Аутентификация

Каждый запрос к контенту, связанному с пользователем, требует Авторизация установки заголовка, значение которого содержит тип токена и сессионный токен, полученный из запроса входа в API.

Действительный /login запрос к API вернет следующую JSON-нагрузку.

{
  "token": "",
  "type": "",
  "expires_in": 0
}

Этот Сессионный токен должен быть включен во все последующие запросы к API, связанные с пользовательским контентом.

Этот type должен быть добавлен перед токеном, отделяясь одним пробелом.

Bearer 4e63518d383d8fcaefb516fe708b893727463031

Этот expires_in — это время в секундах, в течение которого токен будет действителен. Когда это время истечет, потребуется получить новый токен через запрос /login.

Пример получения и установки заголовка авторизации с именем пользователя и паролем

<?php

    // Подключить классы Request и Response

    // Вход
    $url = 'https://api.example.com/v2/login';

    $params = array(
        'username'  => 'sample_username',
        'password'  => 'sample_password'
    );

    // Создать новый объект Request
    $request = new Request($url, 'POST', $params);

    // Отправить запрос
    $request->send();

    // Получить объект Response
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        // Получить данные сессионного токена
        $token = $response->getBodyDecoded();

        // Получить кампании
        $url = 'https://api.example.com/v2/campaigns';

        // Создать новый объект Request
        $request = new Request($url, 'GET');

        // Установить заголовок авторизации
        $request->setAuthorizationHeader($token->type, $token->token);

        // Отправить запрос
        $request->send();

        // Получить объект Response
        $response = $request->getResponse();

        if($response->getStatusCode() == 200) {

            // Получить кампании
            $campaigns = $response->getBodyDecoded();

            foreach($campaigns->result as $campaign) {
                // Отобразить названия кампаний
                echo $campaign->name . PHP_EOL;
            }
        }
        else {
            // Ошибка запроса кампаний
            echo $response->getStatusCode() . PHP_EOL;
            echo $response->getReasonPhrase() . PHP_EOL;
            echo $response->getBody();
        }
    }
    else {
        // Неверный вход
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>

Пример получения и установки заголовка авторизации с API-токеном

<?php

    // Подключить классы Request и Response

    // Вход
    $url = 'https://api.example.com/v2/login';

    $params = array(
        'api_token'  => 'sample_token_2bb447abb71b69368901a....'
    );

    ...

?>

Коллекции

Ниже приведен пример запроса для получения Браузеры коллекции.

<?php

    // Подключить классы Request и Response

    $url = 'https://api.example.com/v2/collections/browsers';

    // Создать новый объект Request
    $request = new Request($url, 'GET');

    // Установить заголовок авторизации, полученный из предыдущего запроса входа
    $request->setAuthorizationHeader($token->type, $token->token);

    // Отправить запрос
    $request->send();

    // Получить объект Response
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        $browsers = $response->getBodyDecoded();

        foreach($browsers as $browser) {

            echo $browser->id . ': ' . $browser->name . PHP_EOL;
        }
    }
    else {
        // Коллекция не найдена
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>

Статистика

Ниже приведен пример запроса рекламодателя к statistics/a/date.

В случае additional_group_by если значение задано, запрос будет сгруппирован по основному полю маршрута и дополнительному(-ым).

Пример статистики по датам, отфильтрованной по ID кампании 1234.

<?php

    // Подключить классы Request и Response

    $url = 'https://api.example.com/v2/statistics/a/date';

    // Указать ID кампании
    $params = array(
       'campaignid'  => 1234
    );

    $request = new Request($url, 'GET', $params);

    // Установить заголовок авторизации, полученный из предыдущего запроса входа
    $request->setAuthorizationHeader($token->type, $token->token);

    // Отправить запрос
    $request->send();

    // Получить объект ответа
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        $statistics = $response->getBodyDecoded();

        foreach($statistics->result as $statistic) {

            echo $statistic->ddate . ': ' . $statistic->value . PHP_EOL;
        }
    }
    else {
        // Статистика кампаний не найдена
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>

Пример статистики по датам с дополнительной группировкой по кампании.

<?php

    // Подключить классы Request и Response

    $url = 'https://api.example.com/v2/statistics/a/date';

    // Указать ID кампании
    $params = array(
       'additional_group_by'  => 'campaign'
    );

    $request = new Request($url, 'GET', $params);

    // Установить заголовок авторизации, полученный из предыдущего запроса входа
    $request->setAuthorizationHeader($token->type, $token->token);

    // Отправить запрос
    $request->send();

    // Получить объект ответа
    $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 {
        // Статистика кампаний не найдена
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>

post /statistics/a/global

Получить глобальную статистику рекламодателя

Пример 1 глобальной статистики

Пример запроса глобальной статистики.

Только group_by параметр обязателен. Значения по умолчанию для остальных параметров можно найти здесь.

Обратите внимание, что маршруты глобальной статистики (statistics/a/global, statistics/p/global) имеют другой формат параметров.

<?php

    // Подключить классы Request и Response

    $url = 'https://api.example.com/v2/statistics/a/global';

    // Указать group_by
    $params = [
        "group_by" => ["date"]
    ];

    $request = new Request($url, 'POST', $params);

    // Установить заголовок авторизации, полученный из предыдущего запроса входа
    $request->setAuthorizationHeader($token->type, $token->token);

    // Отправить запрос
    $request->send();

    // Получить объект ответа
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        $statistics = $response->getBodyDecoded();

        foreach($statistics->result as $statistic) {
            echo 'Дата: ' . $statistic->group_by->date->date . ' -  Показов: ' . $statistic->impressions .' - Стоимость: ' .  $statistic->cost . PHP_EOL;
        }
    }
    else {
        // Статистика кампаний не найдена
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>

Пример 2 глобальной статистики

Получить статистику по датам, включая суммарные итоги.

<?php

    // Подключить классы Request и Response

    $url = 'https://api.example.com/v2/statistics/a/global';

    // Указать ID кампании
    $params = [
        "filter" => [
            "date_from" => "2019-01-10",
            "date_to" => "2019-01-31",
        ],
        "totals" => 1,
        "group_by" => ["date"]
    ];

    $request = new Request($url, 'POST', $params);

    // Установить заголовок авторизации, полученный из предыдущего запроса входа
    $request->setAuthorizationHeader($token->type, $token->token);

    // Отправить запрос
    $request->send();

    // Получить объект ответа
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        $statistics = $response->getBodyDecoded();

        foreach($statistics->result as $statistic) {
            echo 'Дата: ' . $statistic->group_by->date->date . ' -  Показов: ' . $statistic->impressions .' - Стоимость: ' .  $statistic->cost . PHP_EOL;
        }

        echo 'Общая стоимость:' . $statistics->result_total->cost . PHP_EOL;
    }
    else {
        // Статистика кампаний не найдена
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>

Пример 3 глобальной статистики

Получить статистику по кампаниям и странам, отфильтрованную по конкретной дате и отсортированную по показам.

<?php

    // Подключить классы Request и Response

    $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);

    // Установить заголовок авторизации, полученный из предыдущего запроса входа
    $request->setAuthorizationHeader($token->type, $token->token);

    // Отправить запрос
    $request->send();

    // Получить объект ответа
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        $statistics = $response->getBodyDecoded();

        foreach($statistics->result as $statistic) {
            echo 'Страна: ' . $statistic->group_by->country_iso->country_iso . ' -  ID кампании: ' . $statistic->group_by->campaign_id->id .' - Стоимость: ' .  $statistic->cost . PHP_EOL;
        }
    }
    else {
        // Статистика кампаний не найдена
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>

Пример 4 глобальной статистики

Получить статистику издателя по зонам и странам, отфильтрованную по конкретной операционной системе.

<?php

    // Подключить классы Request и Response

    $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);

    // Установить заголовок авторизации, полученный из предыдущего запроса входа
    $request->setAuthorizationHeader($token->type, $token->token);

    // Отправить запрос
    $request->send();

    // Получить объект ответа
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        $statistics = $response->getBodyDecoded();

        foreach($statistics->result as $statistic) {
            echo ' ID зоны:' . $statistic->group_by->zone_id->id . ' - Страна: ' . $statistic->group_by->country_iso->country_iso .' - Доход: ' .  $statistic->revenue . PHP_EOL;
        }
    }
    else {
        // Статистика кампаний не найдена
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>