Свойства объекта PK

Все 20 свойств PK: типы, доступ, источники значений, моменты обновления и примеры.

Объект PK содержит 20 публичных свойств. Девятнадцать доступны только для чтения; изменять можно только PK.conclusion. Каждое свойство ниже описано одним и тем же способом: точный тип, доступ, владелец значения, момент обновления и рабочий пример.

Как читаются свойства

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

Значение читается сейчас

const before = PK.response сохраняет строку в before. Последующее изменение ответа не меняет эту переменную, но новое обращение PK.response уже прочитает обновлённое значение.

Только одно свойство изменяемое

Запись поддержана только для PK.conclusion. Присваивание остальным свойствам не меняет состояние Private Keeper и не должно использоваться как способ настройки запроса.

Момент сценария имеет значение

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

Не выводите секреты в журнал

PK.pwd, PK.proxyPassword и PK.proxyURI могут содержать пароль. Читайте их только для необходимой операции и не передавайте в console.log, текст ошибки, статистику или сторонний запрос.

Входные значения

PK.login и PK.pwd — условные названия первого и второго входных значений. Проект может хранить в них не учётные данные, а любые две строки; смысл определяет маска входа проекта.

Тип и доступ

string, только чтение.

Источник и обновление

Первое значение текущей входной строки. Private Keeper устанавливает его перед запуском проекта для этой строки; действия и сценарии текущего запуска его не меняют.

const accountName = PK.login;

`PK.pwd`

Тип и доступ

string, только чтение.

Источник и обновление

Второе значение текущей входной строки. Оно устанавливается вместе с PK.login перед запуском проекта и остаётся исходным значением до конца обработки строки.

const accountPassword = PK.pwd;

Текущий прокси

Семь свойств читают одну текущую запись прокси. Когда проект или метод объекта PK выбирает другую запись, все семь свойств начинают отражать её при следующем чтении. Если в текущей записи нет отдельной части, соответствующее строковое свойство пусто.

Управление выбором, удалением и заморозкой разобрано в справке по операциям с прокси.

`PK.ip`

Тип и доступ

string, только чтение.

Источник и обновление

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

const proxyHost = PK.ip;

`PK.port`

Тип и доступ

string, только чтение. Даже числовой порт возвращается строкой.

Источник и обновление

Поле порта текущей записи прокси. Меняется одновременно с остальными свойствами прокси.

const proxyPortText = PK.port;

`PK.proxyType`

Тип и доступ

string, только чтение.

Источник и обновление

Точное обозначение типа в текущей записи прокси. Значение обновляется при смене записи; сценарий не должен исправлять регистр или угадывать тип по адресу.

const connectionType = PK.proxyType;

`PK.proxy`

Тип и доступ

string, только чтение.

Источник и обновление

Полная текстовая запись текущего прокси в форме, которую хранит список проекта. Обновляется при любом выборе другой записи.

const currentProxyRecord = PK.proxy;

`PK.proxyURI`

Тип и доступ

string, только чтение.

Источник и обновление

Адрес текущего прокси в форме protocol://user:password@ip:port. Части авторизации отсутствуют, если их нет в записи; значение меняется вместе с текущим прокси.

const proxyAddress = PK.proxyURI;

proxyURI может содержать пароль открытым текстом

Не используйте PK.proxyURI для безопасного журнала. Если нужна только точка подключения, читайте отдельно PK.ip и PK.port.

Тип и доступ

string, только чтение.

Источник и обновление

Имя пользователя из текущей записи прокси. Если авторизация не задана, возвращается пустая строка; при смене прокси значение обновляется.

const proxyUser = PK.proxyLogin;

`PK.proxyPassword`

Тип и доступ

string, только чтение.

Источник и обновление

Пароль из текущей записи прокси. Если авторизация не задана, возвращается пустая строка; при смене прокси значение обновляется.

const proxySecret = PK.proxyPassword;

Запрос и ответ

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

До запроса

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

Во время запроса

Обычный HTTP-путь очищает тело и заголовки, выбирает User-Agent, выполняет переходы и собирает новые значения.

После ответа

