POST-теги

Материал из Документация Ключ-АСТРОМ

API Ключ-АСТРОМ / Эндпойнты среды / Пользовательские теги / POST-теги

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

Запрос потребляет и создает application/jsonполезную нагрузку.

POST Managed https://{your-domain}/e/{your-environment-id}/api/v2/tags
Среда АктивногоШлюза https://{your-activegate-domain}/e/{your-environment-id}/api/v2/tags

Аутентификация

Чтобы выполнить этот запрос, вам необходимо разрешение на запись объектов ( entities.write) , назначенное вашему токену API. Чтобы узнать, как его получить и использовать, см. раздел Токены и аутентификация .

Параметры

Параметр Тип Описание In Необходимость
entitySelector string Указывает объекты, теги которых вы хотите обновить.

Вы должны установить один из этих критериев:

  • Тип объекта:type("TYPE")
  • Идентификатор объекта Ключ-АСТРОМ: entityId("id"). Вы можете указать несколько идентификаторов, разделенных запятой ( entityId("id-1","id-2")). Все запрошенные сущности должны быть одного типа.

Вы можете добавить один или несколько следующих критериев. Значения чувствительны к регистру, и EQUALSоператор используется, если не указано иное.

  • Тег: tag("value"). Теги в форматах [context]key:value, key:valueи valueобнаруживаются и анализируются автоматически. Любые двоеточия ( :), которые являются частью ключа или значения, должны быть экранированы обратной косой чертой ( \), в противном случае она будет интерпретироваться как разделитель между ключом и значением. Все значения тегов чувствительны к регистру.
  • Идентификатор зоны управления:mzId(123)
  • Название зоны управления:mzName("value")
  • Имя объекта: entityName("value"). По умолчанию это фильтрует объекты, имя которых содержит заданное значение и не чувствительно к регистру. Доступны следующие модификации:
    • entityName.equals: изменяет оператор на EQUALS.
    • entityName.startsWith: изменяет оператор на BEGINS WITH.
    • entityName.in: позволяет указать несколько значений. Оператор EQUALSобращается.
    • caseSensitive(entityName("value")): принимает любой критерий имени сущности в качестве аргументов и делает значение чувствительным к регистру.
  • Состояние здоровья (ЗДОРОВЫЙ, НЕЗДОРОВЫЙ):healthState("HEALTHY")
  • Отметка времени первого увиденного: firstSeenTms.<operator>(now-3h). Используйте любой формат метки времени из параметров from / to . Доступны следующие операторы:
    • lte: раньше или в указанное время
    • lt: раньше указанного времени
    • gte: позже или в указанное время
    • gt: позже указанного времени
  • Атрибут объекта: <attribute>("value1","value2")и <attribute>.exists(). Чтобы получить список доступных атрибутов, выполните запрос типа сущности GET и проверьте поле свойств ответа.
  • Связи: fromRelationships.<relationshipName>()и toRelationships.<relationshipName>(). Критерий принимает селектор объектов в качестве атрибута. Чтобы получить список доступных отношений, выполните запрос типа сущности GET и проверьте поля fromRelationships и toRelationships .
  • Отрицание: not(<criterion>). Инвертирует любой критерий, кроме type .

Дополнительные сведения см. в разделе Селектор объектов в документации Ключ-АСТРОМ.

Чтобы задать несколько критериев, разделите их запятой ( ,). Например, type("HOST"),healthState("HEALTHY"). В ответ включаются только результаты, соответствующие всем критериям.

Длина строки ограничена 10 000 символов.

запрос требуется
from string Начало запрошенного таймфрейма.

Вы можете использовать один из следующих форматов:

  • Отметка времени в миллисекундах UTC.
  • Читаемый формат 2021-01-25T05:57:01.123+01:00. Если часовой пояс не указан, используется UTC. Вы можете использовать пробел вместо T. Секунды и доли секунды не являются обязательными.
  • Относительный таймфрейм, назад. Формат: now-NU/A, где Nколичество времени, Uединица времени и Aвыравнивание. Выравнивание округляет все меньшие значения до ближайшего нуля в прошлом. Например, now-1y/wэто один год назад, выровненный на неделю. Вы также можете указать относительный таймфрейм без выравнивания: now-NU. Поддерживаемые единицы времени для относительного таймфрейма:
    • m: минуты
    • h: часы
    • d: дни
    • w: недели
    • M: месяцы
    • y: годы

Если не установлено, используется относительный временной интервал 24 часа ( now-24h).

запрос необязательный
to string Конец запрошенного периода времени.

