URL.md

URL

Изменяемая абсолютная или относительная URI-ссылка с символами Unicode на основе RFC 3986 и RFC 3987. Все изменения атомарны: при ошибке объект сохраняет прежнее состояние. Компоненты, которых операция не касается, сохраняют исходное написание.

Имя класса URL используется как короткое предметное имя. Объект представляет URI-ссылку: она может быть абсолютной или относительной.

Оглавление

• Основные понятия
• Создание
• Общие свойства и представление
  • ВСтроку
  • КодированноеПредставление
  • Скопировать
  • ЯвляетсяАбсолютным
• Схема URL
  • СоответствуетСхеме
  • Схема
  • УстановитьСхему
• Серверная часть URL
  • КодированнаяСервернаяЧасть
  • СервернаяЧасть
  • УстановитьКодированнуюСервернуюЧасть
  • УстановитьСервернуюЧасть
• Данные пользователя URL
  • ДанныеПользователя
  • КодированныеДанныеПользователя
  • ВСтрокуБезДанныхПользователя
  • ВСтрокуСМаскированнымПаролем
  • УстановитьДанныеПользователя
  • УстановитьКодированныеДанныеПользователя
• Хост URL
  • ВидХоста
  • IPАдресХоста
  • ЯвляетсяПетлевым
  • КодированныйХост
  • УстановитьКодированныйХост
  • УстановитьХост
  • Хост
  • IDNХост
• Порт URL
  • ИспользуетСтандартныйПорт
  • Порт
  • СтандартныйПорт
  • ТекстПорта
  • УстановитьПорт
  • ЭффективныйПорт
• Путь URL
  • ДобавитьСегментПути
  • ДобавитьСегментыПути
  • КодированныеСегментыПути
  • КодированныйПуть
  • Путь
  • ПутьИСтрокаЗапроса
  • СегментыПути
  • УстановитьКодированныйПуть
  • УстановитьПуть
• Строка запроса URL
  • СтрокаЗапроса
  • КодированнаяСтрокаЗапроса
  • ПараметрыЗапроса
  • УстановитьСтрокуЗапроса
  • УстановитьКодированнуюСтрокуЗапроса
  • УстановитьПараметрыЗапроса
• Фрагмент URL
  • КодированныйФрагмент
  • УстановитьКодированныйФрагмент
  • УстановитьФрагмент
  • Фрагмент
• Разрешение ссылок
  • Разрешить
  • СделатьОтносительным
• Нормализация и сравнение
  • Корневой
  • Нормализованный
  • НормализованныйДляСхемы
  • Равен
  • РавенПоКомпонентам
  • Сравнить
  • Эквивалентен
  • ЭквивалентенДляСхемы
• Примеры
• Связанные сущности

Основные понятия

Пример иерархической URI-ссылки с серверной частью:

схема://данные-пользователя@хост:порт/путь?запрос#фрагмент

Серверная часть содержит только данные пользователя, хост и порт. Путь, запрос и фрагмент в неё не входят.

Абсолютная URI-ссылка содержит схему, например urn:isbn:9780140328721 или http:/path. Относительная ссылка схемы не содержит, например ../images/logo.svg. Дополнительные требования http, https, ws, wss и ftp проверяет отдельный метод СоответствуетСхеме().

Для компонентов с процентным кодированием предусмотрены пары методов:

• метод со словом Кодированный возвращает или принимает исходное %HH;
• метод без слова Кодированный декодирует или кодирует значение как UTF-8.

Например, для пути /files/a%2Fb метод КодированныйПуть() вернёт /files/a%2Fb, а Путь() вернёт /files/a/b. При этом %2F остаётся частью одного сегмента и не становится разделителем.

Если границы сегментов имеют значение для маршрутизации или проверки безопасности, используйте СегментыПути() или КодированныеСегментыПути(). Не разделяйте результат Путь() по символу /: после декодирования нельзя отличить исходный разделитель от %2F внутри сегмента.

УстановитьПуть("/a%2Fb") считает % данными и создаёт /a%252Fb. УстановитьКодированныйПуть("/a%2Fb") сохраняет /a%2Fb.

Серверная часть и её компоненты, запрос и фрагмент могут отсутствовать. При отсутствии метод возвращает Неопределено, при наличии пустого компонента возвращает пустую строку.

Строка	Метод	Результат
//host/path	ТекстПорта()	Неопределено
//host:/path	ТекстПорта()	""
/path	КодированныйХост()	Неопределено
///path	КодированныйХост()	""
/path	КодированнаяСтрокаЗапроса()	Неопределено
/path?	КодированнаяСтрокаЗапроса()	""
/path	КодированныйФрагмент()	Неопределено
/path#	КодированныйФрагмент()	""

Конструктор и методы изменения проверяют общую грамматику URI, но не ограничения конкретной схемы. Например, http:/path синтаксически корректен, однако СоответствуетСхеме() вернёт Ложь, потому что у http нет хоста.

