Как использовать маркировку капель с API DigitalOcean

Вступление

API-интерфейс DigitalOcean предоставляет доступ к большинству функций панели управления DigitalOcean и предлагает простой способ управления каплями и другими ресурсами из командной строки или из собственного кода.

Маркировка капель является новой функцией. Эта функция позволяет группировать и находить капли с помощью тегов, а также инициировать действия для всех капель с определенным тегом.

Предпосылки

В этом руководстве для всех примеров используется утилитаcurl и Bash. Предполагается, что вы знакомы с использованием API DigitalOcean и уже создалиpersonal access token. Подробнее об этом процессе и основах использования API см.How To Use the DigitalOcean API v2.

Как только у вас будет токен, начните с установки переменной$TOKEN в вашей оболочке. Командаexport гарантирует, что дочерние процессы могут читать переменную:

export TOKEN=your_personal_access_token

Мы будем использовать$TOKEN для остальных примеров в этом документе, всегда внутри строки с двойными кавычками, чтобы интерполировать ее значение, а не буквальную строку$TOKEN. Если вы получаете ошибки, сначала убедитесь, что это значение правильно установлено в вашей текущей оболочке.

Создание, перечисление и просмотр тегов

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

Создание тегов самостоятельно

Используйтеcurl для отправки POST в конечную точку API, включая заголовки дляContent-Type, ваш личный токен доступа и некоторые данные JSON для указания имени тега. Замените желаемое имя тега наtag_name:

curl -X POST \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $TOKEN" \
-d '{"name":"tag_name"}' \
"https://api.digitalocean.com/v2/tags"

Output{"tag":{"name":"tag_name","resources":{"droplets":{"count":0,"last_tagged":null}}}}

[.note] #Note: Этот запрос, как и любой другой запрос, который вносит изменения в вашу учетную запись, требует, чтобы ваш токен имел назначенную ему область «записи».
#

Создание и применение тегов при создании других ресурсов

Ресурсы также могут включать атрибутtags при создании. Это массив имен тегов, которые будут применяться при создании. Теги, которые еще не существуют, будут созданы для удовлетворения запроса. Единственный поддерживаемый ресурс на момент написания этой статьи - это Droplet, но в конечном итоге будут доступны и другие.

Чтобы создать дроплет и применить теги при создании, вы можете набрать:

curl -X POST \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $TOKEN" \
-d '{"name":"example.com","region":"nyc3","size":"512mb","image":"ubuntu-14-04-x64","tags":["tag_name","another_tag"]}' \
"https://api.digitalocean.com/v2/droplets"

Это создаст новую каплю с примененными тегамиtag_name иanother_tag. Если был выполнен пример из предыдущего раздела, то эта команда применила бы существующий тегtag_name и создала бы и применила тегanother_tag к дроплету.

Перечисление существующих тегов

Вы можете перечислить все ваши текущие теги с помощью запроса GET к/v2/tags:

curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.digitalocean.com/v2/tags"

Output{"tags":[{"name":"tag_name","resources":{"droplets":{"count":0,"last_tagged":null}}}],"links":{},"meta":{"total":1}}

Чтобы просмотреть отдельный тег, используйте запрос GET к/v2/tags/tag_name:

curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.digitalocean.com/v2/tags/tag_name"

Output{"tag":{"name":"tag_name","resources":{"droplets":{"count":0,"last_tagged":null}}}}

Пример вывода выше краткий. Обратите внимание, что свойствоresources.droplets.last_tagged равноnull. Как только вы свяжете тег с одной или несколькими каплями, это свойство будет содержать подробную информацию о последней помеченной капле.

Пометка и разметка капель

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

Капли связаны с тегами с помощью их атрибутаid. Вы можете получить объект JSON, содержащий массивdroplets, в котором перечислены все ваши капли, с помощью запроса GET к/v2/droplets:

curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.digitalocean.com/v2/droplets"

Как только вы знаетеid капли, вы можете связать ее с тегом, отправив POST в/v2/tags/tag_name/resources, включая данные JSON, которые устанавливаютresource_id в каплюid иresource_type в строкуdroplet:

curl -X POST \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $TOKEN" \
-d '{"resources":[{"resource_id":"droplet_id","resource_type":"droplet"}]}' \
"https://api.digitalocean.com/v2/tags/tag_name/resources"

