PHP-Beispiele

Überblick

Alle Codebeispiele in diesem Abschnitt verwenden die folgenden Klassen.

Die Request-Klasse verwendet cURL um die Anfragen an die API zu stellen.

Die Response-Klasse enthält die API-Antwort und Informationen zum zurückgegebenen Statuscode.

Request- und Response-Klassen

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;

        /**
         * Konstruktor
         *
         * @param   string      $url
         * @param   string      $method
         * @param   array       $params
         */
        public function __construct($url, $method, $params = array()) {

            $this->_url = $url;

            // Die Methode festlegen
            $this->_method = $method;

            // Die Parameter festlegen
            $this->_params = $params;
        }

        /**
         * Die Request-Methode bestimmen
         *
         * @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;
            }
        }

        /**
         * Authorization-Header hinzufügen
         *
         * @param   string  $type
         * @param   string  $token
         */
        public function setAuthorizationHeader($type, $token) {

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

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

        /**
         * Body zur Anfrage hinzufügen
         */
        private function addBody() {

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

                if(is_array($this->_params)) {
                    // Das Array als JSON kodieren
                    $this->_params = json_encode($this->_params);
                }

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

                // Einen Content-length-Header hinzufügen
                $this->_headers[] = 'Content-length: ' . strlen($this->_params);
            }
        }

        /**
         * Einen Query-String zur Anfrage hinzufügen
         */
        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) {
                    // Parameter per Muster mit der URL abgleichen
                    foreach($this->_params as $param => $value) {
                        $this->_url = preg_replace('/{' . $param . '}/', $value, $this->_url);
                    }
                }
            }
        }

        /**
         * Die Anfrage senden
         */
        public function send() {

            // cURL-Anfrage initialisieren
            $this->_request = curl_init();

            // Die Antwort als String zurückgeben
            curl_setopt($this->_request, CURLOPT_RETURNTRANSFER, 1);

            // Einen Query-String hinzufügen
            $this->addQueryString();

            // Die URL festlegen
            curl_setopt($this->_request, CURLOPT_URL, $this->_url);

            // Anfragemethode festlegen
            $this->setMethod();

            // Einen Body hinzufügen
            $this->addBody();

            if(empty($this->_headers) == false) {
                // Die Header festlegen
                curl_setopt($this->_request, CURLOPT_HTTPHEADER, $this->_headers);
            }

            // SSL-Prüfungen deaktivieren
            curl_setopt($this->_request, CURLOPT_SSL_VERIFYPEER, false);
            curl_setopt($this->_request, CURLOPT_SSL_VERIFYHOST, false);

            // Die Anfrage senden und den Body speichern
            $this->_response = new Response(curl_exec($this->_request));

            // Den Statuscode festlegen
            $this->_response->setStatusCode(curl_getinfo($this->_request, CURLINFO_HTTP_CODE));

            // Die Verbindung schließen
            curl_close($this->_request);
        }

        /**
         * Die Antwort abrufen
         *
         * @return object
         */
        public function getResponse() {

            return $this->_response;
        }
    }

    class Response {

        /**
         * @var array
         */
        protected $_reason_phrases = array(
            //Informationsmeldungen 1xx
            100 => "Fortfahren",
            101 => "Protokolle wechseln",

            // Erfolgreich 2xx
            200 => "OK",
            201 => "Erstellt",
            202 => "Akzeptiert",
            203 => "Nicht autoritative Information",
            204 => "Kein Inhalt",
            205 => "Inhalt zurücksetzen",
            206 => "Teilinhalt",

            // Weiterleitung 3xx
            300 => "Mehrere Auswahlmöglichkeiten",
            301 => "Dauerhaft verschoben",
            302 => "Gefunden",
            303 => "Siehe andere",
            304 => "Nicht geändert",
            305 => "Proxy verwenden",
            306 => "(Ungenutzt)",
            307 => "Vorübergehende Umleitung",

            // Client-Fehler 4xx
            400 => "Ungültige Anfrage",
            401 => "Nicht autorisiert",
            402 => "Zahlung erforderlich",
            403 => "Verboten",
            404 => "Nicht gefunden",
            405 => "Methode nicht erlaubt",
            406 => "Nicht akzeptabel",
            407 => "Proxy-Authentifizierung erforderlich",
            408 => "Anfrage-Timeout",
            409 => "Konflikt",
            410 => "Verschwunden",
            411 => "Länge erforderlich",
            412 => "Vorbedingung fehlgeschlagen",
            413 => "Anfrageentität zu groß",
            414 => "Anfrage-URI zu lang",
            415 => "Nicht unterstützter Medientyp",
            416 => "Angeforderter Bereich nicht erfüllbar",
            417 => "Erwartung fehlgeschlagen",

            // Server-Fehler 5xx
            500 => "Interner Serverfehler",
            501 => "Nicht implementiert",
            502 => "Fehlerhaftes Gateway",
            503 => "Dienst nicht verfügbar",
            504 => "Gateway-Timeout",
            505 => "HTTP-Version nicht unterstützt"
        );

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

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

        /**
         * Konstruktor
         *
         * @param   string      $body
         */
        public function __construct($body) {

            $this->_body = $body;
        }

        /**
         * Konstruktor
         *
         * @param   string      $status_code
         */
        public function setStatusCode($status_code) {

            $this->_status_code = $status_code;
        }

        /**
         * Statuscode abrufen
         *
         * @return  integer
         */
        public function getStatusCode() {

            return $this->_status_code;
        }

        /**
         * Body abrufen
         *
         * @return  string
         */
        public function getBody() {

            return $this->_body;
        }

        /**
         * JSON-dekodierten Body abrufen
         *
         * @return  object|null
         */
        public function getBodyDecoded() {

            return json_decode($this->_body);
        }

        /**
         * Statusphrase abrufen
         *
         * @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;
            }
        }
    }

Anmelden

Es gibt zwei Möglichkeiten, die Anmeldung Route:

• mit Benutzername und Passwort
• mit API-Token (Access-Token)

Beispiel für die Anmeldung mit Benutzername- und Passwort-Parametern.

<?php

    // Request- und Response-Klassen einbinden

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

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

    // Ein neues Request-Objekt erstellen
    $request = new Request($url, 'POST', $params);

    // Die Anfrage senden
    $request->send();

    // Das Response-Objekt abrufen
    $response = $request->getResponse();

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

        // Die Details des Session-Tokens abrufen
        $token = $response->getBodyDecoded();

        print_r($token);
    }
    else {

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

Beispiel für die Anmeldung mit API-Token (Access-Token)

<?php

    // Request- und Response-Klassen einbinden

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

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

    // Ein neues Request-Objekt erstellen
    $request = new Request($url, 'POST', $params);

    // Die Anfrage senden
    $request->send();

    // Das Response-Objekt abrufen
    $response = $request->getResponse();

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

        // Die Details des Session-Tokens abrufen
        $token = $response->getBodyDecoded();

        print_r($token);
    }
    else {

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

Authentifizierung

Jede Anfrage an benutzerbezogene Inhalte erfordert einen Autorisierung Header, dessen Wert den Token-Typ und den von der API-Login-Anfrage erhaltenen Session-Token enthält.

Eine gültige /login Anfrage an die API liefert den folgenden JSON-Payload zurück.

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

Die Session-Token sollte in alle nachfolgenden Anfragen an die API zu benutzerbezogenen Inhalten aufgenommen werden.

Die type ist dem Token voranzustellen, getrennt durch ein einzelnes Leerzeichen.

Bearer 4e63518d383d8fcaefb516fe708b893727463031

Die expires_in ist die Zeit in Sekunden, für die das Token gültig ist. Wenn diese Zeit abläuft, muss über die /login-Anfrage ein neues Token angefordert werden.

Beispiel zum Abrufen und Setzen des Authorization-Headers mit Benutzername und Passwort

<?php

    // Request- und Response-Klassen einbinden

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

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

    // Ein neues Request-Objekt erstellen
    $request = new Request($url, 'POST', $params);

    // Die Anfrage senden
    $request->send();

    // Das Response-Objekt abrufen
    $response = $request->getResponse();

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

        // Die Details des Session-Tokens abrufen
        $token = $response->getBodyDecoded();

        // Kampagnen abrufen
        $url = 'https://api.example.com/v2/campaigns';

        // Ein neues Request-Objekt erstellen
        $request = new Request($url, 'GET');

        // Den Authorization-Header setzen
        $request->setAuthorizationHeader($token->type, $token->token);

        // Die Anfrage senden
        $request->send();

        // Das Response-Objekt abrufen
        $response = $request->getResponse();

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

            // Die Kampagnen abrufen
            $campaigns = $response->getBodyDecoded();

            foreach($campaigns->result as $campaign) {
                // Die Kampagnennamen anzeigen
                echo $campaign->name . PHP_EOL;
            }
        }
        else {
            // Fehler bei der Kampagnenanfrage
            echo $response->getStatusCode() . PHP_EOL;
            echo $response->getReasonPhrase() . PHP_EOL;
            echo $response->getBody();
        }
    }
    else {
        // Ungültige Anmeldung
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>

Beispiel zum Abrufen und Setzen des Authorization-Headers mit API-Token

<?php

    // Request- und Response-Klassen einbinden

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

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

    ...

?>

Sammlungen

Das Folgende ist ein Beispiel für eine Anfrage zum Abrufen der Browser Sammlung.

<?php

    // Request- und Response-Klassen einbinden

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

    // Ein neues Request-Objekt erstellen
    $request = new Request($url, 'GET');

    // Den aus der vorherigen Login-Anfrage abgerufenen Authorization-Header setzen
    $request->setAuthorizationHeader($token->type, $token->token);

    // Die Anfrage senden
    $request->send();

    // Das Response-Objekt abrufen
    $response = $request->getResponse();

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

        $browsers = $response->getBodyDecoded();

        foreach($browsers as $browser) {

            echo $browser->id . ': ' . $browser->name . PHP_EOL;
        }
    }
    else {
        // Sammlung nicht gefunden
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>

Statistiken

Das folgende ist ein Beispiel für eine Anfrage eines Werbetreibenden an statistics/a/date.

Falls additional_group_by der Wert definiert ist, wird die Anfrage nach dem Haupt-Routenfeld und den zusätzlichen Feld(en) gruppiert.

Beispiel für Statistiken pro Datum, gefiltert nach Kampagnen-ID 1234.

<?php

    // Request- und Response-Klassen einbinden

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

    // Die Kampagnen-ID angeben
    $params = array(
       'campaignid'  => 1234
    );

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

    // Den Authorization-Header festlegen, der aus der vorherigen Login-Anfrage abgerufen wurde
    $request->setAuthorizationHeader($token->type, $token->token);

    // Die Anfrage senden
    $request->send();

    // Das Response-Objekt abrufen
    $response = $request->getResponse();

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

        $statistics = $response->getBodyDecoded();

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

            echo $statistic->ddate . ': ' . $statistic->value . PHP_EOL;
        }
    }
    else {
        // Kampagnenstatistiken nicht gefunden
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>

Beispiel für Statistiken pro Datum mit zusätzlicher Gruppierung nach Kampagne.

<?php

    // Request- und Response-Klassen einbinden

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

    // Die Kampagnen-ID angeben
    $params = array(
       'additional_group_by'  => 'campaign'
    );

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

    // Den Authorization-Header festlegen, der aus der vorherigen Login-Anfrage abgerufen wurde
    $request->setAuthorizationHeader($token->type, $token->token);

    // Die Anfrage senden
    $request->send();

    // Das Response-Objekt abrufen
    $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 {
        // Kampagnenstatistiken nicht gefunden
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>

post /statistics/a/global

Globale Werbetreibenden-Statistiken abrufen

Beispiel 1 für globale Statistiken

Beispiel für eine Anfrage globaler Statistiken.

Nur der group_by Parameter ist obligatorisch. Die Standardwerte für die anderen Parameter finden Sie Hier.

Bitte beachten Sie, dass die Routen für globale Statistiken (statistics/a/global, statistics/p/global) ein anderes Parameterformat haben.

<?php

    // Request- und Response-Klassen einbinden

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

    // group_by angeben
    $params = [
        "group_by" => ["date"]
    ];

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

    // Den Authorization-Header festlegen, der aus der vorherigen Login-Anfrage abgerufen wurde
    $request->setAuthorizationHeader($token->type, $token->token);

    // Die Anfrage senden
    $request->send();

    // Das Response-Objekt abrufen
    $response = $request->getResponse();

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

        $statistics = $response->getBodyDecoded();

        foreach($statistics->result as $statistic) {
            echo 'Datum: ' . $statistic->group_by->date->date . ' -  Impressionen: ' . $statistic->impressions .' - Kosten: ' .  $statistic->cost . PHP_EOL;
        }
    }
    else {
        // Kampagnenstatistiken nicht gefunden
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>

Beispiel 2 für globale Statistiken

Statistiken pro Datum abrufen, einschließlich Gesamtsummen.

<?php

    // Request- und Response-Klassen einbinden

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

    // Die Kampagnen-ID angeben
    $params = [
        "filter" => [
            "date_from" => "2019-01-10",
            "date_to" => "2019-01-31",
        ],
        "totals" => 1,
        "group_by" => ["date"]
    ];

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

    // Den Authorization-Header festlegen, der aus der vorherigen Login-Anfrage abgerufen wurde
    $request->setAuthorizationHeader($token->type, $token->token);

    // Die Anfrage senden
    $request->send();

    // Das Response-Objekt abrufen
    $response = $request->getResponse();

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

        $statistics = $response->getBodyDecoded();

        foreach($statistics->result as $statistic) {
            echo 'Datum: ' . $statistic->group_by->date->date . ' -  Impressionen: ' . $statistic->impressions .' - Kosten: ' .  $statistic->cost . PHP_EOL;
        }

        echo 'Gesamtkosten:' . $statistics->result_total->cost . PHP_EOL;
    }
    else {
        // Kampagnenstatistiken nicht gefunden
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>

Beispiel 3 für globale Statistiken

Statistiken pro Kampagne und Land abrufen, gefiltert nach einem bestimmten Datum und nach Impressionen sortiert.

<?php

    // Request- und Response-Klassen einbinden

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

    // Den Authorization-Header festlegen, der aus der vorherigen Login-Anfrage abgerufen wurde
    $request->setAuthorizationHeader($token->type, $token->token);

    // Die Anfrage senden
    $request->send();

    // Das Response-Objekt abrufen
    $response = $request->getResponse();

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

        $statistics = $response->getBodyDecoded();

        foreach($statistics->result as $statistic) {
            echo 'Land: ' . $statistic->group_by->country_iso->country_iso . ' -  Kampagnen-ID: ' . $statistic->group_by->campaign_id->id .' - Kosten: ' .  $statistic->cost . PHP_EOL;
        }
    }
    else {
        // Kampagnenstatistiken nicht gefunden
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>

Beispiel 4 für globale Statistiken

Publisher-Statistiken pro Zone und Land abrufen, gefiltert nach einem bestimmten Betriebssystem.

<?php

    // Request- und Response-Klassen einbinden

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

    // Den Authorization-Header festlegen, der aus der vorherigen Login-Anfrage abgerufen wurde
    $request->setAuthorizationHeader($token->type, $token->token);

    // Die Anfrage senden
    $request->send();

    // Das Response-Objekt abrufen
    $response = $request->getResponse();

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

        $statistics = $response->getBodyDecoded();

        foreach($statistics->result as $statistic) {
            echo ' Zone ID:' . $statistic->group_by->zone_id->id . ' - Land: ' . $statistic->group_by->country_iso->country_iso .' - Umsatz: ' .  $statistic->revenue . PHP_EOL;
        }
    }
    else {
        // Kampagnenstatistiken nicht gefunden
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>