Конструктор проверяет форму процентных последовательностей в пути, данных пользователя, хосте и фрагменте. В строке запроса допускается литеральный %. Подробнее это поведение описано в ПараметрыЗапросаURL. Декодирование UTF-8 выполняется при вызове декодирующих методов, поэтому они могут вызвать encoding.invalid.

Создание

Новый URL(<Адрес> = Неопределено, <База> = Неопределено)

Полная диспетчеризация конструктора:

Адрес	База	Поведение
Неопределено	Неопределено	Создание пустой относительной ссылки
Строка или URL	Неопределено	Создание независимого абсолютного или относительного URL
Строка или URL	Абсолютная база	Разрешение по RFC 3986 § 5.2
Неопределено	Заданная база	argument.required
Любая ссылка	Относительная база	url.base_not_absolute

Параметры:

Имя	Тип	Описание
Адрес	Строка, URL, Неопределено	Создаваемая ссылка
База	Строка, URL, Неопределено	Абсолютная база для относительной ссылки

Конструктор возвращает новый URL либо вызывает исключение:

Код	Условие
argument.invalid_type	Передан неподдерживаемый тип адреса или базы
argument.required	База задана без адреса
url.base_not_absolute	База не является абсолютной
Коды разбора URI	Адрес или база имеют недопустимый синтаксис

#Использовать url

Адрес = Новый URL("../users", "https://example.com/api/");
// https://example.com/users

Общие свойства и представление

ВСтроку

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

.ВСтроку()

Возвращаемое значение

Строка: текущее представление URL.

КодированноеПредставление

Возвращает ASCII-представление URL. Символы Unicode, включая символы хоста, преобразуются в UTF-8, после чего каждый полученный байт записывается как %HH. Уже записанные последовательности %HH сохраняют регистр шестнадцатеричных цифр.

.КодированноеПредставление()

Возвращаемое значение

Строка: URL, состоящий из символов ASCII.

Скопировать

Создаёт полностью независимую изменяемую копию.

.Скопировать()

Возвращаемое значение

Новый URL с независимым состоянием.

ЯвляетсяАбсолютным

Проверяет только наличие схемы. Например, http:/path является абсолютным URI, хотя не соответствует схеме http.

.ЯвляетсяАбсолютным()

Возвращаемое значение

Булево: Истина, если ссылка содержит схему.

Схема URL

СоответствуетСхеме

Возвращает Булево по результату проверки дополнительных ограничений схем http, https, ws, wss и ftp. Для относительной ссылки или неизвестной схемы возвращает Истина. Известные схемы требуют непустой хост; указанный непустой порт должен входить в диапазон 0..65535. ws и wss запрещают данные пользователя и фрагмент. Вызывайте метод после создания или изменения URL, если нужны ограничения схемы.

.СоответствуетСхеме()

Успешный конструктор, РазборURL.ПопытатьсяРазобрать() и РазборURL.ЭтоКорректнаяСсылка() не заменяют эту проверку. Метод проверяет структуру известной схемы, но не определяет доверие к узлу и не заменяет ограничения приложения на сетевые адреса.

Возвращаемое значение

Булево: Истина, если ссылка соответствует ограничениям своей схемы.

Схема

Возвращает схему без завершающего :.

.Схема()

Возвращаемое значение

Строка или Неопределено, если ссылка относительная и не содержит схемы.

УстановитьСхему

Устанавливает схему абсолютного URL без завершающего :.

.УстановитьСхему(<Значение>)

Параметры

Параметр	Тип	Описание
Значение	Строка	Новая схема

Возвращаемое значение

Тот же объект URL.

Ошибки

Код	Условие
argument.invalid_type	Передан неподдерживаемый тип
url.invalid_scheme	Значение не соответствует грамматике схемы

Серверная часть URL

КодированнаяСервернаяЧасть

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

.КодированнаяСервернаяЧасть()

Возвращаемое значение

Строка или Неопределено, если серверная часть отсутствует.

СервернаяЧасть

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

.СервернаяЧасть()

Возвращаемое значение

Строка или Неопределено, если серверная часть отсутствует.

Ошибки

Код	Условие
encoding.invalid	Один из декодируемых компонентов содержит некорректный UTF-8
idna.data.invalid	Встроенные данные IDNA повреждены или несовместимы

УстановитьКодированнуюСервернуюЧасть

Устанавливает кодированную серверную часть без изменения исходного написания.

.УстановитьКодированнуюСервернуюЧасть(<Значение>)

Параметры

Параметр	Тип	Описание
Значение	Строка, Неопределено	Кодированная серверная часть либо признак её удаления

Возвращаемое значение

Тот же объект URL.

Ошибки

Код	Условие
argument.invalid_type	Передан неподдерживаемый тип
Коды разбора URI	Нарушены синтаксис, форма %HH, форма хоста или IP-литерала

Поведение

Неопределено удаляет серверную часть вместе с её подкомпонентами.

УстановитьСервернуюЧасть

Разбирает и устанавливает декодированную серверную часть. Символы @, :, [ и ] интерпретируются как структурные разделители.

.УстановитьСервернуюЧасть(<Значение>)

Параметры

