Jak používat etechblog.cz API s klienty PHP

V tomto návodu si ukážeme různé způsoby, jakými můžete v PHP přistupovat k API platformy etechblog.cz.

Konkrétně se zaměříme na využití etechblog.cz API prostřednictvím funkcí jako file_get_contents, knihovny Guzzle, HTTPful a HTTP klienta Symfony.

Co je etechblog.cz API?

etechblog.cz nabízí bezplatnou sadu nástrojů, které vám pomohou monitorovat výkon vašeho webu. Mezi tyto nástroje patří analyzátor nefunkčních odkazů, měření času načítání stránky a kontrola DNS. K těmto funkcím můžete přistupovat jak přes webové rozhraní, tak programově pomocí API.

API je založeno na HTTP protokolu a je dostupné z jakéhokoli programovacího jazyka, který má k dispozici HTTP klientskou knihovnu. API nabízí velkorysý bezplatný plán, takže s ním můžete začít pracovat, aniž byste museli zadávat platební informace.

Co budeme vytvářet

Napíšeme skript, který spustíme z příkazové řádky. Tento skript změří, jak dlouho trvá načtení webové stránky Google, a výsledek vypíše do terminálu. Tento program implementujeme pomocí různých HTTP klientů pro PHP, abychom demonstrovali, jak se API používá.

Konkrétně použijeme vestavěné funkce file_get_contents() a php_curl, a také knihovnu Guzzle. Přestože se tyto příklady mohou zdát jednoduché, demonstrují základní koncepty práce s etechblog.cz API.

Předpoklady

Předtím, než budete pokračovat, musíte mít základní znalosti PHP a mít jej nainstalovaný ve vašem počítači. Pro správu rozšíření budete potřebovat také Composer.

A konečně, budete potřebovat textový editor pro psaní kódu. V tomto případě budeme používat Visual Studio Code, což je populární open-source editor od Microsoftu. Můžete si ho stáhnout ze stránek Visual Studio Code.

Přehled etechblog.cz API

etechblog.cz API má různé koncové body v závislosti na tom, co chcete s ním dělat. Kompletní seznam koncových bodů a související dokumentaci najdete na stránce s dokumentací.

Vytvoření účtu etechblog.cz

Pro začátek práce s API si musíte vytvořit účet na vstupní stránce API, kde kliknete na tlačítko registrace. Po úspěšné registraci budete přesměrováni na řídicí panel, kde najdete svůj API klíč. Řídicí panel by měl vypadat podobně jako na obrázku níže. Z bezpečnostních důvodů je můj API klíč zakrytý.

Tento klíč budete muset uvádět v hlavičce každého API požadavku. Brzy si ukážeme, jak na to.

Po vytvoření účtu etechblog.cz a instalaci PHP můžeme začít pracovat na projektu.

Vytvoření složky projektu

Nejprve si vytvořte složku, kam budeme ukládat soubory projektu. Následně vytvořte tyto soubory:

• .env
• with_curl.php
• with_file_get_contents.php
• with_guzzle.php

Potom spusťte následující příkaz pro instalaci rozšíření vlucas/phpdotenv a guzzlehttp/guzzle:

composer require vlucas/phpdotenv guzzlehttp/guzzle

V tuto chvíli by vaše projektová složka měla vypadat takto:

Nyní otevřete soubor .env a přidejte následující řádek, nahrad’te <your-api-key> vaším skutečným API klíčem z řídicího panelu etechblog.cz:

API_KEY=<your-api-key>

Použití file_get_contents()

První metoda, kterou použijeme pro vytváření HTTP požadavků, je funkce file_get_contents(), která je součástí PHP. Podpis funkce file_get_contents() je následující:

file_get_contents(path, include_path, context)

Přestože se tato funkce často používá pro čtení obsahu souborů z místního úložiště, můžeme ji použít i ke čtení webových zdrojů, jako jsou data vrácená API endpointem.

Pro začátek otevřete soubor with_file_get_contents.php a přidejte základní PHP kód:

<?php
        // veškerý kód bude vložen sem
    ?>

Dále můžeme začít s načítáním rozšíření. Do souboru přidejte následující řádek kódu:

require_once('vendor/autoload.php');

Následně načteme naše proměnné prostředí, mezi které patří i API klíč:

$dotenv = DotenvDotenv::createImmutable(__DIR__);
    $dotenv->load();

Poté definujeme užitečné zatížení. To budou data, která budeme odesílat jako součást těla požadavku:

$payload = json_encode([
        "url" => "https://www.google.com", 
        "proxyCountry" => "us",
        "followRedirect" => true
    ]);

Vytvořili jsme proměnnou $payload a přiřadili jsme jí JSON string, který obsahuje vlastnosti url, proxyCountry a followRedirect.

