JavaScript SDK monday code udostępnia przydatne narzędzia dla deweloperów, którzy chcą tworzyć i hostować bezpieczne aplikacje za pomocą monday code oraz płynnie integrować je z platformą monday.com. Obecnie zawiera sześć metod:

• storage
• secure storage
• environment variables manager
• secrets manager
• logger
• queue

W tym dokumencie opisujemy każdą dostępną metodę, jej parametry i powiązane przykłady kodu. SDK znajdziesz też tutaj.

Zainstaluj SDK

Możesz zainstalować JavaScript SDK monday code za pomocą npm install:

npm i @mondaycom/apps-sdk

Storage

Metoda storage przechowuje dane klientów Twojej aplikacji. Dane są bezpiecznie przechowywane i logicznie odseparowane. Oznacza to, że są podzielone na mniejsze kategorie na tym samym urządzeniu, co ułatwia przyznawanie lub blokowanie dostępu. Dane są odseparowane według accountId i app, dlatego dane zapisane przez jedno konto są niedostępne dla innych kont. Zapewnia to dodatkową warstwę zabezpieczeń.

Możesz używać tej metody w każdej aplikacji backendowej, nie tylko w aplikacjach hostowanych w monday code.

Metody storage mają następujące limity:

• Maksymalna długość klucza: 256
• Limit przechowywania dla jednego klucza: 6 MB
• Limit współbieżności dla tokenu JWT: 12 żądań na sekundę

Parametry

Parametr	Typ	Opis	Wymagany	Obsługiwane metody
key	String	Klucz, pod którym można zapisać, pobrać lub usunąć zawartość.	Tak	set get search delete
value	Dowolny serializowalny obiekt	Wartość do zapisania.	Tak	set
shared	Boolean	`False`, jeśli dane nie są współdzielone między integracjami i widokami. Są dostępne tylko z poziomu aplikacji backendowych. To ustawienie domyślne. `True`, jeśli zapisane dane są dostępne zarówno z aplikacji frontendowych, jak i backendowych.	Nie	set get delete
previousVersion	String	Ostatnia wersja zapisanej wartości dla danego klucza.	Nie	set
version	String	Nowa wersja zapisanej wartości.	Tak	set
cursor	String	Kursor używany do stronicowania dużych zbiorów wyników.	Nie	search
ttl	Number	Czas (w sekundach), po którym wartość zostanie usunięta i przestanie być dostępna. Maksymalna wartość wynosi 30 dni.	Nie	set

Inicjowanie

Parametr	Opis
ACCESS_TOKEN	Token dostępu użytkownika lub konta, na rzecz którego działa aplikacja (uzyskany w procesie OAuth). Przekazany z frontendu token sessionToken nie zadziała.

import { Storage } from '@mondaycom/apps-sdk';

const storage = new Storage('<ACCESS_TOKEN>');

Metody

Udostępniamy cztery metody do zarządzania pamięcią: set, get, search i delete.

set

Metoda storage.set zapisuje w bazie danych wartość value pod kluczem key.

const { version, success, error } = await storage.set(key, value, { previousVersion, shared });

get

Metoda storage.get zwraca z bazy danych zapisaną wartość przypisaną do klucza key.

const { value, version, success } = await storage.get(key, { shared });

search

Metoda storage.search pobiera zapisaną wartość na podstawie klucza key.

const { records, cursor, success } = await storage.search(key, { cursor });

delete

Metoda storage.delete usuwa z bazy danych zapisaną wartość przypisaną do klucza key.

const { success, error } = await storage.delete(key, { shared });

Bezpieczna pamięć masowa

Metoda secureStorage przechowuje poufne dane klientów w projektach monday code. Dane są bezpiecznie przechowywane i logicznie odseparowane. Oznacza to, że są podzielone na mniejsze kategorie na tym samym urządzeniu, co ułatwia przyznawanie lub blokowanie dostępu. Dane są odseparowane dla konkretnej aplikacji, dlatego dane zapisane przez jedną aplikację są niedostępne dla innych aplikacji. Zapewnia to dodatkową warstwę zabezpieczeń.