Параметр	Тип	Описание
Значение	Строка, Неопределено	Серверная часть либо признак её удаления

Возвращаемое значение

Тот же объект URL.

Ошибки

Код	Условие
argument.invalid_type	Передан неподдерживаемый тип
url.invalid_syntax	Значение содержит недопустимую кодовую точку Unicode
url.invalid_authority	Нарушена структура серверной части
url.invalid_host	Некорректен хост

Поведение

Неопределено удаляет серверную часть вместе с данными пользователя, хостом и портом.

Данные пользователя URL

ДанныеПользователя

Возвращает строго декодированные данные пользователя без завершающего @.

.ДанныеПользователя()

Возвращаемое значение

Строка или Неопределено, если данные пользователя отсутствуют.

Ошибки

Код	Условие
encoding.invalid	Процентные байты не образуют корректную последовательность UTF-8

КодированныеДанныеПользователя

Возвращает кодированные данные пользователя без завершающего @.

.КодированныеДанныеПользователя()

Возвращаемое значение

Строка или Неопределено, если данные пользователя отсутствуют.

ВСтрокуБезДанныхПользователя

Возвращает строку URL без кодированных данных пользователя и разделителя @.

.ВСтрокуБезДанныхПользователя()

Возвращаемое значение

Строка: URL без имени пользователя и пароля. Остальные компоненты сохраняются без изменений.

Поведение

Метод не гарантирует безопасное журналирование: секреты могут оставаться в пути, запросе и фрагменте.

ВСтрокуСМаскированнымПаролем

Возвращает строку URL, в которой текст после первого буквального : в данных пользователя заменён на *****. Если буквального : нет, строка возвращается без изменений. Кодированный %3A разделителем не считается.

.ВСтрокуСМаскированнымПаролем()

Возвращаемое значение

Строка: URL с замаскированным паролем. Имя пользователя и остальные компоненты сохраняются без изменений.

Поведение

Метод не гарантирует безопасное журналирование: секреты могут оставаться в пути, запросе и фрагменте.

УстановитьДанныеПользователя

Кодирует и устанавливает полные данные пользователя.

.УстановитьДанныеПользователя(<Значение>)

Параметры

Параметр	Тип	Описание
Значение	Строка, Неопределено	Данные пользователя либо признак их удаления

Возвращаемое значение

Тот же объект URL.

Ошибки

Код	Условие
argument.invalid_type	Передан неподдерживаемый тип
url.invalid_syntax	Значение содержит недопустимую кодовую точку Unicode

Поведение

При отсутствии серверной части она создаётся с пустым хостом. Неопределено удаляет имя и пароль.

УстановитьКодированныеДанныеПользователя

Устанавливает кодированные данные пользователя без завершающего @ и без изменения исходного написания.

.УстановитьКодированныеДанныеПользователя(<Значение>)

Параметры

Параметр	Тип	Описание
Значение	Строка, Неопределено	Кодированные данные либо признак их удаления

Возвращаемое значение

Тот же объект URL.

Ошибки

Код	Условие
argument.invalid_type	Передан неподдерживаемый тип
url.invalid_syntax	Значение содержит символы вне ASCII
url.invalid_authority	Значение нарушает структуру данных пользователя
url.invalid_percent_encoding	Нарушена форма %HH

Поведение

При отсутствии серверной части она создаётся с пустым хостом. Неопределено удаляет имя и пароль.

Хост URL

Хост() возвращает декодированное имя, КодированныйХост() сохраняет процентное кодирование, а IDNХост() преобразует международное доменное имя в Punycode для DNS. КодированноеПредставление() кодирует весь URI в ASCII, но не заменяет доменное имя на Punycode.

Чтобы получить полностью кодированную строку с DNS-совместимым хостом, создайте копию, установите в неё результат IDNХост() и вызовите КодированноеПредставление():

#Использовать url

Адрес = Новый URL("https://пример.рф/путь");
СетевойАдрес = Адрес.Скопировать();
СетевойАдрес.УстановитьХост(Адрес.IDNХост());

Сообщить(СетевойАдрес.КодированноеПредставление());
// https://xn--e1afmkfd.xn--p1ai/%D0%BF%D1%83%D1%82%D1%8C

Используйте исходное, процентно-кодированное или Punycode-представление в соответствии с требованиями клиента, которому передаётся адрес.

ВидХоста

Возвращает вид хоста: зарегистрированное имя, IPv4, IPv6 или IPvFuture. Значения перечислены в ВидыХостаURL. Без серверной части возвращает Неопределено.

.ВидХоста()

Возвращаемое значение

Строка из модуля ВидыХостаURL или Неопределено без серверной части.

IPАдресХоста

Возвращает явно заданный IPv4- или IPv6-адрес хоста по RFC 3986 §3.2.2. Квадратные скобки IPv6-литерала URL в результат не входят.

IP = Адрес.IPАдресХоста();

Возвращаемое значение

IPАдрес для IPv4- или IPv6-хоста. Для зарегистрированного имени, IPvFuture, пустого или отсутствующего хоста возвращает Неопределено.

Ограничения