Vlastnost url určuje webovou stránku, jejíž dobu načítání chceme měřit.

proxyCountry určuje lokaci serveru, který chceme použít k odeslání požadavku. V tomto případě používáme server v USA, ale můžete si vybrat také z Indie, Číny, Velké Británie a Francie. Více informací naleznete v dokumentaci.

Vlastnost followRedirect určuje, zda má proxy server sledovat případná přesměrování a měřit čas odezvy finální odpovědi nebo prvního přesměrování.

Nyní můžeme vytvořit nastavení, které bude konfigurovat náš požadavek. Přidejte následující kód:

$options = [
        "http" => [
            "method" => "POST",
            "header" => array("Content-Type: application/json", "x-api-key : " . $_ENV['API_KEY']),
            "content" => $payload
        ] 
    ];

Vytvořili jsme objekt $options, který definuje metodu HTTP jako POST. V hlavičce jsou nastaveny dvě vlastnosti: typ obsahu Content-Type jako JSON a x-api-key, který je načten jako proměnná prostředí z .env souboru.

Nyní můžeme požadavek provést tak, že vytvoříme stream, do kterého budou zapsány naše nastavení:

$context = stream_context_create($options);

Dále zavoláme funkci file_get_contents(), abychom provedli požadavek a uložili odpověď do proměnné:

$response = file_get_contents("https://api.etechblog.cz.com/loadtime", false, $context);

Odeslali jsme požadavek na https://api.etechblog.cz.com/loadtime. Hodnota false říká PHP, aby nepoužívalo cestu a my předáme metodě námi vytvořený $context.

Pro zobrazení odezvy použijeme následující:

echo "Loadtime: " . json_decode($response)->data->total . "n";

Váš finální soubor by měl vypadat takto:

<?php
        require_once('vendor/autoload.php');
    
        $dotenv = DotenvDotenv::createImmutable(__DIR__);
        $dotenv->load();
    
        $payload = json_encode([
            "url" => "https://www.google.com", 
            "proxyCountry" => "us",
            "followRedirect" => true
        ]);
    
        $options = [
            "http" => [
                "method" => "POST",
                "header" => array("Content-Type: application/json", "x-api-key : " . $_ENV['API_KEY']),
                "content" => $payload
            ] 
        ];
    
        $context = stream_context_create($options);
    
        $response = file_get_contents("https://api.etechblog.cz.com/loadtime", false, $context);
    
        echo "Loadtime: " . json_decode($response)->data->total . "n";
    ?>

Když soubor spustíte pomocí následujícího příkazu:

php with_file_get_contents.php

Obdržíte tento výstup:

Loadtime: 81

Použití cURL

cURL je nástroj pro příkazovou řádku, který se používá pro vytváření klientských požadavků na URL. V PHP ho lze použít pomocí rozšíření php-curl. Pro začátek otevřete soubor with_curl.php a vložte základní PHP:

<?php
        // veškerý nový kód bude napsán sem
    ?>

Poté importujeme rozšíření a načteme proměnnou prostředí API_KEY definovanou v souboru .env:

require_once('vendor/autoload.php');
    
    $dotenv = DotenvDotenv::createImmutable(__DIR__);
    $dotenv->load();

Dále vytvoříme proměnnou pro uložení hlaviček našeho objektu jako pole, kde každý prvek je konkrétní hlavička:

$header = ["Content-type: application/json", "x-api-key: " . $_ENV['API_KEY']];

Definovali jsme dvě hlavičky: jednu pro typ obsahu a druhou pro API klíč.

Poté můžeme definovat tělo požadavku:

$body = json_encode([
        "url" => "google.com",
        "proxyCountry" => "us",
        "followRedirect" => true
    ]);

Nyní můžeme vytvořit curl relaci pomocí funkce curl_init(). Jako argument předáme URL, na kterou chceme odeslat požadavek:

$ch = curl_init("https://api.etechblog.cz.com/loadtime");

Vše můžeme dát dohromady definováním hlaviček a těla jako možností pro relaci. K tomu použijeme funkci curl_setopt_array():

curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST => "POST",
        CURLOPT_HTTPHEADER => $header,
        CURLOPT_POSTFIELDS => $body
    ]);

Pro odeslání požadavku zavoláme funkci curl_exec():

$response = curl_exec($ch);

Odpověď jsme uložili do proměnné $response. Nyní můžeme relaci zavřít, abychom uvolnili systémové prostředky:

curl_close($ch);

Nakonec můžeme odpověď vytisknout na obrazovku pomocí var_dump:

var_dump($response);

Váš finální skript by měl vypadat takto:

