Данные удалённой среды

С помощью код-плиток (в Дашбордах) и код-разделов (в Блокнотах) можно объединять данные из нескольких сред Ключ-АСТРОМ.

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

Аутентификация с помощью токена платформы: предназначена для личного использования. Используйте, когда нужно быстро протестировать и оперативно загрузить данные из удалённых сред.
Аутентификация клиента OAuth: предназначена для совместного использования. Используйте, чтобы обеспечить единообразную видимость данных для всех пользователей.

Начните с готовой плитки или раздела в Дашбордах или Блокнотах

Можно начать с готовой плитки или раздела при создании дашборда или блокнота, использующего данные из удалённой среды Ключ-АСТРОМ.

В дашборде или блокноте выберите Добавить. В верхней части меню есть поле поиска.

Прокрутите меню вниз до раздела Библиотека и выберите любую из следующих готовых код-плиток или разделов, чтобы добавить её в дашборд или блокнот:

Загрузка внешних данных
Данные удалённой среды через токен платформы
Данные удалённой среды через OAuth

Адаптируйте пример под свои нужды.

Аутентификация с помощью токена платформы

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

Описанный ниже пример кода на JavaScript использует хранилище учётных данных для безопасного хранения токена и токен платформы для аутентификации, обеспечивая надёжный и безопасный способ загрузки данных из удалённой среды Ключ-АСТРОМ.

Предварительные требования

Прежде чем создавать код для плитки дашборда или раздела блокнота:

Создайте токен платформы Ключ-АСТРОМ в среде, из которой хотите загружать данные. Подробнее см. Токены платформы.
Создайте запись в хранилище учётных данных Ключ-АСТРОМ в основной среде, чтобы сохранить токен платформы, который позже будет использоваться в код-плитке или разделе для аутентификации. Подробнее см. Хранилище учётных данных.
Разрешите внешние запросы.

Разрешите внешние запросы

Внешние запросы включают исходящие сетевые подключения из вашей среды Ключ-АСТРОМ к внешним сервисам. Они позволяют управлять доступом к публичным конечным точкам из AppEngine с помощью функций приложений и функций в Дашбордах, Блокнотах и Автоматизациях.

Перейдите в Настройки > Общие > Внешние запросы.
Выберите Новый шаблон хоста.
Добавьте доменные имена.
Выберите Добавить.

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

Например, можно добавить myenv8132.apps.astromkey.com, чтобы разрешить только эту среду, или использовать подстановочный знак, например *.apps.astromkey.com, чтобы разрешить все ваши среды Ключ-АСТРОМ сразу.

Подробнее о добавлении в список разрешённых см. Разрешение диапазонов IP, которые могут получить доступ к вашей среде.

Код

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

async function()

Это основная функция. Она вызывает fetchFromAstromkey (см. выше) с необходимыми параметрами.

fetchFromAstromkey(credentialId = "", url = "", query = "")

Чтобы загрузить данные из Ключ-АСТРОМ, эта функция:

Извлекает учётные данные из записи хранилища учётных данных в основном тенанте на основе заданного credentialId.
Выполняет вызов API на API вторичного/удалённого тенанта на основе учётных данных, а также параметров url и query, предоставленных основной функцией.

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

Основывайте свой код на примере ниже.

Читайте комментарии в примере кода для деталей.

Замените CREDENTIALS_VAULT-XXXXXXXXXXXXXXXX на свой идентификатор учётных данных.

Замените https://remote-environment-id.apps.astromkey.com/platform/storage/query/v1/query:execute?enrich:metric-metadata на свой URL.

Настройте запрос "fetch logs | limit 1" под свои нужды.

Запустите код в код-плитке (Дашборды) или код-разделе (Блокноты).

Если при запуске кода возникнут ошибки, они будут перехвачены и залогированы с префиксами [AstromkeyAuthError], [CredentialVaultError] или [ExecutionError] для упрощения отладки.

Начните с готовой плитки или раздела Можно начать с готовой плитки или раздела (Данные удалённой среды через токен платформы) при создании дашборда или блокнота, использующего данные из удалённой среды Ключ-АСТРОМ.

import { credentialVaultClient } from "@astromkey-sdk/client-classic-environment-v2";

/**
 * Execute a query against an Astromkey API with token retrieval inlined.
 * @param {string} credentialId - The ID of the credential vault entry.
 * @param {string} url - The API endpoint URL.
 * @param {string} query - The query to execute.
 * @returns {Promise<any>} - The API response data.
 * @throws Will throw an error if any step fails.
 */
async function fetchFromAstromkey(credentialId, url, query) {
  if (!credentialId || !url || !query) {
    throw new Error("[ValidationError] Missing required parameters: credentialId, url, or query.");
  }

  try {
    // Retrieve the platform token from the credential vault.
    const { token } = await credentialVaultClient.getCredentialsDetails({
      id: credentialId,
    }).catch((error) => {
      console.error(`[CredentialVaultError] Failed to retrieve token: ${error.message}`);
      throw new Error("Unable to fetch platform token.");
    });

    if (!token) {
      throw new Error("[CredentialVaultError] Token is undefined or empty.");
    }

    // Perform the API request.
    const response = await fetch(url, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Accept: "application/json",
        Authorization: `Bearer ${token}`,
      },
      body: JSON.stringify({
        query,
        requestTimeoutMilliseconds: 60000,
        enablePreview: true,
      }),
    });

    if (!response.ok) {
      throw new Error(`[HTTPError] API call failed with status ${response.status}: ${response.statusText}`);
    }

    return await response.json();
  } catch (error) {
    console.error(`[FetchError] Query execution failed: ${error.message}`);
    throw new Error("Unable to execute query.");
  }
}

/**
 * Main function to fetch and return results from Astromkey.
 * @returns {Promise<any>} - The query result.
 */
export default async function() {
  const credentialId = "CREDENTIALS_VAULT-XXXXXXXXXXXXXXXX"; // Replace with your credential vault ID.
  const url = "https://remote-environment-id.apps.astromkey.com/platform/storage/query/v1/query:execute"; // Replace with API URL.
  const query = "fetch logs | limit 1"; // Replace with your query.

  try {
    const { result } = await fetchFromAstromkey(credentialId, url, query);
    return result;
  } catch (error) {
    console.error(`[MainFunctionError] ${error.message}`);
    return null; // Or handle as needed.
  }
}

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

Загрузка данных из удалённых сред через OAuth предназначена для совместного использования. Этот метод обеспечивает единообразную видимость данных для всех пользователей.

Описанный ниже пример кода на JavaScript использует хранилище учётных данных для безопасного хранения токена и OAuth для аутентификации, обеспечивая надёжный и безопасный способ загрузки данных из удалённой среды Ключ-АСТРОМ.