Попробуйте снова запросить GET для тега, и свойствоresources.droplets.last_tagged должно содержать подробную информацию о капле, которую вы только что отметили:

curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.digitalocean.com/v2/tags/tag_name"

Чтобы удалить тег из определенной капли, вы можете отправить запрос DELETE к/v2/tags/tag_name/resources/ с теми же данными, которые вы использовали для маркировки капли в первую очередь:

curl -X DELETE \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $TOKEN" \
-d '{"resources":[{"resource_id":"droplet_id","resource_type":"droplet"}]}' \
"https://api.digitalocean.com/v2/tags/tag_name/resources"

Это удалит тег из ресурса.

Поиск капель по метке

Чтобы найти все капли, связанные с определенным тегом, отправьте запрос GET к/v2/droplets?tag_name=tag_name:

curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.digitalocean.com/v2/droplets?tag_name=tag_name"

Это отфильтрует ваши капли по запрошенному тегу.

Выполнение действий с помеченными каплями

Вы можете выполнить ряд действий со всеми каплями, связанными с определенным тегом:

Data Заметки

Data	Заметки
`{"type":"power_cycle"}`	Выключите и снова включите Droplets.
`{"type":"power_on"}`	Включены капли питания. Должно быть выключено.
`{"type":"power_off"}`	Капли питания отключены. Должен быть на.
`{"type":"shutdown"}`	Shutdown Droplets, аналогично выключению из командной строки.
`{"type":"enable_private_networking"}`	Включитеprivate networking.
`{"type":"enable_ipv6"}`	ВключитеIPv6 addresses для капель.
`{"type":"enable_backups"}`	Включите резервное копирование для капель.
`{"type":"disable_backups"}`	Отключить резервное копирование.
`{"type":"snapshot, "name": "snapshot_name"}`	Сделайте снимки капель. Капли должны быть выключены в первую очередь, а`name` является обязательным.

{"type":"power_cycle"}

Выключите и снова включите Droplets.

{"type":"power_on"}

Включены капли питания. Должно быть выключено.

{"type":"power_off"}

Капли питания отключены. Должен быть на.

{"type":"shutdown"}

Shutdown Droplets, аналогично выключению из командной строки.

{"type":"enable_private_networking"}

Включитеprivate networking.

{"type":"enable_ipv6"}

ВключитеIPv6 addresses для капель.

{"type":"enable_backups"}

Включите резервное копирование для капель.

{"type":"disable_backups"}

Отключить резервное копирование.

{"type":"snapshot, "name": "snapshot_name"}

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

Чтобы выполнить действие, отправьте POST на/v2/droplets/actions?tag_name=tag_name с данными JSON, указавtype и любые дополнительные значения, необходимые для действия:

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{"type":"action_type"}' \
"https://api.digitalocean.com/v2/droplets/actions?tag_name=tag_name"

Вы можете получить историю последних действий, включая их статус завершения, с помощью запроса GET к/v2/actions:

curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.digitalocean.com/v2/actions"

Это полезный способ определить, завершены ли действия или все еще выполняются.

Пример: снимок с меткой капли

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

Сначала выполните действиеshutdown:

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{"type":"shutdown"}' \
"https://api.digitalocean.com/v2/droplets/actions?tag_name=fileserver"

Дождитесь завершения завершения работы всех капель и выполните действиеsnapshot, включая значениеname для снимка:

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{"type":"snapshot", "name":"snapshot_name"}' \
"https://api.digitalocean.com/v2/droplets/actions?tag_name=fileserver"

Имейте в виду, что создание снимков может занять час или более, в зависимости от размера капли. После завершения создания снимков вы можете вернуть капли в оперативный режим с помощью действияpower_on:

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{"type":"power_on"}' \
"https://api.digitalocean.com/v2/droplets/actions?tag_name=fileserver"

Это запустит дроплет снова.

Удаление тегов

Вы можете удалить сам тег и удалить его связь со всеми ресурсами с помощью запроса DELETE к/v2/tags/tag_name:

curl -X DELETE \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $TOKEN" \
"https://api.digitalocean.com/v2/tags/tag_name"

Тег будет полностью удален.

Заключение

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

Отсюда вы можете захотеть углубиться вdetailed DigitalOcean API documentation или исследоватьlibraries which wrap the API for popular programming languages.

TOC