Налаштуйте SDK

PHP

З якими опціями збирається SDK, для чого кожна з них і яку єдину змінну середовища він читає.

3 хв читання

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

Зібрати SDK

PHP

use Psr\Log\AbstractLogger;
use Slen\Sdk\SlenConfig;
use Slen\Sdk\SlenSdk;

// Stands in for the PSR-3 logger of your application: this one prints what went wrong.
$logger = new class extends AbstractLogger {
    public function log($level, string|\Stringable $message, array $context = []): void
    {
        if ($level === 'warning' || $level === 'error') {
            echo $level, ' ', $message, PHP_EOL;
        }
    }
};

// SlenConfig reads no environment variable: the key is passed.
$slen = SlenSdk::create(new SlenConfig(
    apiKey: (string) getenv('SLEN_API_KEY'),
    timeout: 120.0,
    connectTimeout: 3.0,
    retries: 3,
    logger: $logger,
));

SlenConfig не читає змінних середовища: передайте ключ, як приклад читає його з SLEN_API_KEY. Порожній ключ, тайм-аут не більший за нуль, від’ємну кількість повторів і допуск вебхука менший за одну секунду він відхиляє з InvalidArgumentException там, де збирають SDK, а не на першому виклику. Збирання SDK не звертається до мережі. Ключ і секрет вебхука не видно ні в дампі конфігурації, ні в трасуванні стека. У застосунку на Laravel сервіс-провайдер збирає SDK із файлу конфігурації — Інтеграція з Laravel.

SDK із прикладу запускає флоу, як будь-який інший. Його логер друкує рядок, лише коли запит надсилається ще раз або не вдається.

PHP

use Slen\Sdk\Modules\Operations\Options\ExecuteOptions;

$execution = $slen->operations()->execute(
    'generate_email',
    ['messages' => [['role' => 'user', 'content' => 'Write a short follow-up email.']]],
    new ExecuteOptions(idempotencyKey: 'order-42:email'),
);

echo $execution->status->value, PHP_EOL;

Опції

Опція	Тип	За замовчуванням
`apiKey` обовʼязково	`string`	немає
`timeout`	`float`	`self::DEFAULT_TIMEOUT`
`connectTimeout`	`float`	`self::DEFAULT_CONNECT_TIMEOUT`
`retries`	`int`	`self::DEFAULT_RETRIES`
`logger`	`Psr\Log\LoggerInterface`	`new \Psr\Log\NullLogger(…)`
`spanRecorder`	`Slen\Sdk\Observability\SpanRecorderInterface`	`new \Slen\Sdk\Observability\NullSpanRecorder(…)`
`httpClient`	`?Psr\Http\Client\ClientInterface`	`null`
`requestFactory`	`?Psr\Http\Message\RequestFactoryInterface`	`null`
`streamFactory`	`?Psr\Http\Message\StreamFactoryInterface`	`null`
`webhookSecret`	`?string`	`null`
`webhookToleranceSeconds`	`int`	`self::DEFAULT_WEBHOOK_TOLERANCE_SECONDS`

Таблиця друкує значення за замовчуванням так, як його пише мова: час у Node.js — у мілісекундах, у PHP — у секундах.

Ключ — apiKey: API-ключ вашого проєкту, sl_live_…. Де його випустити, показує стаття Керування API-ключами.
Тайм-аути — timeoutMs у Node.js; timeout і connectTimeout у PHP. Вони обмежують одну спробу запиту — Повтори й тайм-аути.
Повтори — retries: скільки разів запит надсилається ще раз, коли відповіді не було, після 429 або 503. 0 вимикає повтори — Повтори й тайм-аути.
Журнал — logger: куди SDK пише те, що робить, — Журнал.
Спани — spanRecorder, а в Node.js ще й otlp — Спани.
Вебхуки — webhookSecret і webhookToleranceSeconds: секрет підпису вашого ендпоінта й те, наскільки старим може бути підпис, — Вебхуки.

Ще три параметри:

httpClient — клієнт PSR-18, через який ідуть запити. Він використовується як є, зі своїми тайм-аутами. Тест передає сюди дублер зі статті Тестування інтеграції.
requestFactory, streamFactory — фабрики PSR-17, якими створюються запити.

Без них SDK знаходить те, що встановлено у вашому застосунку. Коли він знаходить Guzzle або Symfony HttpClient, він збирає цей клієнт сам, із timeout і connectTimeout. Будь-який інший клієнт зберігає свої тайм-аути, і SDK пише у свій журнал slen.config.timeout_not_applied.

Виклик приймає те, що називає його предмет, — операцію та її вхід, id, суму, — а потім один об’єкт опцій: RequestOptions або опції цього виклику, наприклад ExecuteOptions запуску. В опціях виклику, який надсилає запит, є timeout і retries: вони замінюють значення конфігурації лише для цього виклику — Повтори й тайм-аути.

SlenConfig::withLogger(), SlenConfig::withSpanRecorder() і SlenConfig::withHttpClient() повертають копію конфігурації з однією зміною. Зібраний SDK не змінюється: SlenSdk::withLogger() повертає копію, яка пише журнал в інший логер, через той самий HTTP-клієнт, — Журнал.

Тести й локальний стек

SDK завжди звертається до публічного API Slen: адреса — константа SDK, і ніщо в цьому довіднику її не передає. Лише тест або локальний стек Slen спрямовує SDK на іншу адресу — опцією baseUrl: хост без /api — цей шлях SDK додає сам. У застосунку на Laravel такий тест задає значення конфігурації slen-sdk.base_url; у файлі конфігурації пакета такого ключа немає.

Що читати далі

Повтори й тайм-аути — що SDK надсилає ще раз сам і що обмежує кожен тайм-аут.
Журнал — що SDK пише у ваш логер.
Інтеграція з Laravel — SDK, зібраний із файлу конфігурації застосунку на Laravel.
Тестування інтеграції — SDK, який відповідає з тестового дублера, без мережі.

Зібрано з openapi b070e1f, sdk contract 6a2e0e0, php 4089db3, node 0fa87be