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

Файлы и папки на Диске можно публиковать — генерировать ссылки, по которым они будут доступны не только владельцу. Опубликованный ресурс получает два новых атрибута:

• public_key — ключ опубликованного ресурса. По этому ключу другие приложения смогут получить метаинформацию о публичном ресурсе. Как это делать.
• public_url — публичная ссылка на ресурс вида https://yadi.sk/.... Пользователи, которым владелец ресурса передаст эту ссылку, смогут открыть опубликованную папку или скачать файл.

Необходимые права доступа для OAuth-приложения:

• cloud_api:disk.read
• cloud_api:disk.write
• cloud_api:disk.app_folder

Формат запроса

Формат запроса (query-параметры и тело) зависит от того, с какой версией API Диска вы планируете работать.

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

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

Метод: PUT.

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

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

path*

Путь к публикуемому ресурсу. Например, %2Fbar%2Fphoto.png.

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

allow_address_access

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

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

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

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

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

Заголовки

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

Тело запроса

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

{
  "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"
        ]
      }
    ]
  }
}

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

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

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

{
  "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,
  }
}

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

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

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

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

Формат ответа

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

Если запрос был обработан без ошибок, API отвечает кодом 200 OK и возвращает ссылку на опубликованный ресурс в теле ответа (в объекте Link).

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

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

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

Если запрос вызвал ошибку, возвращается подходящий код ответа, а тело ответа содержит описание ошибки.

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

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