Метод не выполняет разрешение доменного имени и не является самостоятельной защитой от SSRF. Зарегистрированное имя, включая похожие на IP-адрес нестандартные формы, может быть интерпретировано сетевым стеком как IP-адрес, о чём предупреждает RFC 3986 §7.4. Проверять нужно фактически разрешённые адреса.

ЯвляетсяПетлевым

Проверяет, указывает ли явно заданный хост URL на сетевой интерфейс обратной петли (loopback). Проверка выполняется без DNS-запросов и обращения к файлу hosts.

.ЯвляетсяПетлевым()

Метод возвращает Истина для:

• IPv4-адресов из 127.0.0.0/8 по RFC 1122 §3.2.1.3;
• IPv6-адреса ::1 по RFC 4291 §2.5.3;
• localhost, localhost. и имён внутри .localhost без учёта регистра по RFC 6761 §6.3.

При распознавании дерева localhost процентное кодирование незарезервированных символов не меняет результат. Например, local%68ost распознаётся как localhost по правилам RFC 3986 §6.2.2.2.

IPv6-адрес с отображённым IPv4 по RFC 4291 §2.5.5.2 классифицируется по вложенному IPv4-адресу. Например, ::ffff:127.0.0.1 считается петлевым, а ::ffff:192.0.2.1 нет.

Возвращаемое значение

Булево: Истина, если хост является петлевым.

Ошибки

Код	Условие
encoding.invalid	Процентные байты имени не образуют корректную последовательность UTF-8
idna.data.invalid	Встроенные данные IDNA повреждены или несовместимы

Ограничения

Метод классифицирует только текст URL и не является защитой от SSRF. Другое доменное имя может разрешиться в петлевой или иной специальный IP-адрес, а результат DNS может измениться между проверкой и подключением.

КодированныйХост

Возвращает кодированный хост без преобразования в Punycode. Квадратные скобки IP-литерала сохраняются.

.КодированныйХост()

Возвращаемое значение

Строка или Неопределено, если серверная часть отсутствует.

УстановитьКодированныйХост

Устанавливает кодированный хост без изменения исходного написания. IPv6 и IPvFuture должны быть заключены в квадратные скобки.

.УстановитьКодированныйХост(<Значение>)

Параметры

Параметр	Тип	Описание
Значение	Строка	Кодированный хост

Возвращаемое значение

Тот же объект URL.

Ошибки

Код	Условие
argument.invalid_type	Передан неподдерживаемый тип
url.invalid_syntax	Значение содержит символы вне ASCII
url.invalid_percent_encoding	Нарушена форма %HH
url.invalid_host	Хост не распознан

УстановитьХост

Устанавливает декодированный хост. IPv6-адрес без скобок автоматически заключается в квадратные скобки. В ВСтроку() символы Unicode сохраняются, а в КодированноеПредставление() и КодированныйХост() каждый байт их представления в UTF-8 записывается как %HH.

.УстановитьХост(<Значение>)

Параметры

Параметр	Тип	Описание
Значение	Строка	Зарегистрированное имя, IPv4, IPv6 или IPvFuture

Возвращаемое значение

Тот же объект URL.

Ошибки

Код	Условие
argument.invalid_type	Передан неподдерживаемый тип
url.invalid_syntax	Значение содержит недопустимую кодовую точку Unicode
url.invalid_host	Хост синтаксически недопустим

Хост

Возвращает декодированное логическое представление хоста.

.Хост()

Возвращаемое значение

Строка или Неопределено, если серверная часть отсутствует.

Ошибки

Код	Условие
encoding.invalid	Процентные байты имени не образуют корректную последовательность UTF-8
idna.data.invalid	Встроенные данные IDNA повреждены или несовместимы

IDNХост

Возвращает ASCII-совместимое представление хоста. Международное доменное имя строго проверяется по UTS #46 и преобразуется в Punycode с непереходной обработкой. ASCII-метки проверяются по правилам CheckHyphens и UseSTD3ASCIIRules: разрешены только буквы, цифры и дефис, дефис запрещён в начале и конце, а последовательность -- в позициях 3 и 4 разрешена только в префиксе xn--. Метка не может превышать 63 октета, а полное ASCII-имя без завершающей точки - 253 октета. IP-адрес возвращается без изменений.

Метка означает часть доменного имени между точками, а октет в этом разделе означает один байт ASCII. Непереходная обработка не заменяет специальные символы устаревшими ASCII-аналогами, например ß не превращается в ss. CheckHyphens проверяет положение дефисов, а UseSTD3ASCIIRules запрещает в ASCII-метках символы, кроме букв, цифр и дефиса.

.IDNХост()

Возвращаемое значение

Строка или Неопределено, если хост отсутствует.

Ошибки

Код	Условие
encoding.invalid	Процентные байты имени не образуют корректную последовательность UTF-8
url.invalid_host	Зарегистрированное имя не соответствует требованиям IDNA
idna.data.invalid	Встроенные данные IDNA повреждены или несовместимы

Порт URL

ИспользуетСтандартныйПорт

