Управление прокси

Объект PK предоставляет четыре метода управления прокси. setProxy назначает указанную запись, deleteProxy исключает текущую запись из списка, freezeProxy временно запрещает её повторный выбор, а nextProxy отдельно выбирает следующую доступную запись.

Что выбрать

Когда изменение начинает действовать

Методы работают с прокси текущего выполнения проекта. Назначение или переключение меняет маршрут для следующего сетевого запроса; уже отправленный запрос продолжает выполняться с прежними параметрами. После успешной смены новое чтение PK.ip, PK.port, PK.proxyType и остальных свойств прокси показывает новую текущую запись.

Назначить указанную прокси

PK.setProxy(proxy, type)

Добавляет указанную запись в список проекта, делает её текущей и применяет к соединению для следующих запросов. Метод использует тот же механизм, что и функция USEPROXY в in-Line Kit.

PK.setProxy("127.0.0.1:8080", "HTTP");

Подробное поведение общего механизма приведено в справке по USEPROXY.

Допустимые адреса и типы

Параметр proxy принимает одну из трёх форм:

IP:PORT
IP:PORT:LOGIN:PASSWORD
LOGIN:PASSWORD@IP:PORT

Параметр type принимает ровно одно из четырёх значений без учёта регистра:

HTTP
HTTPS
SOCKS4
SOCKS5

HTTP и HTTPS приводятся исполнителем к одному внутреннему виду прокси HTTP. Не передавайте пустой адрес, неизвестный тип или строку иной формы: метод завершится явной ошибкой, а сценарий не должен продолжать работу так, будто прокси назначена.

Пример с учётными данными:

PK.setProxy(
  "keeper-user:[email protected]:1080",
  "SOCKS5"
);

Исключить текущую прокси

PK.deleteProxy()

Удаляет исходную запись текущей прокси из загруженного списка, чтобы список больше не выбирал её в текущем запуске. Назначенная текущая запись при этом не очищается и не заменяется автоматически.

PK.deleteProxy();

Если текущей прокси нет, метод ничего не меняет и не сообщает об этом отдельным результатом. Отсутствие ошибки не доказывает, что запись существовала или была удалена. Точное соответствие функции in-Line Kit описано в справке по DELPROXY.

Временно заблокировать текущую прокси

PK.freezeProxy(seconds)

Запрещает повторный выбор происхождения текущей прокси на указанное число секунд. Текущий адрес и соединение не меняются, поэтому для продолжения через другую запись нужен отдельный вызов PK.nextProxy().

PK.freezeProxy(180);

Исполнитель оставляет в аргументе только цифры: например, -180 фактически превращается в 180, а значение без цифр приводит к тихому пропуску действия. Не полагайтесь на это исправление. Проверьте число до вызова и передайте положительное целое значение:

const freezeSeconds = 180;

if (!Number.isInteger(freezeSeconds) || freezeSeconds <= 0) {
  throw new Error("Время блокировки должно быть положительным целым числом");
}

PK.freezeProxy(freezeSeconds);

Если текущей прокси нет, метод ничего не блокирует. Полезного результата у него нет, поэтому сам вызов нельзя использовать как подтверждение выполненной блокировки. Поведение исходной функции разобрано в справке по FREEZEPROXY.

Выбрать следующую прокси

PK.nextProxy()

Просит список выбрать следующую доступную запись, делает её текущей, очищает сведения о прежнем соединении и применяет новый маршрут.

const selectedProxy = PK.nextProxy();

if (selectedProxy === "") {
  throw new Error("Не удалось выбрать следующую прокси");
}

Не разбирайте selectedProxy по двоеточиям ради адреса, порта или пароля: форма зависит от записи и наличия учётных данных. После успешного выбора читайте нужные части через PK.ip, PK.port, PK.proxyType, PK.proxyLogin и PK.proxyPassword. Полный договор исходной функции приведён в справке по NEXTPROXY.

Что происходит с соединением

При назначении или выборе исполнитель сравнивает адрес, порт, тип и учётные данные с уже применённым маршрутом. Если хотя бы одна часть изменилась, прежнее постоянное соединение закрывается до записи новых параметров. Следующий запрос поэтому не продолжает старое соединение через другую прокси.

Безопасные последовательности

Исключение и выбор — две разные операции. Сначала измените доступность текущей записи, затем явно выберите следующую и проверьте строковый результат до нового сетевого запроса.

Заблокировать на время и продолжить

const freezeSeconds = 180;

if (!Number.isInteger(freezeSeconds) || freezeSeconds <= 0) {
  throw new Error("Время блокировки должно быть положительным целым числом");
}

PK.freezeProxy(freezeSeconds);

const selectedProxy = PK.nextProxy();
if (selectedProxy === "") {
  throw new Error("После блокировки не осталось доступной прокси");
}

const selectedHost = PK.ip;
const selectedPort = PK.port;

Здесь проверяется именно результат nextProxy, потому что freezeProxy ничего полезного не возвращает. Новый сетевой запрос можно выполнять только после непустого результата переключения.

Удалить до конца запуска и продолжить

PK.deleteProxy();

const selectedProxy = PK.nextProxy();
if (selectedProxy === "") {
  throw new Error("После удаления не осталось доступной прокси");
}

const selectedType = PK.proxyType;

Эта последовательность подходит для записи, которую нельзя снова использовать в текущем запуске. Если запрет должен закончиться через некоторое время, применяйте freezeProxy, а не deleteProxy.

Проверить текущую запись

Свойства прокси являются живыми: каждое чтение получает текущее состояние проекта, а не снимок на момент начала сценария. Поэтому читайте их после setProxy или успешного nextProxy.

PK.setProxy("127.0.0.1:1080", "SOCKS5");

const route = {
  host: PK.ip,
  port: PK.port,
  type: PK.proxyType,
};

Назначение всех семи свойств и правила работы с паролем собраны в справке по свойствам PK.