> ## Documentation Index
> Fetch the complete documentation index at: https://docs.catproxy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Параметры управления сессиями

> Узнайте, как управлять ротацией IP-адресов и создавать закреплённые сессии (sticky sessions) с настраиваемой продолжительностью с помощью параметров управления сессией.

Управление сессиями позволяет вам контролировать жизненный цикл IP-адреса вашего прокси. По умолчанию каждый ваш запрос получает новый случайный IP-адрес из нашего пула (ротация на каждый запрос). Однако для многих задач необходимо сохранять один и тот же IP-адрес в течение нескольких запросов. Это называется "закреплённой сессией" (sticky session).

Вы управляете этим поведением, добавляя параметры сессии к **имени пользователя** вашего прокси.

***

## Типы сессий

<CardGroup cols={2}>
  <Card title="Ротация IP (по умолчанию)" icon="rotate">
    **Поведение:** вы получаете новый IP-адрес при каждом запросе.<br />
    **Пример использования:** идеально подходит для масштабных задач парсинга, где необходимо максимальное разнообразие IP-адресов, чтобы избежать ограничений скорости и блокировок.<br />
    **Как использовать:** отправляйте запросы с базовым именем пользователя, без параметров сессии.
  </Card>

  <Card title="Фиксированный IP (закреплённая сессия)" icon="map-pin">
    **Поведение:** вы получаете один IP-адрес и можете использовать его повторно в течение определённого периода времени.<br />
    **Пример использования:** необходим для любого многошагового сценария на сайте - например, для входа в систему, добавления товаров в корзину или навигации по постраничным результатам.<br />
    **Как использовать:** добавьте параметр `-session` к своему имени пользователя.
  </Card>
</CardGroup>

***

## Параметры управления сессией

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

### Идентификатор сессии (`-session`)

Это основной параметр для включения закреплённой сессии.

<Accordion title="Подробности параметра">
  * **Формат:** `-session-[id]`
  * **Значение:** любая буквенно-цифровая строка по вашему выбору. Эта строка является вашим уникальным идентификатором для сессии.
  * **Зависимости:** нет.
  * **Как это работает:** все запросы, отправленные с одним и тем же идентификатором сессии, будут направляться через один и тот же выходной IP на протяжении всей сессии. Чтобы получить новый IP, просто измените ID сессии.
  * **Примеры имени пользователя:**
    * `...-my_scraper-session-user123` (получает IP **A**)
    * `...-my_scraper-session-user123` (по-прежнему получает IP **A**)
    * `...-my_scraper-session-user456` (получает новый IP, IP **B**)
</Accordion>

### Время сессии (`-time`)

По умолчанию закреплённая сессия длится **10 минут**. Параметр `-time` позволяет вам изменить эту продолжительность.

<Accordion title="Подробности параметра">
  * **Формат:** `-time-[минуты]`
  * **Значение:** целое число.
  * **Зависимости:** **должен** использоваться вместе с параметром `-session`.
  * **Пример имени пользователя:** `...-my_scraper-session-user123-time-30`
  * **Результат:** закреплённая сессия для `user123` будет длиться **30 минут** вместо 10 по умолчанию.
  * **Случай ошибки:** использование `-time-30` без `-session` приведёт к ошибке.
</Accordion>

<Warning>
  **Важное замечание о надёжности сессии:**
  Продолжительность сессии - это запрос, а не 100% гарантия. Из-за динамичной природы резидентных сетей устройство-узел может отключиться в любой момент. Если IP-адрес вашей сессии станет недоступным, наша система автоматически назначит вам **новый IP** при следующем запросе с тем же идентификатором сессии.
</Warning>

### Строгий режим (`-const`)

Этот параметр изменяет поведение шлюза, когда IP-адрес сессии становится недоступным.

<Accordion title="Подробности параметра">
  * **Формат:** `-const` (это флаг, он не имеет значения).
  * **Зависимости:** **должен** использоваться вместе с параметром `-session`.
  * **Поведение по умолчанию (без `-const`):** если IP-адрес вашей сессии становится недоступным, мы автоматически назначаем новый IP для вашей сессии. Это гарантирует, что ваш парсер продолжит работу.
  * **Поведение с `-const`:** если IP-адрес вашей сессии становится недоступным, мы **не** назначаем замену. Вместо этого ваш запрос завершится с ошибкой `502 Bad Gateway` и заголовком `X-Catproxy-Error: Session IP is offline`.
  * **Пример использования:** используйте этот вариант только в тех случаях, когда ваш рабочий процесс критически зависит от использования **одного и того же IP** от начала до конца, и вы предпочтете, чтобы процесс завершился ошибкой, а не продолжился с новым IP.
  * **Пример имени пользователя:** `...-my_scraper-session-user123-time-60-const`
</Accordion>

***

### Какой тип сессии использовать?

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

| Если ваша цель...                                                                                                                                                                     | Рекомендуемые параметры                    | Пример имени пользователя                     | Почему это работает                                                                                                                                                                                            |
| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------- | :-------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Максимальная анонимность и парсинг простых страниц**<br />(например, сбор цен на товары с нескольких страниц)                                                                       | (нет - используйте поведение по умолчанию) | `...-proxy-myproject-country-de`              | По умолчанию вы получаете **новый IP для каждого запроса**. Это крайне затрудняет целевому сайту отслеживание вас как отдельного пользователя.                                                                 |
| **Многошаговые действия и вход в систему**<br />(например, вход в аккаунт, заполнение формы, навигация по корзине)                                                                    | `-session-[ваш_id]`                        | `...-proxy-myproject-session-user123`         | Использование идентификатора `session` гарантирует, что вы сохраните **один и тот же IP-адрес** для последовательности запросов, что позволит вам выглядеть как обычный пользователь, перемещающийся по сайту. |
| **Долгосрочный сбор данных с одного IP**<br />(например, мониторинг определённого профиля в социальных сетях в течение часа)                                                          | `-session-[ваш_id] -time-[минуты]`         | `...-proxy-myproject-session-task456-time-60` | Добавление параметра `-time` увеличивает стандартное 10-минутное время жизни сессии.                                                                                                                           |
| **Задачи повышенной безопасности, где смена IP недопустима**<br />(например, управление конфиденциальным онлайн-аккаунтом, где внезапная смена IP может вызвать тревогу безопасности) | `-session-[ваш_id] -const`                 | `...-proxy-myproject-session-secure-const`    | Флаг `-const` гарантирует, что если назначенный вам IP сессии станет недоступным, ваш запрос **завершится ошибкой** вместо автоматического назначения нового IP. Это предотвращает случайное раскрытие IP.     |