Проверяет, отсутствует ли порт, пуст ли он или равен стандартному порту схемы.

.ИспользуетСтандартныйПорт()

Возвращаемое значение

Булево: Истина, если URL использует стандартный порт известной схемы.

Порт

Возвращает числовое значение явно указанного непустого порта. Стандартный порт схемы не подставляется.

.Порт()

Возвращаемое значение

Число или Неопределено для отсутствующего либо пустого порта.

Ошибки

Код	Условие
url.port.numeric_overflow	Текст порта нельзя точно представить числом

СтандартныйПорт

Возвращает стандартный порт известной схемы.

.СтандартныйПорт()

Возвращаемое значение

Число или Неопределено, если схема неизвестна.

ТекстПорта

Возвращает исходный текст порта без начального :.

.ТекстПорта()

Возвращаемое значение

Строка или Неопределено, если разделитель порта отсутствует. Для пустого порта возвращается пустая строка.

УстановитьПорт

Устанавливает порт; допускаются значения больше 65535.

.УстановитьПорт(<Значение>)

Параметры

Параметр	Тип	Описание
Значение	Строка, Число, Неопределено	Порт либо признак его удаления

Возвращаемое значение

Тот же объект URL.

Ошибки

Код	Условие
argument.invalid_type	Передан неподдерживаемый тип
argument.invalid_value	Передано отрицательное или дробное число либо строка, содержащая не только цифры ASCII

Поведение

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

ЭффективныйПорт

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

.ЭффективныйПорт()

Возвращаемое значение

Число или Неопределено, если схема неизвестна и явный непустой порт отсутствует.

Ошибки

Код	Условие
url.port.numeric_overflow	Явный порт нельзя точно представить числом

Путь URL

ДобавитьСегментПути

Кодирует значение как один сегмент и добавляет его в конец пути. Символ / внутри значения кодируется как %2F. Если путь уже заканчивается /, новый непустой сегмент записывается после этого разделителя без добавления второго /. Добавление пустого сегмента к непустому пути, оканчивающемуся /, добавляет ещё один /.

Исходный URL	Сегмент	Результат
https://host/a	b/c.txt	https://host/a/b%2Fc.txt
https://host/a/	b	https://host/a/b
https://host/a/	""	https://host/a//
Относительная пустая ссылка	""	Пустая ссылка

.ДобавитьСегментПути(<Сегмент>)

Параметры

Параметр	Тип	Описание
Сегмент	Строка	Декодированный сегмент пути

Возвращаемое значение

Тот же объект URL.

Ошибки

Код	Условие
argument.invalid_type	Передан неподдерживаемый тип
url.invalid_syntax	Сегмент содержит недопустимую кодовую точку Unicode

ДобавитьСегментыПути

Последовательно кодирует и добавляет несколько сегментов пути.

.ДобавитьСегментыПути(<Сегменты>)

Параметры

Параметр	Тип	Описание
Сегменты	Массив, ФиксированныйМассив	Декодированные строковые сегменты

Возвращаемое значение

Тот же объект URL.

Ошибки

Код	Условие
argument.invalid_type	Передано значение другого типа либо коллекция содержит нестроковый элемент
url.invalid_syntax	Один из сегментов содержит недопустимую кодовую точку Unicode

Поведение

Перед изменением проверяются все элементы, поэтому ошибка не приводит к частичному добавлению. Если первый сегмент относительной ссылки без серверной части содержит :, перед путём добавляется ./ по RFC 3986 § 4.2.

КодированныеСегментыПути

Разделяет путь по буквальному / до декодирования.

.КодированныеСегментыПути()

Возвращаемое значение

Новый ФиксированныйМассив кодированных сегментов пути.

Пустые сегменты сохраняются по тем же правилам, что и в СегментыПути().

КодированныйПуть

Возвращает кодированный путь.

.КодированныйПуть()

Возвращаемое значение

Строка: кодированный путь, включая пустую строку.

Путь

Возвращает путь после строгого декодирования UTF-8.

.Путь()

Возвращаемое значение

Строка: декодированный путь.

Ошибки

Код	Условие
encoding.invalid	Процентные байты не образуют корректную последовательность UTF-8

ПутьИСтрокаЗапроса

Возвращает путь и запрос в кодированном виде без фрагмента.

.ПутьИСтрокаЗапроса()

Возвращаемое значение

Строка: кодированный путь и, при наличии ?, кодированный запрос с разделителем.

СегментыПути

Разделяет путь по буквальному / и строго декодирует каждый сегмент как UTF-8.

.СегментыПути()

Возвращаемое значение

Новый ФиксированныйМассив декодированных сегментов пути.

Пустые сегменты сохраняются. Пустой путь даёт один элемент "", путь / даёт два элемента "", а завершающий / создаёт завершающий пустой элемент. Например, /a/ даёт "", "a", "".

Ошибки

Код	Условие
encoding.invalid	Один из сегментов содержит некорректный UTF-8

УстановитьКодированныйПуть

Устанавливает кодированный путь без изменения исходного написания.

.УстановитьКодированныйПуть(<Значение>)

Параметры