<?php
        require_once('vendor/autoload.php');
    
        $dotenv = DotenvDotenv::createImmutable(__DIR__);
        $dotenv->load();
    
        $header = ["Content-type: application/json", "x-api-key: " . $_ENV['API_KEY']];
    
        $body = json_encode([
            "url" => "google.com",
            "proxyCountry" => "us",
            "followRedirect" => true
        ]);
    
        $ch = curl_init("https://api.etechblog.cz.com/loadtime");
    
        curl_setopt_array($ch, [
            CURLOPT_CUSTOMREQUEST => "POST",
            CURLOPT_HTTPHEADER => $header,
            CURLOPT_POSTFIELDS => $body
        ]);
    
        $response = curl_exec($ch);
    
        curl_close($ch);
    
        var_dump($response);
    ?>

Když skript spustíme pomocí php with_curl.php, měli byste obdržet tento výstup:

{"timestamp":1666083632547,"apiStatus":"success","apiCode":200,"meta":{"url":"google.com","followRedirect":true,"redirectedURL":"https://www.google.com/?gws_rd=ssl","test":{"id":"d20h1hb409qbfwm0g534l51asugpi5hl"}},"data":{"dns":12,"connect":17,"tls":6,"send":21,"wait":110,"total":114}}bool(true)

Požadavek byl úspěšně dokončen a API odpovědělo daty v JSON formátu. Tyto data můžete použít dle potřeby.

Použití Guzzle

V poslední části tohoto návodu použijeme Guzzle pro napsání skriptu. Jako vždy začneme vložením základního PHP kódu do souboru with_guzzle.php:

<?php
        // veškerý kód bude vložen sem
    ?>

Poté můžeme importovat rozšíření, Guzzle Client a Request Objects a načíst proměnné prostředí:

require_once('vendor/autoload.php');
    
    use GuzzleHttpClient;
    use GuzzleHttpPsr7Request;

Následně můžeme načíst proměnné prostředí:

$dotenv = DotenvDotenv::createImmutable(__DIR__);
    $dotenv->load();

Nyní můžeme vytvořit instanci Guzzle HTTP klienta:

$client = new GuzzleHttpClient();

Poté vytvoříme hlavičky pro náš požadavek:

$headers = [
        'x-api-key' => $_ENV['API_KEY'],
        'Content-Type' => 'application/json'
    ];

Dále definujeme tělo požadavku:

$body = json_encode([
        "url" => "google.com",
        "proxyCountry" => "us",
        "followRedirect" => true
    ]);

Nyní můžeme provést požadavek vytvořením instance třídy Request a předáním URL, hlaviček a těla:

$request = new Request('POST', 'https://api.etechblog.cz.com/loadtime', $headers, $body);

Pro odeslání požadavku použijeme tento řádek kódu:

$response = $client->sendAsync($request)->wait();

Po odeslání požadavku můžeme získat tělo odpovědi takto:

$response_body = $response->getBody();

Nakonec můžeme dekódovat JSON odpověď a vytisknout dobu načítání:

echo "Loadtime: " . json_decode($response_body)->data->total . "n";

Váš finální soubor by tedy měl vypadat takto:

<?php
        require_once('vendor/autoload.php');
    
        use GuzzleHttpClient;
        use GuzzleHttpPsr7Request;
    
        $dotenv = DotenvDotenv::createImmutable(__DIR__);
        $dotenv->load();
        
    
        $client = new GuzzleHttpClient();
    
        $headers = [
            'x-api-key' => $_ENV['API_KEY'],
            'Content-Type' => 'application/json'
        ];
    
        $body = json_encode([
            "url" => "google.com",
            "proxyCountry" => "us",
            "followRedirect" => true
        ]);
    
        $request = new Request('POST', 'https://api.etechblog.cz.com/loadtime', $headers, $body);
    
        $response = $client->sendAsync($request)->wait();
    
        $response_body = $response->getBody();
    
        echo "Loadtime: " . json_decode($response_body)->data->total . "n";
    ?>

A když skript spustíte pomocí příkazu:

$php with_guzzle.php

Zobrazí se následující odpověď:

Loadtime: 130

Závěr

V tomto článku jsme si ukázali různé klienty, které můžete použít při vytváření PHP projektů, které vyžadují interakci s etechblog.cz API.

Zatímco skripty v tomto projektu používají příkazovou řádku jako hlavní formu výstupu, reálné projekty by mohly zobrazovat odpovědi na webové stránce nebo je ukládat do souboru. Ukázkové skripty v tomto článku byly jednoduché, ale demonstrovaly základní koncepty práce s etechblog.cz API. Pro použití s jinými API endpointy můžete změnit URL a předávat různé parametry v těle požadavku.

Možná vás také bude zajímat, jak používat etechblog.cz DNS Lookup API v JavaScriptu.