Сценарий после ответа видит обработанное тело, конечные заголовки, cookie, историю адресов и исход последней транспортной попытки.

`PK.userAgent`

Тип и доступ

string, только чтение.

Источник и обновление

Строка User-Agent, выбранная текущим действием. Она вычисляется после предварительного сценария и перед отправкой запроса, поэтому до запроса свойство может ещё содержать значение предыдущего действия; после ответа оно относится к выполненному запросу.

const sentUserAgent = PK.userAgent;

`PK.response`

Тип и доступ

string, только чтение.

Источник и обновление

Обработанное тело ответа: уже с учётом выбранной кодировки, распаковки и настроек действия. Обычный HTTP-путь очищает строку перед запросом и записывает новое тело до запуска сценария после ответа.

Если договор сервера обещает объект JSON, разбирайте строку один раз и работайте уже с полученным объектом:

const body = JSON.parse(PK.response);
const accountId = body.account.id;

JSON.parse должен завершиться ошибкой на ответе, который нарушил ожидаемый договор. Не подменяйте такой ответ пустым объектом.

`PK.headers`

Тип и доступ

string, только чтение.

Источник и обновление

Многострочный текст заголовков последнего обработанного HTTP-ответа. Перед новой HTTP-попыткой строка очищается, а после цепочки переходов содержит заголовки последней выполненной попытки.

const responseHeaders = PK.headers;

`PK.cookies`

Тип и доступ

string, только чтение.

Источник и обновление

Текущее плоское хранилище cookie сетевой сессии. После принятого соединения Private Keeper заменяет строку содержимым своего хранилища; это не необработанные заголовки Set-Cookie.

const cookieState = PK.cookies;

В строке хранятся пары имя=значение. Область домена, путь, срок действия и защитные признаки браузерной cookie в этом свойстве не представлены.

`PK.redirectHistory`

Тип и доступ

string[], свойство только для чтения.

Источник и обновление

История адресов логического HTTP-запроса. Перед текущим действием она очищается, после обработки переходов элемент 0 содержит исходный адрес, а следующие элементы — фактически запрошенные адреса переходов.

const addresses = PK.redirectHistory;
const originalAddress = addresses[0];
const finalAddress = addresses[addresses.length - 1];

Каждое чтение возвращает отдельный массив JavaScript. Изменение addresses меняет только эту местную копию и не переписывает историю Private Keeper.

Типизированное состояние сети

Четыре сетевых свойства образуют одну запись состояния. Читайте их вместе после запроса: networkOutcome определяет ветку, а остальные три поля объясняют только транспортную ошибку.

not_run

Транспортная попытка ещё не зафиксирована: networkErrorKind === "none", код равен 0, сообщение пустое. Почтовый соединитель и WebSocket не заполняют эту запись, поэтому для них состояние остаётся not_run.

success

Транспорт выполнил запрос: вид ошибки равен none, код — 0, сообщение пустое. Код ответа HTTP, например 404 или 500, сам по себе не превращает транспортный исход в transport_error.

transport_error

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

Допустимы только следующие сочетания:

`networkOutcome`	`networkErrorKind`	`networkErrorCode`	`networkErrorMessage`
`not_run`	`none`	`0`	пустая строка
`success`	`none`	`0`	пустая строка
`transport_error`	`dns_failure`, `timeout`, `connection_reset`, `connection_refused`, `tls_failure` или `other`	исходный код, иногда `0`	непустой диагностический текст

Состояние хранит сырой исход транспорта

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

`PK.networkOutcome`

Тип и доступ

"not_run" | "success" | "transport_error", только чтение.

Источник и обновление

Состояние текущего обычного HTTP-запроса. Сбрасывается в not_run непосредственно перед логическим запросом, затем получает сырой исход транспорта; каждый выполненный переход заменяет его своим исходом.

if (PK.networkOutcome === "transport_error") {
  PK.conclusion = 2;
}

`PK.networkErrorKind`

Тип и доступ

Источник и обновление

Структурированный вид ошибки из той же сетевой записи. Обновляется одновременно с PK.networkOutcome; none допустим только для not_run и success.