Вы можете использовать один из следующих форматов:

  • Отметка времени в миллисекундах UTC.
  • Человекочитаемый формат 2021-01-25T05:57:01.123+01:00. Если часовой пояс не указан, используется UTC. Вы можете использовать пробел вместо T. Секунды и доли секунды не являются обязательными.
  • Относительный таймфрейм, назад. Формат: now-NU/A, где Nколичество времени, Uединица времени и Aвыравнивание. Выравнивание округляет все меньшие значения до ближайшего нуля в прошлом. Например, now-1y/wэто один год назад, выровненный на неделю. Вы также можете указать относительный таймфрейм без выравнивания: now-NU. Поддерживаемые единицы времени для относительного таймфрейма:
    • m: минуты
    • h: часы
    • d: дни
    • w: недели
    • M: месяцы
    • y: годы

Если не установлено, используется текущая метка времени.

запрос необязательный
body Добавить теги сущностей Тело JSON запроса. Содержит теги, которые необходимо добавить к соответствующим объектам. body необязательный

Объекты тела запроса

Объект AddEntityTags

Список тегов, которые будут добавлены к отслеживаемым объектам.

Элемент Тип Описание
tags AddEntityTag[] Список тегов, которые будут добавлены к отслеживаемым объектам.

Объект AddEntityTag

Пользовательский тег, добавляемый к отслеживаемым объектам.

Элемент Тип Описание
value string Значение пользовательского тега, добавляемого к отслеживаемым объектам. Может быть нулевым

Может быть null.

key string Ключ пользовательского тега, который будет добавлен к отслеживаемым объектам.

JSON-модель тела запроса

Это модель тела запроса, показывающая возможные элементы. Его необходимо настроить для использования в реальном запросе.

{
  "tags": [
    {
      "key": "mainApp"
    },
    {
      "key": "bookings",
      "value": "42"
    }
  ]
}

Ответ

Коды ответов

Код Тип Описание
200 AddedEntityTags Успех

Объекты тела ответа

Объект AddedEntityTags

Список настраиваемых тегов, добавленных к отслеживаемым объектам.

Элемент Тип Описание
matchedEntitiesCount integer Количество отслеживаемых объектов, в которые были добавлены теги.

Может быть null.

appliedTags METag[] Список добавленных пользовательских тегов.

Может быть null.

Объект METag

Тег отслеживаемого объекта.

Элемент Тип Описание
stringRepresentation string Строковое представление тега.

Может быть null.

value string Значение тега.

Может быть null.

key string Ключ тега.

Может быть null.

context string Происхождение тега, например AWS или Cloud Foundry.

Пользовательские теги используют это CONTEXTLESSзначение.

Может быть null.

JSON-модель тела ответа

{
  "appliedTags": [
    {
      "context": "CONTEXTLESS",
      "key": "mainApp",
      "stringRepresentation": "mainApp"
    },
    {
      "context": "CONTEXTLESS",
      "key": "booking",
      "stringRepresentation": "booking"
    }
  ],
  "matchedEntitiesCount": 2
}

Пример

В этом примере запрос добавляет пользовательские теги REST-test и RESTexample к хостам, которые уже имеют тег easyTravel . Для этого параметру запроса entitySelector присваиваетсяtype("HOST"),tag("easyTravel") значение .

Маркер API передается в заголовке авторизации .

Curl

curl -L -X POST 'https://mySampleEnv.live.astromkey.com/api/v2/tags?entitySelector=type(%22HOST%22),tag(%22easyTravel%22)' \
-H 'Authorization: Api-Token dt0c01.abc123.abcdefjhij1234567890' \
-H 'Content-Type: application/json' \
--data-raw '{
  "tags": [
  {
    "key": "REST-test"
  },
  {
    "key": "RESTexample"
  }
  ]
}'

URL-адрес запроса

https://mySampleEnv.live.astromkey.com/api/v2/tags?entitySelector=type(%22HOST%22),tag(%22easyTravel%22)

Тело запроса

{
  "tags": [
    {
      "key": "REST-test"
    },
    {
      "key": "RESTexample"
    }
  ]
}

Тело ответа

{
  "matchedEntitiesCount": 3,
  "appliedTags": [
    {
      "context": "CONTEXTLESS",
      "key": "REST-test",
      "stringRepresentation": "REST-test"
    },
    {
      "context": "CONTEXTLESS",
      "key": "RESTexample",
      "stringRepresentation": "RESTexample"
    }
  ]
}

Код ответа

200