Конфигурация
Каждый параметр клиента, что он читает из окружения и что отклоняет.
Опции
client := openemail.New( openemail.WithAPIKey(os.Getenv("OPENEMAIL_API_KEY")), openemail.WithBaseURL("https://api.openemail.uk"), openemail.WithTimeout(30*time.Second), openemail.WithMaxRetries(2), openemail.WithHeader("X-Team", "billing"),) if err := client.Err(); err != nil { return err} fmt.Println(client.Mode(), client.BaseURL())| Опция | Что делает |
|---|---|
| WithAPIKey | API-ключ рабочего пространства, начинающийся с oe_live_ или oe_test_. В вызове он действует с другим ключом только для этого вызова. |
| WithAccessToken | Токен доступа OAuth для приложения, которое подключил человек. Передайте ключ или токен, но не оба. |
| WithAccessTokenFunc | Функция, возвращающая токен доступа. Она выполняется перед каждым запросом, поэтому именно здесь стоит обновлять токен. |
| WithBaseURL | Источник API. К голому хосту, такому как localhost:2222, добавляется схема. |
| WithHTTPClient | *http.Client или что угодно с таким же методом Do. Тест передаёт сюда подделку. |
| WithTimeout | Сколько может длиться одна попытка. По умолчанию 30 секунд, ноль отключает ограничение, а загрузки ждут не менее десяти минут. |
| WithMaxRetries | Сколько раз повторяется неудавшийся запрос. По умолчанию 2, а 0 отправляет один раз. |
| WithUserAgent | Заменяет заголовок User-Agent, который состоит из openemail-go/ и версии. |
| WithHeader | Добавляет заголовок к каждому запросу. |
Всё, что вы не указали, читается из окружения: OPENEMAIL_API_KEY, затем OPENEMAIL_ACCESS_TOKEN и OPENEMAIL_BASE_URL. client.Mode() сообщает, является ли ключ ключом live или test.
Контекст и таймауты
Каждый метод первым принимает context.Context. Его отмена сразу останавливает вызов, а его крайний срок ограничивает весь вызов вместе с повторами, тогда как WithTimeout ограничивает каждую попытку. WithTimeout работает и для отдельного вызова.
ctx, cancel := context.WithTimeout(ctx, 10*time.Second)defer cancel() thread, err := client.Threads.Get(ctx, "CAHk7pQ2x9LmZ4-mail.example.com", openemail.WithTimeout(5*time.Second))if err != nil { return err} fmt.Println(thread.Int("messageCount"))Параметры вызова
Параметры запроса и настройки вызова представляют собой функции, передаваемые после аргументов, например openemail.WithLimit, openemail.WithCursor и openemail.WithIdempotencyKey. Каждый метод принимает параметры, перечисленные в его записи в справочнике, а параметр, который к нему не относится, отклоняется до отправки чего-либо.
page, err := client.Emails.List(ctx, openemail.WithStatus("failed", "bounced"), openemail.WithLimit(50), openemail.WithAPIKey(os.Getenv("OTHER_WORKSPACE_KEY")),)if err != nil { return err} fmt.Println(len(page.Items), page.HasMore)Что клиент отклоняет
- Ключ, который не начинается с
oe_live_илиoe_test_, и ключ вместе с токеном доступа. - Отправку учётных данных по обычному
http:, если только сервер не находится на этой машине по адресуlocalhost,127.x.x.xили::1. - Базовый URL на
0.0.0.0, то есть на адресе, который сервер слушает. Используйте127.0.0.1с тем же портом. - Пустой идентификатор или состоящий только из точек, который парсер URL удалил бы.
- Переход по перенаправлению. HTTP-клиент по умолчанию возвращает его как ошибку, поэтому учётные данные никогда не уходят на другой хост.
Вывод клиента, параметра или ошибки никогда не показывает учётные данные. Ключ, токен и значения пользовательских заголовков не попадают в вывод fmt, log/slog и encoding/json.
Конечная точка без метода
client.Request вызывает любой путь с учётными данными, базовым URL, таймаутом и правилами повторов клиента. Путь должен начинаться с одного /, а путь, покидающий источник базового URL, отклоняется.
label, err := client.Request(ctx, http.MethodPost, "/labels", openemail.Body{"name": "Invoices"})if err != nil { return err} fmt.Println(label)