Jeśli wdrożysz projekt monday code, ta metoda automatycznie użyje rzeczywistej bezpiecznej pamięci masowej. Jeśli korzystasz z SDK lokalnie, użyje lokalnej bezpiecznej pamięci masowej albo lokalnej bazy mockującej, która naśladuje API udostępniane przez rzeczywistą bezpieczną pamięć masową. Lokalne dane nie zostaną zachowane, jeśli nie masz uprawnień do zapisywania plików na dysku.

Metody secureStorage mają następujące limity:

• Limit współbieżności: 7 żądań na sekundę
• Limit zapisów dla jednego klucza: 1 żądanie zapisu na sekundę dla tego samego klucza

Parametry

Parametr	Typ	Opis	Wymagany
key	String	Klucz, pod którym zostanie zapisana zawartość.	Tak
value	Dowolny	Serializowalna wartość do zapisania.	Tak

Inicjowanie

import { SecureStorage } from '@mondaycom/apps-sdk';

const secureStorage = new SecureStorage();

Metody

Udostępniamy trzy metody do zarządzania bezpieczną pamięcią masową: set, get i delete.

set

Metoda secureStorage.set zapisuje w bazie danych wartość value pod kluczem key.

Parametr	Typ	Opis	Wymagany
key	String	Klucz, pod którym zostanie zapisana zawartość.	Tak
value	Dowolny	Serializowalna wartość do zapisania. Jeśli wartość nie jest obiektem, zostanie opakowana w obiekt z kluczem value.	Tak

await secureStorage.set(key, value);

get

Metoda secureStorage.get zwraca z bazy danych zapisaną wartość przypisaną do klucza key.

const storedValue = await secureStorage.get(key);

delete

Metoda secureStorage.delete usuwa z bazy danych zapisaną wartość przypisaną do klucza key.

await secureStorage.delete(key);

Menedżer zmiennych środowiskowych

Metoda EnvironmentVariablesManager umożliwia odczytywanie zmiennych środowiskowych aplikacji we wdrożonym projekcie monday code. Aby ustawić zmienne, możesz użyć CLI.

Zmienne są przypisane do aplikacji, dlatego możesz uzyskać do nich dostęp we wszystkich wersjach aplikacji.

Jeśli korzystasz z SDK Node.js, zalecamy użycie menedżera zmiennych środowiskowych, aby wczytywać zmienne bez ponownego wdrażania serwera. Jeśli używasz innych języków, musisz ponownie wdrożyć usługę, aby nowe zmienne zaczęły działać.

Inicjowanie

import { EnvironmentVariablesManager } from '@mondaycom/apps-sdk';

// Initialize the environment variables manager without injecting env into `process.env`
let envManager = new EnvironmentVariablesManager();

// Initialize the environment variables manager and inject env into `process.env`
envManager = new EnvironmentVariablesManager({ updateProcessEnv: true });

Metody

Udostępniamy dwie metody do zarządzania zmiennymi środowiskowymi: get i getKeys.

get

Metoda envManager.get pobiera zmienne środowiskowe.

// Get cached environment variable
const cachedValue = envManager.get(key, { invalidate: false });

// Get the latest version of environment variable
const latestValue = envManager.get(key);

getKeys

Metoda envManager.getKeys pobiera klucze zmiennych środowiskowych.

// Get all cached environment variables keys
const cachedKeys = envManager.getKeys({ invalidate: false });

// Get all environment variables keys
const latestKeys = envManager.getKeys();

Menedżer sekretów

Metoda SecretsManager umożliwia odczytywanie sekretów aplikacji we wdrożonym projekcie monday code. Sekrety możesz ustawić w sekcji monday code w interfejsie Developer Center.

Metody SecretsManager mają następujące limity:

Inicjowanie

import { SecretsManager } from '@mondaycom/apps-sdk';

