---
metadata:
  - name: generator
    content: Diplodoc Platform v5.44.0
alternate:
  - https://yandex.ru/dev/disk-api/doc/en/reference/publish.md
  - https://yandex.ru/dev/disk-api/doc/ru/reference/publish.md
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/dev/disk-api/doc/ru/llms.txt

# Предоставление и настройка публичного доступа к ресурсу

Файлы и папки на Диске можно публиковать — генерировать ссылки, по которым они будут доступны не только владельцу. Опубликованный ресурс получает два новых атрибута:
- `public_key` — ключ опубликованного ресурса. По этому ключу другие приложения смогут получить метаинформацию о публичном ресурсе. [Как это делать](https://yandex.ru/dev/disk-api/doc/ru/reference/public.md#meta).
- `public_url` — публичная ссылка на ресурс вида `https://yadi.sk/...`. Пользователи, которым владелец ресурса передаст эту ссылку, смогут открыть опубликованную папку или скачать файл.

{% note warning %}

Опубликовать ресурс можно только с OAuth-токеном его владельца.

{% endnote %}

Необходимые права доступа для OAuth-приложения:
* `cloud_api:disk.read`
* `cloud_api:disk.write`
* `cloud_api:disk.app_folder`


## Формат запроса {#publish-q-request}

Формат запроса (query-параметры и тело) зависит от того, с какой версией API Диска вы планируете работать.
- В последней версии API можно задать списки пользователей, у которых будет персональный доступ к опубликованному ресурсу. Эти настройки определяются массивом `accesses[]` в теле запроса. При этом часть параметров из предыдущих версий API можно не использовать, так как их функции теперь могут выполнять другие параметры.
- Если вы уже пользуетесь версией API без массива `accesses[]`, вы можете продолжать это делать — метод поддерживает обратную совместимость. В этом случае, если вам необходимо задать персональный доступ ко вновь публикуемому ресурсу, вы можете воспользоваться либо полностью новым форматом тела запроса, либо часть параметров оставить в привычном варианте. Информация о взаимозаменяемости полей приведена в описании тела запроса на вкладке «Формат предыдущей версии API».

На то, используется ли в запросе массив `accesses[]`, указывает query-параметр `allow_address_access`.

Метод: ##PUT##.

```
https://cloud-api.yandex.net/v1/disk/resources/publish
 ? [path](*popup-path)=<путь к публикуемому ресурсу>
 & [[allow_address_access](*popup-allow_address_access)=<признак формата запроса с настройками персонального доступа>]
```

### Описание query-параметров {#query}

path[*](*popup-a)
: Путь к публикуемому ресурсу. Например, `%2Fbar%2Fphoto.png`.

<!-- source: ru/_includes/reference/parameters-warehouse/id-format/path-encoding.md -->
Путь в значении параметра следует кодировать в URL-формате.
<!-- endsource: ru/_includes/reference/parameters-warehouse/id-format/path-encoding.md -->


allow_address_access
: Параметр с типом `boolean`, который обозначает, по какому формату составлен запрос — с настройками персонального доступа или без.

Допустимые значения:

  - `false` (значение по умолчанию) — запрос не содержит массив настроек персонального доступа. Значение используется для обеспечения обратной совместимости: для запросов, сформированных по формату предыдущих версий API, в которых нет элементов массива `accesses[]`, query-параметр `allow_address_access` должен иметь значение `false` либо отсутствовать.
  - `true` — запрос составлен в формате, который предполагает использование настроек персонального доступа. Применяется, если вы используете текущую версию API и отправляете запрос с телом, в котором содержится массив `accesses[]`.

Чтобы отправлять запросы, которые содержат массив настроек доступа `accesses[]`, у вашего сервиса должна быть возможность и на обработку ответов с этим массивом.


\*  Обязательный параметр.


### Заголовки {#header}

```
Authorization: OAuth <token>
Content-Type: application/json
```

### Тело запроса {#body}

В теле запроса передается объект PublicSettings, с помощью которого можно задать настройки доступа для публикуемого ресурса.

{% list tabs group=version %}

- Формат с настройками персонального доступа

  ```json
  {
    "public_settings": {
      "available_until": integer,
      "password": "string",
      "accesses": [
        {
          "macros": [
            "string"
          ],
          "org_id": integer,
          "rights": [
            "string"
          ]
        },
        {
          "user_ids": [
            "string"
          ],
          "rights": [
            "string"
          ]
        },
        {
          "group_ids": [
            integer
          ],
          "rights": [
            "string"
          ]
        },
        {
          "department_ids": [
            integer
          ],
          "rights": [
            "string"
          ]
        }
      ]
    }
  }
  ```

  #|
  || **Параметр** | **Тип данных** | **Описание** ||
  ||`available_until` | integer | Время жизни ссылки на ресурс (в секундах).

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

  {% cut "Как создать новую ссылку на ресурс" %}

  Выполните одно из действий:
  - снимите ресурс с публикации (см. [описание запроса на закрытие публичного доступа](https://yandex.ru/dev/disk-api/doc/ru/reference/unpublish.md)) и опубликуйте снова с нужными настройками доступа;
  - измените настройки доступа (см. [описание запроса на изменение прав доступа](https://yandex.ru/dev/disk-api/doc/ru/reference/unpublish.md)).

  {% endcut %}

  ||
  ||`password` | string | Пароль для общего доступа к ресурсу по ссылке.

  Обязателен, если в массиве `accesses[]` для объекта с `macros` в параметре `rights` задано одно из прав `read_with_password` или `read_with_password_without_download`. ||
  ||`accesses` | array | [Массив параметров](#accesses), которые задают права доступа пользователей к ресурсу. Позволяет задать настройки для разных уровней доступа:
  - общего — внутри организации или для любых пользователей Яндекс 360 для бизнеса;
  - персонального для определенных сотрудников организации;
  - персонального для определенных групп;
  - персонального для определенных подразделений. ||
  |#

  **accesses []** {#accesses}

  : Массив `accesses []` может содержать по одному экземпляру объектов, описывающих следующие уровни доступа:

    - Общий доступ

      #|
      || **Параметр** | **Тип данных** | **Описание** ||
      ||`macros`[**](*popup-b) | array of string | Массив, который содержит информацию о том, будет ли общий доступ к ресурсу с указанными правами предоставлен только внутри организации или для любых пользователей. Возможные значения:
      - `employees` — общий доступ к ресурсу только внутри определенной организации;
      - `all` — общий доступ для всех пользователей.

      В данном поле внутри массива должно содержаться только одно значение. При передаче более одного значения в ответе на запрос вернется ошибка.  ||
      ||`org_id` | integer | Идентификатор организации, сотрудникам которой предоставляется общий доступ к ресурсу с правами, заданными в параметре `rights` данного объекта. Учитывается, только если параметр `macros` имеет значение `employees`.

      Можно указать идентификатор только той организации, в которой состоит пользователь, от чьего имени отправляется запрос. Если OAuth-токен не принадлежит сотруднику указанной организации, в ответе на запрос придет ошибка.||
      ||`rights`[**](*popup-b) | array of string | Права доступа к ресурсу. Возможные значения в порядке приоритета:
      - `write` — редактирование;
      - `read` — просмотр;
      - `read_without_download` — просмотр без возможности скачивания;
      - `read_with_password` — просмотр с доступом по паролю;
      - `read_with_password_without_download` — просмотр с доступом по паролю без возможности скачивания.

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

    - Персональный доступ для сотрудников

      #|
      || **Параметр** | **Тип данных** | **Описание** ||
      ||`user_ids` | array of string | Массив идентификаторов (uid) сотрудников организации, которым предоставляется персональный доступ к ресурсу с правами, заданными в параметре `rights` данного объекта.||
      ||`emails` | array of string | Массив адресов электронной почты сотрудников организации, которым предоставляется персональный доступ к ресурсу с правами, заданными в параметре `rights` данного объекта.||
      ||`rights` | array of string | Права доступа к ресурсу. Возможные значения:
      - `write` — редактирование;
      - `read` — просмотр.

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

    - Персональный доступ для групп

      #|
      || **Параметр** | **Тип данных** | **Описание** ||
      ||`group_ids` | array of integer | Массив идентификаторов групп (id) в организации, членам которых предоставляется персональный доступ к ресурсу с правами, заданными в параметре `rights` данного объекта.||
      ||`rights` | array of string | Права доступа к ресурсу. Возможные значения:
      - `write` — редактирование;
      - `read` — просмотр.

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

    - Персональный доступ для подразделений

      #|
      || **Параметр** | **Тип данных** | **Описание** ||
      ||`department_ids` | array of integer | Массив идентификаторов подразделений (id) в организации, членам которых предоставляется персональный доступ к ресурсу с правами, заданными в параметре `rights` данного объекта.||
      ||`rights` | array of string | Права доступа к ресурсу. Возможные значения:
      - `write` — редактирование;
      - `read` — просмотр.

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

    Объекты, которые описывают персональный доступ (для пользователей, групп и отделов), имеют приоритет над объектом, описывающим общий доступ (macros). Например, если для всех сотрудников организации настроен доступ с правом «просмотр», то некоторым из них можно переопределить это право на «редактирование».

  {% cut "**Примеры тела запроса с настройками персонального доступа**" %}

  {% list tabs accordion %}

  - Общий доступ на просмотр по временной ссылке

    ```json
    {
      "public_settings": {
        "available_until": 604800,
        "accesses": [
          {
            "macros": [
              "all"
            ],
            "rights": [
              "read"
            ]
          }
        ]
      }
    }
    ```

  - Общий доступ внутри организации на просмотр по паролю

    ```json
    {
      "public_settings": {
        "password": "A123456",
        "accesses": [
          {
            "macros": [
              "employees"
            ],
            "org_id": 8012499,
            "rights": [
              "read_with_password"
            ]
          }
        ]
      }
    }
    ```

  - Общий и персональный доступ с разными правами (с идентификацией сотрудников по uid)

    Общий доступ внутри организации на просмотр и персональный доступ для отдельных сотрудников (с указанными идентификаторами) и подразделений на редактирование:

    ```json
    {
      "public_settings": {
        "accesses": [
          {
            "macros": [
              "employees"
            ],
            "org_id": 8012499,
            "rights": [
              "read"
            ]
          },
          {
            "user_ids": [
              "1130000066112030",
              "1130000066113521"
            ],
            "rights": [
              "write"
            ]
          },
          {
            "department_ids": [
              1
            ],
            "rights": [
              "write"
            ]
          }
        ]
      }
    }
    ```

  - Общий и персональный доступ с разными правами (с идентификацией сотрудников по электронной почте)

    Общий доступ внутри организации на просмотр и персональный доступ для отдельных сотрудников (с указанными адресами электронной почты) и подразделений на редактирование:

    ```json
    {
      "public_settings": {
        "accesses": [
          {
            "macros": [
              "employees"
            ],
            "org_id": 8012499,
            "rights": [
              "read"
            ]
          },
          {
            "emails": [
              "login@domain.ru"
            ],
            "rights": [
              "read"
            ]
          },
          {
            "department_ids": [
              3
            ],
            "rights": [
              "write"
            ]
          }
        ]
      }
    }
    ```

  {% endlist %}

  {% endcut %}


- Формат предыдущей версии API

  ```json
  {
    "public_settings": {
      "available_until_verbose": {
        "enabled": boolean,
        "value": integer
      },
      "available_until": integer,
      "password_verbose": {
        "enabled": boolean,
        "value": "string"
      },
      "password": "string",
      "external_organization_id_verbose": {
        "enabled": boolean,
        "value": "string"
      },
      "external_organization_id": "string",
      "read_only": boolean,
    }
  }
  ```

  #|
  || **Параметр** | **Тип данных** | **Описание** | **Использование при переходе на текущую версию API** ||
  ||`available_until_verbose` | object | [Группа параметров](#available_until_verbose), которая задает время жизни ссылки на ресурс (в секундах), если запрос отправляется с мобильного устройства. | Оставлен для обеспечения обратной совместимости. В текущей версии вне зависимости от источника запроса, чтобы задать доступность ресурса по времени, вместо этого параметра достаточно указать параметр `available_until`. ||
  ||`available_until` | integer | Время жизни ссылки на ресурс (в секундах).

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

  {% cut "Как создать новую ссылку на ресурс" %}

  Выполните одно из действий:
  - снимите ресурс с публикации (см. [описание запроса на закрытие публичного доступа](https://yandex.ru/dev/disk-api/doc/ru/reference/unpublish.md)) и опубликуйте снова с нужными настройками доступа;
  - измените настройки доступа (см. [описание запроса на изменение прав доступа](https://yandex.ru/dev/disk-api/doc/ru/reference/unpublish.md)).

  {% endcut %}

  | Используется в текущей версии. ||
  ||`password_verbose` | object | [Группа параметров](#password_verbose), которая задает пароль для доступа к ресурсу по ссылке, если запрос отправляется с мобильного устройства. |
Оставлен для обеспечения обратной совместимости. В текущей версии вне зависимости от источника запроса, чтобы задать доступность ресурса по паролю, вместо этого параметра достаточно указать параметр `password`. ||
  ||`password` | string | Пароль для общего доступа к ресурсу по ссылке. | В текущей версии будет учитываться, только если в массиве `accesses[]` для объекта с `macros` в параметре `rights` задано одно из прав `read_with_password` или `read_with_password_without_download`. ||
  ||`external_organization_id_verbose` | object | [Группа параметров](#external_organization_id_verbose), которая задает идентификатор организации в Яндекс 360 для бизнеса, у сотрудников которой будет общий доступ к публикуемому ресурсу, если запрос отправляется с мобильного устройства. |
  Оставлен для обеспечения обратной совместимости. В текущей версии, чтобы задать ограничение на доступ внутри организации, вместо этого параметра следует использовать параметры массива `accesses[]`: в `macros` укажите значение `employees`, а в `org_id` — идентификатор организации. Если же в запросе в группе `external_organization_id_verbose` указано `enabled: true`, то эта группа имеет приоритет над параметром `accesses.macros`. ||
  ||`external_organization_id` | string | Идентификатор организации в Яндекс 360 для бизнеса, у сотрудников которой будет общий доступ к публикуемому ресурсу. Если параметр указан, то сотрудникам других организаций доступ к ресурсу будет запрещен.

  Можно указать идентификатор только той организации, в которой состоит пользователь, от чьего имени отправляется запрос. Если OAuth-токен не принадлежит сотруднику указанной организации, в ответе на запрос придет ошибка. |
  Оставлен для обеспечения обратной совместимости. В текущей версии, чтобы задать ограничение на доступ внутри организации,  вместо этого параметра следует использовать параметры массива `accesses[]`: в `macros` укажите значение `employees`, а в `org_id` — идентификатор организации. Если же в запросе указан параметр `external_organization_id`, то он имеет приоритет над параметром `accesses.macros`. ||
  ||`read_only` | boolean |Глобальная настройка, которая задает право «Только просмотр» для всех пользователей, имеющих общий доступ к публикуемому ресурсу. |
  Оставлен для обеспечения обратной совместимости. В текущей версии, чтобы задать конкретные права на ресурс,  вместо этого параметра следует использовать параметры массива `accesses[]`. Если же в запросе указано `read_only: true`, то значения параметров `accesses.rights` игнорируются. ||
  |#

  **available_until_verbose** {#available_until_verbose}

  :  

    #|
    || **Параметр** | **Тип данных** | **Описание** ||
    ||`enabled`[**](*popup-b) | boolean | Признак того, что при отправке запроса с мобильных устройств доступность ресурса по времени задается в этом объекте. ||
    ||`value` | integer | Время жизни ссылки на ресурс (в секундах).

    Аналогичен параметру `available_until`, но используется, только если запрос отправляется с мобильного устройства. Обеспечивает обратную совместимость с предыдущими версиями API.

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

    {% cut "Как создать новую ссылку на ресурс" %}

    Выполните одно из действий:
    - снимите ресурс с публикации (см. [описание запроса на закрытие публичного доступа](https://yandex.ru/dev/disk-api/doc/ru/reference/unpublish.md)) и опубликуйте снова с нужными настройками доступа;
    - измените настройки доступа (см. [описание запроса на изменение прав доступа](https://yandex.ru/dev/disk-api/doc/ru/reference/unpublish.md)).

    Если в новом запросе необходимо задать время жизни ссылки на ресурс, это можно сделать в поле `available_until`, даже если запрос отправляется с мобильного устройства — в текущей версии API источник запроса не имеет значения.

    {% endcut %}

    ||
    |#

  **password_verbose** {#password_verbose}

  :  

    #|
    || **Параметр** | **Тип данных** | **Описание** ||
    ||`enabled`[**](*popup-b) | boolean | Признак того, что при отправке запроса с мобильных устройств пароль для общего доступа к ресурсу задается в этом объекте.

    Если вы:
    - создаете запрос с мобильного устройства,
    - не указывали пароль в параметре `password`,
    - в `accesses.rights` задали права `read_with_password` или `read_with_password_without_download`,
    то параметр `enabled` должен иметь значение `true`. ||
    ||`value` | string | Пароль для общего доступа к ресурсу по ссылке. Обязателен, если `enabled` имеет значение `true`.

    Аналогичен параметру `password`, но используется, только если запрос отправляется с мобильного устройства. Обеспечивает обратную совместимость с предыдущими версиями API. ||
    |#

  **external_organization_id_verbose** {#external_organization_id_verbose}

  :  

    #|
    || **Параметр** | **Тип данных** | **Описание** ||
    ||`enabled`[**](*popup-b) | boolean | Признак того, что при отправке запроса с мобильных устройств идентификатор организации, у сотрудников которой будет общий доступ к публикуемому ресурсу, задается в этом объекте.

    Обеспечивает обратную совместимость с предыдущими версиями API. В текущей версии, чтобы задать ограничение на доступ внутри организации, следует использовать параметры массива `accesses[]`: в `macros` укажите значение `employees`, а в `org_id` — идентификатор организации. Если же в запросе указано `enabled: true`, то параметр `accesses.macros` игнорируется.||
    ||`value` | string | Идентификатор организации в Яндекс 360 для бизнеса, у сотрудников которой будет общий доступ к публикуемому ресурсу.

    Аналогичен параметру `external_organization_id`, но используется, только если запрос отправляется с мобильного устройства. Можно указать идентификатор только той организации, в которой состоит пользователь, от чьего имени отправляется запрос. Если OAuth-токен не принадлежит сотруднику указанной организации, в ответе на запрос придет ошибка. ||
    |#

  {% cut "**Примеры тела запроса по формату предыдущей версии API**" %}

  {% list tabs accordion %}


  - Доступ внутри организации

    Общий доступ внутри организации c правами только но просмотр:

    ```json
    {
      "public_settings": {
        "password_verbose": {
          "enabled": false
        },
        "password": "A12345",
        "external_organization_id_verbose": {
          "enabled": false
        },
        "external_organization_id": "8012499",
        "read_only": true
      }
    }
    ```

  - С мобильного устройства в рамках обратной совместимости

    Общий доступ для всех по временной ссылке c правами только но просмотр:

    ```json
    {
      "public_settings": {
        "available_until_verbose": {
          "enabled": true,
          "value": 604800
        },
        "read_only": true
      }
    }
    ```

  - Добавление настроек персонального доступа

    К запросу из предыдущего примера добавлены настройки персонального доступа для двух пользователей при этом остальные параметры использованы по формату предыдущей версии API:

    ```json
    {
      "public_settings": {
        "available_until_verbose": {
          "enabled": true,
          "value": 604800
        },
        "read_only": true,
        "accesses": [
          {
            "user_ids": [
              "1130000066112030",
              "1130000066113521"
            ],
            "rights": [
              "write"
            ]
          }
        ]
      }
    }
    ```

    Такой запрос будет аналогичен следующему запросу, составленному по формату новой версии API:

    ```json
    {
      "public_settings": {
        "available_until": 604800,
        "accesses": [
          {
            "macros": [
              "all"
            ],
            "rights": [
              "read"
            ]
          },
          {
            "user_ids": [
              "1130000066112030",
              "1130000066113521"
            ],
            "rights": [
              "write"
            ]
          }
        ]
      }
    }
    ```


  {% endlist %}

  {% endcut %}

{% endlist %}

{% note info %}

Для каждого ресурса можно указать до 200 получателей персонального доступа – пользователей, групп и подразделений.

{% endnote %}

## Формат ответа {#publish-q-response}

### Успешный ответ

Если запрос был обработан без ошибок, API отвечает кодом `200 OK` и возвращает ссылку на опубликованный ресурс в теле ответа (в объекте [Link](https://yandex.ru/dev/disk-api/doc/ru/reference/response-objects.md#link)).

Пример ответа:

```json
{
  "href": "https://cloud-api.yandex.net/v1/disk/resources?path=disk%3A%2Fbar%2Fphoto.png",
  "method": "GET",
  "templated": false
}
```

<!-- source: ru/_includes/reference/response-objects/id-link/link-table.md -->


#|
|| **Элемент** | **Описание**||
|| `href` | URL. Может быть шаблонизирован, см. ключ `templated`. ||
|| `method` | HTTP-метод для запроса URL из ключа `href`. ||
|| `templated` | Признак URL, который был шаблонизирован согласно [RFC 6570](http://tools.ietf.org/html/rfc6570). Возможные значения:

- «true» — URL шаблонизирован: прежде чем отправлять запрос на этот адрес, следует указать нужные значения параметров вместо значений в фигурных скобках.
- «false» — URL может быть запрошен без изменений.||
|#
<!-- endsource: ru/_includes/reference/response-objects/id-link/link-table.md -->

### Ответ с ошибкой

<!-- source: ru/_includes/reference/response-error.md -->
Если запрос вызвал ошибку, возвращается подходящий код ответа, а тело ответа содержит [описание ошибки](https://yandex.ru/dev/disk-api/doc/ru/reference/response-objects.md#error).
<!-- endsource: ru/_includes/reference/response-error.md -->

Некоторые возможные ошибки:

* `400` — Некорректный запрос.
* `401` — Не авторизован.
* `403` — API недоступно. Ваши файлы занимают больше места, чем у вас есть. Удалите лишнее или увеличьте объем Диска. / API недоступно. Диск в режиме «только чтение». Проверьте тариф вашей организации. / API недоступно. Недопустимые права доступа. / API недоступно. Достигнут лимит на выдачу прав.
* `404` — Не удалось найти запрошенный ресурс.
* `423` — Запрошенный ресурс доступен только для чтения.
* `423` — Технические работы. Сейчас можно только просматривать и скачивать файлы.
* `423` — Ресурс заблокирован. Возможно, над ним выполняется другая операция.
* `503` — Сервис временно недоступен.
* `507` — Недостаточно свободного места.

[*popup-path]: Путь к публикуемому ресурсу. Например, `%2Fbar%2Fphoto.png`.


Путь в значении параметра следует кодировать в URL-формате.

[*popup-allow_address_access]: Параметр с типом `boolean`, который обозначает, по какому формату составлен запрос — с настройками персонального доступа или без.

Допустимые значения:

  - `false` (значение по умолчанию) — запрос не содержит массив настроек персонального доступа. Значение используется для обеспечения обратной совместимости: для запросов, сформированных по формату предыдущих версий API, в которых нет элементов массива `accesses[]`, query-параметр `allow_address_access` должен иметь значение `false` либо отсутствовать.
  - `true` — запрос составлен в формате, который предполагает использование настроек персонального доступа. Применяется, если вы используете текущую версию API и отправляете запрос с телом, в котором содержится массив `accesses[]`.

Чтобы отправлять запросы, которые содержат массив настроек доступа `accesses[]`, у вашего сервиса должна быть возможность и на обработку ответов с этим массивом.

[*popup-a]: Обязательный параметр.

[*popup-b]: Параметр обязательный, если в запросе присутствует объект, к которому этот параметр относится.