Як використовувати API techukraine.net із клієнтами PHP

Автор

Огляд різних PHP-клієнтів для взаємодії з techukraine.net API

У цій інструкції ми детально розглянемо декілька варіантів PHP-клієнтів, за допомогою яких ви можете налагодити зв’язок із techukraine.net API.

Зокрема, ми зосередимося на тому, як використовувати techukraine.net API, застосовуючи функції file_get_contents, бібліотеки Guzzle та HTTPful, а також Symfony HTTP-клієнт.

Що собою являє techukraine.net API?

techukraine.net пропонує користувачам набір безкоштовних інструментів, призначених для відстеження продуктивності веб-сайтів. Серед них – аналізатор непрацюючих посилань, інструмент вимірювання швидкості завантаження та перевірка DNS. Доступ до цих інструментів надається як через веб-інтерфейс, так і через API.

API працює на протоколі HTTP і доступний для використання з будь-якої мови програмування, що має HTTP-клієнтську бібліотеку. Важливо відзначити, що API надає щедрий безкоштовний тарифний план, що дозволяє розпочати роботу без надання платіжної інформації.

Цілі нашого проекту

Наша мета – створити скрипт, який можна запустити з командного рядка. Він буде визначати час, потрібний для завантаження веб-сайту Google, та виводити отримані дані на термінал. Для реалізації цієї простої програми ми використаємо різні PHP HTTP-клієнти, демонструючи різноманітність підходів до роботи з API.

Ми будемо використовувати як вбудовані функції, такі як file_get_contents() та php_curl, так і сторонні розширення, зокрема Guzzle PHP. Хоч ці приклади можуть здаватися простими, вони дозволяють чітко зрозуміти основні принципи взаємодії з techukraine.net API.

Необхідні умови

Для успішної роботи з матеріалом вам знадобиться базове розуміння PHP та встановлене середовище PHP на вашому комп’ютері. Також вам буде потрібен Composer для управління встановленням необхідних розширень.

Окрім цього, необхідний текстовий редактор для написання коду. У цьому посібнику я буду використовувати Visual Studio Code – популярний редактор із відкритим кодом від Microsoft. Ви можете завантажити його з офіційного веб-сайту Visual Studio Code.

Огляд techukraine.net API

techukraine.net API має кілька різних кінцевих точок, залежно від того, яку саме функцію ви хочете використовувати. Детальний список усіх кінцевих точок та відповідну документацію можна знайти на сторінці документації API.

Створення облікового запису techukraine.net

Щоб розпочати роботу з API, необхідно створити обліковий запис, перейшовши на відповідну сторінку API та натиснувши кнопку реєстрації. Після успішної реєстрації ви потрапите на панель управління, де буде відображено ваш API-ключ. Панель управління повинна мати вигляд, як на малюнку нижче. З міркувань безпеки, мій API-ключ приховано.

У кожному API-запиті вам потрібно буде вказувати цей ключ у заголовку запиту. Ми розглянемо, як це зробити, трохи згодом.

Після створення облікового запису techukraine.net та встановлення PHP, ми можемо приступити до підготовки нашого проекту.

Створення папки проекту

Насамперед створіть нову папку, в якій будуть розміщуватись файли вашого проекту. Далі створіть такі файли:

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

Після цього скористайтеся наведеною нижче командою, щоб встановити розширення vlucas/phpdotenv і guzzlehttp/guzzle:

composer require vlucas/phpdotenv guzzlehttp/guzzle

На даному етапі структура папки вашого проекту має виглядати наступним чином:

Тепер відкрийте файл .env та додайте наступний рядок коду, замінивши <your-api-key> на ваш власний API-ключ з панелі управління techukraine.net:

API_KEY=<your-api-key>

Використання функції file_get_contents()

Перший метод, який ми можемо використати для виконання HTTP-запитів, це виклик функції file_get_contents(), яка вбудована в PHP. Сигнатура цієї функції має такий вигляд:

file_get_contents(path, include_path, context)

Хоча цей метод зазвичай використовується для читання вмісту файлів на локальному диску, ми можемо використовувати його і для зчитування веб-ресурсів, таких як дані, що повертаються кінцевою точкою API.

Для початку відкрийте файл with_file_get_contents.php і додайте туди шаблонний код PHP:

<?php
   // Код буде вставлено тут
?>

Далі, почнемо із завантаження розширень. Додайте до свого файлу наступний рядок коду:

require_once('vendor/autoload.php');

Тепер завантажимо наші змінні середовища, зокрема наш API-ключ:

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

Далі визначимо корисне навантаження – дані, які ми будемо відправляти в тілі запиту:

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

Тут ми створили змінну $payload, якій присвоїли JSON-рядок з властивостями url, proxyCountry та followRedirect.

Властивість url визначає веб-сторінку, час завантаження якої ми хочемо виміряти.

proxyCountry визначає розташування сервера, який буде використовуватися для відправлення запиту. В цьому випадку ми використовуємо сервер у США, але ви можете обрати сервер у Індії, Китаї, Великобританії або Франції. Детальніше про це можна прочитати в документації.

followRedirect визначає, чи повинен проксі-сервер обробляти перенаправлення та вимірювати час відповіді кінцевого ресурсу, або ж першого перенаправлення.