const mayBeTemporary =
  PK.networkErrorKind === "timeout" ||
  PK.networkErrorKind === "connection_reset";

Значения означают: dns_failure — не удалось разрешить имя, timeout — превышено время ожидания, connection_reset — соединение сброшено, connection_refused — удалённая сторона отказала, tls_failure — ошибка защищённого соединения, other — иной транспортный сбой.

`PK.networkErrorCode`

Тип и доступ

number, целое число, только чтение.

Источник и обновление

Исходный диагностический код сетевого поставщика. Обновляется вместе с состоянием сети; для not_run и success всегда равен 0, а при transport_error число 0 остаётся допустимым.

const providerCode = PK.networkErrorCode;

Коды зависят от сетевого поставщика и среды. Для основной логики сначала используйте networkOutcome и networkErrorKind, а числовой код сохраняйте для точной диагностики.

`PK.networkErrorMessage`

Тип и доступ

string, только чтение.

Источник и обновление

Технический текст сетевого поставщика. Обновляется вместе с состоянием сети; пуст для not_run и success, непуст при transport_error.

if (PK.networkOutcome === "transport_error") {
  const diagnostic = PK.networkErrorMessage;
}

Не определяйте вид сбоя по словам в сообщении: язык и формулировка могут измениться. Для ветвления предназначен PK.networkErrorKind.

Полная обработка состояния

switch (PK.networkOutcome) {
  case "not_run":
    // Этот сценарий не получил исход обычной HTTP-попытки.
    break;

  case "success":
    // Транспорт завершён; теперь проверяйте договор самого ответа.
    break;

  case "transport_error":
    if (PK.networkErrorKind === "timeout") {
      PK.setDV("NetworkStatus", "Превышено время ожидания");
    } else {
      PK.setDV("NetworkStatus", "Сетевая ошибка");
    }
    PK.conclusion = 2;
    break;

  default:
    throw new Error("Неизвестное состояние сети");
}

В проекте должна существовать динамическая переменная NetworkStatus. Ветка default намеренно останавливает сценарий, если программа когда-либо передаст значение вне документированного договора.

Управление результатом

`PK.conclusion`

Тип и доступ

number, целое число; чтение и запись.

Источник и обновление

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

Поддерживаемые значения:

1 — хороший

Действие получило ожидаемый положительный результат.

0 — плохой

Ответ корректно обработан, но проверяемые данные не подходят.

2 — ошибка

Выполнение не смогло получить или обработать требуемый результат.

3 — капча

Продолжение требует обработки капчи или связанной защитной проверки.

99 — прочее

Текущее действие не относится к четырём основным исходам.

const body = JSON.parse(PK.response);

if (body.status === "valid") {
  PK.conclusion = 1;
} else if (body.status === "invalid") {
  PK.conclusion = 0;
} else {
  throw new Error("Неизвестный status в ответе");
}

Присваивайте только целые числа 0, 1, 2, 3 и 99. Внутренний мост способен округлить другое числовое значение, но такие итоги не входят в публичный договор и могут привести к неверному продолжению проекта. Общие значения результата также разобраны в справке Скрипт-бокса.

Распознавание капчи

`PK.AGResult`

Тип и доступ

string, только чтение.

Источник и обновление

Решение капчи в области текущего запроса. До получения или повторного использования решения возвращается пустая строка; после сохранения решения свойство сразу начинает возвращать его текст.

const captchaSolution = PK.AGResult;

if (captchaSolution !== "") {
  PK.setDV("CaptchaSolution", captchaSolution);
}

В проекте должна существовать динамическая переменная CaptchaSolution. Пустая строка означает отсутствие решения в текущем запросе, а не ошибку распознавания; сведения об ошибке берите из результата самого модуля капчи.

Решение относится к текущему запросу

Не храните PK.AGResult как бессрочное значение и не переносите его в другой запрос без явного договора: решение может быть привязано к адресу, параметрам задания, прокси и моменту получения. Порядок распознавания и ошибки описаны в справке модуля капчи.

Значение читается сейчас

Только одно свойство изменяемое

Момент сценария имеет значение

not_run

success

transport_error

На этой странице