Параметр	Тип	Описание
Значение	Строка	Кодированный путь

Возвращаемое значение

Тот же объект URL.

Ошибки

Код	Условие
argument.invalid_type	Передан неподдерживаемый тип
url.invalid_syntax	Значение содержит недопустимый символ
url.invalid_percent_encoding	Нарушена форма %HH

УстановитьПуть

Кодирует и устанавливает полный путь, сохраняя структурные разделители /.

.УстановитьПуть(<Значение>)

Параметры

Параметр	Тип	Описание
Значение	Строка	Декодированный путь

Возвращаемое значение

Тот же объект URL.

Ошибки

Код	Условие
argument.invalid_type	Передан неподдерживаемый тип
url.invalid_syntax	Значение содержит недопустимую кодовую точку Unicode

Строка запроса URL

СтрокаЗапроса() работает со всем запросом как с компонентом URI и оставляет + без изменений. ПараметрыЗапроса() по умолчанию разбирает пары в формате RFC3986(), где + является обычным символом. Для интерпретации application/x-www-form-urlencoded вызовите РазобратьКак(ФорматыПараметровЗапросаURL.ВебФорма()).

Повторные вызовы ПараметрыЗапроса() возвращают одну и ту же коллекцию. Ранее полученная ссылка на неё остаётся актуальной после изменения строки запроса через методы URL. Чтение параметров сохраняет исходное написание, а изменение пар влияет на последующее представление URL в соответствии с текущим форматом.

СтрокаЗапроса

Возвращает строку запроса после строгого декодирования UTF-8.

.СтрокаЗапроса()

Возвращаемое значение

Строка или Неопределено, если строка запроса отсутствует.

Ошибки

Код	Условие
encoding.invalid	Процентные байты не образуют корректную последовательность UTF-8

КодированнаяСтрокаЗапроса

Возвращает кодированную строку запроса без начального ?.

.КодированнаяСтрокаЗапроса()

Возвращаемое значение

Строка или Неопределено, если строка запроса отсутствует. Пустая строка запроса возвращается пустой строкой.

ПараметрыЗапроса

Возвращает связанную с URL коллекцию параметров запроса.

.ПараметрыЗапроса()

Возвращаемое значение

Тот же объект ПараметрыЗапросаURL на протяжении жизни URL.

УстановитьСтрокуЗапроса

Кодирует и устанавливает строку запроса без начального ?.

.УстановитьСтрокуЗапроса(<Значение>)

Параметры

Параметр	Тип	Описание
Значение	Строка, Неопределено	Декодированная строка запроса либо признак её удаления

Возвращаемое значение

Тот же объект URL.

Ошибки

Код	Условие
argument.invalid_type	Передан неподдерживаемый тип
url.invalid_syntax	Значение содержит недопустимую кодовую точку Unicode

Поведение

Пустая строка создаёт определённый пустой запрос ?. Неопределено полностью удаляет запрос.

УстановитьКодированнуюСтрокуЗапроса

Устанавливает кодированную строку запроса без начального ? и без изменения исходного написания.

.УстановитьКодированнуюСтрокуЗапроса(<Значение>)

Параметры

Параметр	Тип	Описание
Значение	Строка, Неопределено	Кодированная строка запроса либо признак её удаления

Возвращаемое значение

Тот же объект URL.

Ошибки

Код	Условие
argument.invalid_type	Передан неподдерживаемый тип
url.invalid_syntax	Значение содержит недопустимый символ

Поведение

Пустая строка создаёт определённый пустой запрос ?. Неопределено полностью удаляет запрос. Процент, не образующий последовательность %HH, в кодированном представлении заменяется на %25.

УстановитьПараметрыЗапроса

Копирует пары и текущий формат. Если в пустой коллекции строка запроса отсутствует, компонент запроса удаляется. Переданная коллекция остаётся независимой, а ранее полученная ссылка на параметры целевого URL остаётся актуальной.

.УстановитьПараметрыЗапроса(<Значение>)

Параметры

Имя	Тип	Описание
Значение	ПараметрыЗапросаURL	Копируемая коллекция

Возвращаемое значение

Тот же объект URL.

Ошибки

Код	Условие
argument.invalid_type	Передано значение другого типа

Фрагмент URL

КодированныйФрагмент

Возвращает кодированный фрагмент без начального #.

.КодированныйФрагмент()

Возвращаемое значение

Строка или Неопределено, если фрагмент отсутствует. Пустой фрагмент возвращается пустой строкой.

УстановитьКодированныйФрагмент

Устанавливает кодированный фрагмент без начального # и без изменения исходного написания.

.УстановитьКодированныйФрагмент(<Значение>)

Параметры

Параметр	Тип	Описание
Значение	Строка, Неопределено	Кодированный фрагмент либо признак его удаления

Возвращаемое значение

Тот же объект URL.

Ошибки

Код	Условие
argument.invalid_type	Передан неподдерживаемый тип
url.invalid_syntax	Значение содержит недопустимый символ
url.invalid_percent_encoding	Нарушена форма %HH

Поведение