Далі створимо масив параметрів, який налаштує наш запит. Додайте наступний код:

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

Таким чином, ми створили об’єкт $options, який визначає, що наш HTTP-метод – це POST, і в заголовку ми вказуємо тип вмісту як JSON, а також передаємо наш API-ключ, завантажений зі змінних середовища.

Далі ми можемо зробити запит, створивши потік, в який будуть записані наші параметри:

$context = stream_context_create($options);

Тепер викличемо метод file_get_contents(), щоб відправити запит та зберегти відповідь у змінній:

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

Ми відправили запит на https://api.techukraine.net.com/loadtime. Другий аргумент вказує PHP не використовувати шляхи. І передаємо створений нами контекст методу.

Для відображення відповіді скористаємося наступним кодом:

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

В результаті ваш файл має виглядати так:

<?php
    require_once('vendor/autoload.php');

    $dotenv = Dotenv\Dotenv::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.techukraine.net.com/loadtime", false, $context);

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

Запустивши цей файл за допомогою команди:

php with_file_get_contents.php

Ви отримаєте такий результат:

Loadtime: 81

Використання cURL

cURL – це утиліта командного рядка, що використовується для виконання запитів до URL-адрес на стороні клієнта. У PHP її можливо використовувати за допомогою бібліотеки php-curl. Для початку відкрийте файл with_curl.php та додайте шаблонний PHP-код:

<?php
    // Весь новий код буде записано тут
?>

Тепер імпортуємо розширення та завантажимо змінну середовища API_KEY, що визначена у файлі .env:

require_once('vendor/autoload.php');

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

Далі створимо масив, в якому будемо зберігати заголовки нашого запиту, де кожен елемент масиву – це окремий заголовок.

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

Тут ми визначили два заголовки: один для типу вмісту, а інший – для API-ключа.

Потім визначимо тіло запиту:

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

Після цього можна створити сеанс curl за допомогою функції curl_init(). URL-адресу, до якої ми хочемо відправити запит, передамо як аргумент цієї функції.

$ch = curl_init("https://api.techukraine.net.com/loadtime");

Тепер з’єднаємо все разом, вказавши заголовок та тіло запиту як параметри сеансу. Для цього ми будемо використовувати функцію curl_setopt_array().

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

Для відправлення запиту ми викличемо функцію curl_exec().

$response = curl_exec($ch);

Ми зберегли відповідь у змінній $response, тому тепер можемо закрити сеанс, щоб звільнити системні ресурси, що використовуються сеансом.

curl_close($ch);

Наостанок, можемо вивести відповідь на екран за допомогою var_dump().

var_dump($response);

Отже, в кінцевому вигляді ваш скриптовий файл повинен виглядати так:

<?php
    require_once('vendor/autoload.php');

    $dotenv = Dotenv\Dotenv::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.techukraine.net.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);
?>

Коли ми запустимо цей скрипт за допомогою php with_curl.php, ви повинні отримати такий результат:

{"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)

Запит був успішним, і API повернув дані у форматі JSON. Ви можете обробляти ці дані на свій розсуд.

З використанням Guzzle

Наостанок ми розглянемо використання Guzzle для створення скрипта. Зазвичай, почнемо з того, що вставимо шаблонний PHP-код у файл with_guzzle.php:

<?php
    // Весь код буде тут
?>

Далі ми імпортуємо необхідні розширення та об’єкти Guzzle Client та Request і завантажимо змінні середовища:

require_once('vendor/autoload.php');

use GuzzleHttp\Client;
use GuzzleHttp\Psr7\Request;

Тепер завантажимо змінні середовища:

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

Далі створимо екземпляр HTTP-клієнта Guzzle:

$client = new Client();

Тепер створимо масив заголовків для нашого запиту:

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

Потім визначимо тіло запиту:

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

Після цього ми можемо зробити запит, створивши екземпляр класу Request та передавши URL кінцевої точки API, заголовок та тіло запиту.

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

Тепер можемо відправити запит, додавши наступний код:

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

Після відправки запиту, ми можемо отримати його тіло таким чином:

$response_body = $response->getBody();

Нарешті, ми можемо декодувати JSON-відповідь та вивести час завантаження:

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

В результаті наш файл має виглядати так:

<?php
    require_once('vendor/autoload.php');

    use GuzzleHttp\Client;
    use GuzzleHttp\Psr7\Request;

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

    $client = new Client();

    $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.techukraine.net.com/loadtime', $headers, $body);

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

    $response_body = $response->getBody();

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

Після запуску скрипта командою:

$php with_guzzle.php

Ви побачите таку відповідь:

Loadtime: 130

Висновок

В цій статті ми розглянули різні клієнтські підходи, які можна використовувати при створенні PHP-проекту, що взаємодіє з techukraine.net API.

Хоча в нашому проекті скрипти використовують командний рядок для виводу, в реальних проектах відповідь може бути представлена на веб-сторінці або записана у файл. Приклади скриптів у статті були простими, але вони ілюструють ключові принципи використання techukraine.net API. Для використання інших API-ендпоінтів ви можете змінювати URL та передавати різні параметри у тілі запиту.

Можливо, вас також зацікавить стаття про використання techukraine.net DNS Lookup API у Javascript.