const secretsManager = new SecretsManager();

Metody

Udostępniamy dwie metody do zarządzania sekretami: get i getKeys.

get

Metoda get pobiera sekrety.

// Get cached secrets
const cachedValue = secretsManager.get(key, { invalidate: false });

// Get the latest version of a secret
const latestValue = secretsManager.get(key);

getKeys

Metoda getKeys pobiera klucze sekretów.

// Get all cached secrets keys
const cachedKeys = secretsManager.getKeys({ invalidate: false });

// Get all secrets keys
const latestKeys = secretsManager.getKeys();

Logger

logger to prosty sposób na zapisywanie komunikatów aplikacji w projekcie monday code. Dostęp do zapisanych komunikatów uzyskasz za pomocą CLI. Logi zapisane bez użycia logger nie są dostępne w CLI i mogą nie zostać prawidłowo oznaczone.

Inicjowanie

import { Logger } from '@mondaycom/apps-sdk';

const tag = 'my-app';
// tag will be added to every logged message
const logger = new Logger(tag);

Metody

Udostępniamy cztery metody do zarządzania zmiennymi środowiskowymi: info, warn, error i debug.

info

Metoda logger.info zapisuje komunikat informacyjny.

logger.info('info message');

warn

Metoda logger.warn zapisuje komunikat ostrzegawczy.

logger.warn('warn message');

debug

Metoda logger.debug zapisuje komunikat debugowania.

logger.debug('debug message');

error

Metoda logger.error zapisuje komunikat o błędzie.

// Stack trace will be logged as well if error is provided
logger.error('error message', { error: new Error('error') });

Kolejka

Obsługujemy kolejkę opartą na prostym modelu publikowania i subskrypcji (pub/sub). Pamiętaj, że każda wersja aplikacji: minor i major, ma własną kolejkę.

Inicjowanie

import { Queue } from "@mondaycom/apps-sdk";
const queue = new Queue();

Metody

Udostępniamy dwie metody do zarządzania kolejką: publishMessage i validateMessageSecret.

publishMessage

Metoda publishMessage publikuje wiadomość w kolejce. Przyjmuje parametr message w postaci ciągu znaków.

Po opublikowaniu wiadomości są wysyłane jako żądania POST do określonego endpointu aplikacji: /mndy-queue.

const messageContent = JSON.stringify({ content: "This is a message" })
const messageId = await queue.publishMessage(messageContent)

validateMessageSecret

Każda wiadomość zawiera losowy ciąg znaków secret w parametrach zapytania. Można go użyć do uwierzytelnienia żądania. Metoda validateMessageSecret sprawdza, czy wiadomość jest prawidłowa i czy żądanie do endpointu /mndy-queue zostało wywołane przez monday code.

Pamiętaj, że każda wersja aplikacji: minor i major, ma własny sekret wiadomości.

const queryParams = req.query;
if (!queue.validateMessageSecret(queryParams.secret))  {
  logger.info("Queue message received is not valid, since secret does not match. This message could come from an attacker.");
  throw new Error('not allowed');
}

Odbieranie wiadomości

Wszystkie wiadomości będą wysyłane do aplikacji jako żądania HTTP POST do endpointu /mndy-queue.

app.post(
    "/mndy-queue",
    async (req, res) => {
        try {
            const { body, query } = req;
            readQueueMessage({ body, query });
            return res.status(200).send({}); // return 200 to ACK the queue message
        } catch (err) {
            logger.error(err.error);
            return res.status(500).send({ message: "internal server error" });
        }
    }
);

Odpowiadanie na wiadomość

Po odebraniu wiadomości odpowiedz na żądanie statusem powodzenia (HTTP 200) w ciągu 10 minut. Jeśli nie odpowiesz w tym czasie lub zwrócisz błąd, spróbujemy wysłać element kolejki ponownie jeszcze 9 razy. Wiadomość zniknie po dziesiątej i ostatniej próbie.