Пустая строка создаёт определённый пустой фрагмент #. Неопределено полностью удаляет фрагмент.

УстановитьФрагмент

Кодирует и устанавливает фрагмент без начального #.

.УстановитьФрагмент(<Значение>)

Параметры

Параметр	Тип	Описание
Значение	Строка, Неопределено	Декодированный фрагмент либо признак его удаления

Возвращаемое значение

Тот же объект URL.

Ошибки

Код	Условие
argument.invalid_type	Передан неподдерживаемый тип
url.invalid_syntax	Значение содержит недопустимую кодовую точку Unicode

Поведение

Пустая строка создаёт определённый пустой фрагмент #. Неопределено полностью удаляет фрагмент.

Фрагмент

Возвращает фрагмент после строгого декодирования UTF-8.

.Фрагмент()

Возвращаемое значение

Строка или Неопределено, если фрагмент отсутствует.

Ошибки

Код	Условие
encoding.invalid	Процентные байты не образуют корректную последовательность UTF-8

Разрешение ссылок

Разрешить

Разрешает ссылку относительно текущего URL по RFC 3986 § 5.2.

.Разрешить(<Ссылка>)

Параметры

Параметр	Тип	Описание
Ссылка	Строка, URL	Относительная или абсолютная ссылка

Возвращаемое значение

Новый независимый абсолютный URL.

Ошибки

Код	Условие
argument.invalid_type	Передан неподдерживаемый тип ссылки
url.base_not_absolute	Текущий URL не является абсолютной базой
Коды разбора URI	Переданная строка имеет недопустимый синтаксис

СделатьОтносительным

Строит детерминированную URI-ссылку на абсолютную цель относительно текущего URL. Результат выбирается так, чтобы Разрешить() восстановил цель. Если это невозможно, возвращается абсолютная цель.

.СделатьОтносительным(<Цель>)

Параметры

Параметр	Тип	Описание
Цель	Строка, URL	Абсолютная целевая ссылка

Возвращаемое значение

Новый независимый URL: относительная ссылка либо нормализованная абсолютная цель.

Примеры выбранной формы результата:

База	Цель	Результат
http://e/a/	http://e/a/b	b
http://e/a/b/file	http://e/a/c/file2	../c/file2
http://e/a/b	http://e/a/	./
http://e/a/	https://e/a/b	https://e/a/b
http://e/a/	http://other/a/b	http://other/a/b

База с завершающим / рассматривается как каталог. Если схема или серверная часть не позволяют построить относительную ссылку с тем же смыслом, возвращается абсолютная цель.

Ошибки

Код	Условие
argument.invalid_type	Передан неподдерживаемый тип цели
argument.invalid_value	Цель не является абсолютной
url.base_not_absolute	Текущий URL не является абсолютной базой
Коды разбора URI	Переданная строка имеет недопустимый синтаксис

Нормализация и сравнение

Методы сравнивают только представления URI. Они не выполняют сетевые запросы и не гарантируют, что два URI ведут на один ресурс.

Корневой

Возвращает новый корневой URL для текущих схемы, хоста и порта. Результат состоит из нормализованных схемы и хоста, нестандартного порта, если он был задан, и пути /. Данные пользователя, исходный путь, строка запроса и фрагмент в результат не входят.

.Корневой()

Исходный URL	Результат
HTTPS://user@example.com:443/a?q=1#part	https://example.com/
https://example.com:8443/a	https://example.com:8443/
x://[2001:DB8::A]:1234/a	x://[2001:db8::a]:1234/

Схема, хост и порт нормализуются по тем же правилам, что и в НормализованныйДляСхемы(). Поэтому стандартный порт из результата удаляется. Исходный объект не изменяется.

RFC 3986 не определяет операцию получения корневого URL. Метод собирает результат из компонентов серверной части, описанных в RFC 3986 § 3.2, и устанавливает корневой путь / в соответствии с синтаксисом пути из RFC 3986 § 3.3.

Возвращаемое значение

Новый независимый URL с корневым путём.

Ошибки

Код	Условие
url.server_address_required	Текущий URL не содержит схему или непустой хост

Нормализованный

Возвращает новый URL после общей нормализации по RFC 3986 § 6.2.2:

• приводит схему и ASCII-символы хоста к нижнему регистру;
• приводит шестнадцатеричные цифры в %HH к верхнему регистру;
• декодирует %HH, если байт обозначает незарезервированный символ;
• сворачивает полные сегменты . и .., сохраняя смысл относительной ссылки;
• удаляет пустой порт и его разделитель по RFC 3986 § 3.2.3.

.Нормализованный()

Возвращаемое значение

Новый независимый нормализованный URL.

НормализованныйДляСхемы

Сначала выполняет все преобразования Нормализованный(), затем применяет правила схемы из RFC 3986 § 6.2.3:

• удаляет стандартный порт 80 для http и ws, 443 для https и wss, 21 для ftp;
• заменяет пустой путь на / для http, https, ws и wss, если определена серверная часть.

Для неизвестной схемы результат совпадает с Нормализованный().

.НормализованныйДляСхемы()

