IKuznetsov: Новая страница: « == Данные удалённой среды == С помощью код-плиток (в '''Дашбордах''') и код-разделов (в '''Блокнотах''') можно объединять данные из нескольких сред Ключ-АСТРОМ. Для загрузки данных из удалённых сред доступны два механизма аутентификации: * '''Аутентификация с п...»

2026-09-28T20:36:41Z

Новая страница: « == Данные удалённой среды == С помощью код-плиток (в '''Дашбордах''') и код-разделов (в '''Блокнотах''') можно объединять данные из нескольких сред Ключ-АСТРОМ. Для загрузки данных из удалённых сред доступны два механизма аутентификации: * '''Аутентификация с п...»

Новая страница

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

<code>async function()</code>

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

<code>fetchFromAstromkey(credentialId = "", url = "", query = "")</code>

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

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

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

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

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

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

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

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

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

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

'''Начните с готовой плитки или раздела''' Можно начать с готовой плитки или раздела ('''Данные удалённой среды через токен платформы''') при создании дашборда или блокнота, использующего данные из удалённой среды Ключ-АСТРОМ.<pre>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.
}
}</pre>

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

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

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

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

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

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

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

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

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

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

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

<code>async function()</code>

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

<code>fetchFromAstromkey(credentialId = "", url = "", query = "")</code>

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

* Извлекает учётные данные из записи хранилища учётных данных в основном тенанте на основе заданного <code>credentialId</code>.
* Получает токен доступа для вторичного тенанта через '''SSO''', вызывая функцию <code>authenticateToAstromkey</code>.
* Выполняет вызов '''API''' на API вторичного/удалённого тенанта на основе ранее полученного значения <code>accessToken</code>, а также параметров <code>url</code> и <code>query</code>, предоставленных основной функцией.

<code>authenticateToAstromkey(clientId = '', clientSecret = '')</code>

Для аутентификации через '''SSO''' эта функция:

* Принимает два параметра: <code>clientId</code> и <code>clientSecret</code>.
* Запрашивает токен доступа на основе исходных параметров функции и набора областей действия, определённых внутри функции.
* В случае успеха возвращает полученный токен доступа из конечной точки '''SSO''' Ключ-АСТРОМ.

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

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

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

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

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

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

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

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

'''Начните с готовой плитки или раздела''' Можно начать с готовой плитки или раздела ('''Данные удалённой среды через OAuth''') при создании дашборда или блокнота, использующего данные из удалённой среды Ключ-АСТРОМ.<pre>import { credentialVaultClient } from "@astromkey-sdk/client-classic-environment-v2";

/**
* Authenticate to Astromkey SSO using client credentials.
* @param {string} clientId - The client ID for authentication.
* @param {string} clientSecret - The client secret for authentication.
* @returns {Promise<string>} - The access token.
* @throws Will throw an error if authentication fails.
*/
async function authenticateToAstromkey(clientId, clientSecret) {
if (!clientId || !clientSecret) {
throw new Error("[ValidationError] Missing clientId or clientSecret for SSO authentication.");
}

const scopes = [
"environment-api",
"storage:buckets:read",
"storage:bizevents:read",
"storage:logs:read",
"storage:metrics:read",
"storage:entities:read",
].join(" ");

try {
const response = await fetch("https://sso.astromkey.com/sso/oauth2/token", {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded" },
body: `grant_type=client_credentials&client_id=${clientId}&client_secret=${clientSecret}&scopes=${scopes}`,
});

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

const { access_token: accessToken } = await response.json();
if (!accessToken) {
throw new Error("[SSOError] Access token not received.");
}

return accessToken;
} catch (error) {
console.error(`[AstromkeyAuthError] ${error.message}`);
throw error;
}
}

/**
* Fetch data from Astromkey using a query.
* @param {string} credentialId - The credential vault ID.
* @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 one or more required parameters: credentialId, url, or query.");
}

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

if (!clientId || !clientSecret) {
throw new Error("[CredentialVaultError] Missing clientId or clientSecret from the retrieved credentials.");
}

// Authenticate and get an access token.
const accessToken = await authenticateToAstromkey(clientId, clientSecret);

// Perform the API request.
const response = await fetch(url, {
method: "POST",
headers: {
"Content-Type": "application/json",
Accept: "application/json",
Authorization: `Bearer ${accessToken}`,
},
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] ${error.message}`);
throw error;
}
}

/**
* Main function to execute a query and return results from Astromkey.
* @returns {Promise<any>} - The query result.
*/
export default async function fetchAstromkeyData() {
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; // Return null or handle gracefully.
}
}</pre>

Данные удалённой среды - История изменений