Возвращаемое значение

Новый независимый URL, нормализованный с учётом схемы.

Равен

Сравнивает исходные написания текущего URL и другой URI-ссылки без нормализации.

.Равен(<Другое>)

Параметры

Параметр	Тип	Описание
Другое	Строка, URL	Сравниваемая ссылка

Возвращаемое значение

Булево: Истина, если исходные строки совпадают.

Ошибки

Код	Условие
argument.invalid_type	Передано значение другого типа
Коды разбора URI	Переданная строка имеет недопустимый синтаксис

РавенПоКомпонентам

Проверяет совпадение структуры и кодированных данных двух ссылок. Метод вызывает Сравнить() и возвращает Истина, если результат равен нулю.

Например, HTTP://Example.com/a%2f равен по компонентам http://example.com/a%2F, а /%7E не равен /~.

.РавенПоКомпонентам(<Другое>)

Параметры

Параметр	Тип	Описание
Другое	Строка, URL	Сравниваемая ссылка

Возвращаемое значение

Булево: Истина, если кодированные компоненты равны по указанным правилам.

Ошибки

Код	Условие
argument.invalid_type	Передано значение другого типа
Коды разбора URI	Переданная строка имеет недопустимый синтаксис

Сравнить

Сравнивает ссылки для сортировки по кодированным компонентам. Регистр схемы, хоста и шестнадцатеричных цифр в %HH не учитывается. Остальные символы сравниваются буквально, без нормализации.

.Сравнить(<Другое>)

Параметры

Параметр	Тип	Описание
Другое	Строка, URL	Сравниваемая ссылка

Возвращаемое значение

Число: меньше нуля, если текущий URL должен идти раньше; больше нуля, если позже; ноль, если ссылки равны по компонентам. Конкретное значение числа не определено.

Ошибки

Код	Условие
argument.invalid_type	Передано значение другого типа
Коды разбора URI	Переданная строка имеет недопустимый синтаксис

Эквивалентен

Проверяет эквивалентность по общим правилам URI, не зависящим от схемы. Перед сравнением обе ссылки проходят Нормализованный().

Например, HTTP://Example.com/a/../%7E эквивалентен http://example.com/~. При этом http://example.com не эквивалентен http://example.com:80/, поскольку стандартный порт и пустой путь зависят от схемы.

.Эквивалентен(<Другое>)

Параметры

Параметр	Тип	Описание
Другое	Строка, URL	Сравниваемая ссылка

Возвращаемое значение

Булево: Истина, если ссылки эквивалентны после общей нормализации.

Ошибки

Код	Условие
argument.invalid_type	Передано значение другого типа
Коды разбора URI	Переданная строка имеет недопустимый синтаксис

ЭквивалентенДляСхемы

Проверяет эквивалентность с учётом правил известных схем. Перед сравнением обе ссылки проходят НормализованныйДляСхемы().

Например, http://example.com эквивалентен для схемы http://example.com:80/: порт 80 удаляется, а пустой путь заменяется на /. Для неизвестной схемы метод работает так же, как Эквивалентен().

.ЭквивалентенДляСхемы(<Другое>)

Параметры

Параметр	Тип	Описание
Другое	Строка, URL	Сравниваемая ссылка

Возвращаемое значение

Булево: Истина, если ссылки эквивалентны после нормализации с учётом схемы.

Ошибки

Код	Условие
argument.invalid_type	Передано значение другого типа
Коды разбора URI	Переданная строка имеет недопустимый синтаксис

Примеры

Безопасное добавление одного сегмента пути:

#Использовать url

Адрес = Новый URL("https://example.com/files");
Адрес.ДобавитьСегментПути("reports/2025.pdf");

Сообщить(Адрес.ВСтроку());
// https://example.com/files/reports%2F2025.pdf

Строка запроса и параметры веб-формы:

#Использовать url

Адрес = Новый URL("https://example.com/?q=hello+world");

Сообщить(Адрес.СтрокаЗапроса());
// q=hello+world

Адрес.ПараметрыЗапроса().РазобратьКак(
    ФорматыПараметровЗапросаURL.ВебФорма()
);
Сообщить(Адрес.ПараметрыЗапроса().Получить("q"));
// hello world

Представления международного доменного имени:

#Использовать url

Адрес = Новый URL("https://пример.рф/");

Сообщить(Адрес.Хост());
// пример.рф

Сообщить(Адрес.КодированныйХост());
// %D0%BF%D1%80%D0%B8%D0%BC%D0%B5%D1%80.%D1%80%D1%84

Сообщить(Адрес.IDNХост());
// xn--e1afmkfd.xn--p1ai

Сравнение после общей нормализации и с учётом схемы:

#Использовать url

Первый = Новый URL("http://example.com");
Второй = Новый URL("http://example.com:80/");

Сообщить(Первый.Эквивалентен(Второй));
// Ложь

Сообщить(Первый.ЭквивалентенДляСхемы(Второй));
// Истина

Связанные сущности

• ВидыХостаURL
• ПараметрыЗапросаURL
• КодыОшибокURL