Interfejsy API tagowania po stronie serwera

W tym dokumencie opisujemy interfejsy API do tagowania po stronie serwera.

---

addEventCallback

Rejestruje funkcję wywołania zwrotnego, która zostanie wywołana po zakończeniu zdarzenia. Funkcja wywołania zwrotnego zostanie wywołana po wykonaniu wszystkich tagów dla danego zdarzenia. Do funkcji wywołania zwrotnego przekazywane są 2 wartości: identyfikator kontenera, który wywołuje funkcję, oraz obiekt zawierający informacje o zdarzeniu.

Gdy ten interfejs API jest używany w tagu, jest powiązany z bieżącym zdarzeniem. Gdy ten interfejs API jest używany w kliencie, musi być powiązany z konkretnym zdarzeniem za pomocą funkcji bindToEvent interfejsu API runContainer. Aby dowiedzieć się więcej, zapoznaj się z przykładem.

Składnia

const addEventCallback = require('addEventCallback');

addEventCallback((containerId, eventData) => {
  // Take some action based on the event data.
});

Parametry

Parametr	Typ	Opis
callback	function	Funkcja do wywołania na końcu zdarzenia.

Obiekt eventData zawiera te dane:

Nazwa klucza	Typ	Opis
tags	Tablica	Tablica obiektów danych tagów. Każdy tag, który został uruchomiony podczas zdarzenia, będzie miał w tym tablicy swój wpis. Obiekt danych tagu zawiera identyfikator tagu (id), jego stan wykonania (status) i czas wykonania (executionTime). Dane tagu obejmują też dodatkowe metadane tagu skonfigurowane w tagu.

Przykład

W kliencie:

const addEventCallback = require('addEventCallback');
const claimRequest = require('claimRequest');
const extractEventsFromMpv1 = require('extractEventsFromMpv1');
const logToConsole = require('logToConsole');
const returnResponse = require('returnResponse');
const runContainer = require('runContainer');

claimRequest();

const events = extractEventsFromMpv1();
let eventsCompleted = 0;
events.forEach((evt, i) => {
  runContainer(evt, /* onComplete= */ (bindToEvent) => {
    bindToEvent(addEventCallback)((containerId, eventData) => {
      logToConsole('Event Number: ' + i);
      eventData.tags.forEach((tag) => {
        logToConsole('Tag ID: ' + tag.id);
        logToConsole('Tag Status: ' + tag.status);
        logToConsole('Tag Execution Time: ' + tag.executionTime);
      });
    });
    if (events.length === ++eventsCompleted) {
      returnResponse();
    }
  });
});

W tagu:

const addEventCallback = require('addEventCallback');

addEventCallback((containerId, eventData) => {
  // This will be called at the end of the current event.
});

Powiązane uprawnienia

read_event_metadata

---

callLater

Zaplanuj wywołanie funkcji do wykonania asynchronicznie. Funkcja zostanie wywołana po zwróceniu bieżącego kodu. Jest to równoważne z setTimeout(<function>, 0).

Przykład

const callLater = require('callLater');
const logToConsole = require('logToConsole');

callLater(() => {
  logToConsole('Logged asynchronously');
});

Składnia

callLater(function)

Parametry

Parametr	Typ	Opis
function	function	Funkcja do wywołania.

Powiązane uprawnienia

Brak.

---

claimRequest

Aby zgłosić żądanie, użyj tego interfejsu API w kliencie. Po zgłoszeniu żądania kontener nie uruchamia dodatkowych klientów.

Ten interfejs API zwraca wyjątek, jeśli zostanie wywołany w tagu lub zmiennej. Ten interfejs API zgłasza wyjątek, jeśli zostanie wywołany po zwróceniu klienta (np. w niesynchronizowanym wywołaniu zwrotnym, takim jak callLater lub funkcja runContainer onComplete).

Klient powinien zgłosić żądanie za pomocą tego interfejsu API przed wywołaniem interfejsu runContainer.

Przykład

const claimRequest = require('claimRequest');

claimRequest();

Składnia

claimRequest();

Powiązane uprawnienia

Brak.

---

computeEffectiveTldPlusOne

Zwraca skuteczną domenę najwyższego poziomu + 1 (eTLD+1) danej domeny lub adresu URL. Domena eTLD+1 jest obliczana na podstawie oceny domeny pod kątem reguł listy domen publicznych. eTLD + 1 to zwykle domena najwyższego poziomu, w której możesz ustawić plik cookie.

Jeśli argument jest null lub nieokreślony, zwracana jest jego wartość niezmieniona. W przeciwnym razie argument jest przekształcany w ciąg znaków. Jeśli argument nie jest prawidłową domeną lub adresem URL, zwracany jest pusty ciąg. Jeśli serwer nie może pobrać listy sufiksów publicznych, wartość argumentu jest zwracana bez zmian.

Przykład

const computeEffectiveTldPlusOne = require('computeEffectiveTldPlusOne');

// Returns 'example.co.uk'
computeEffectiveTldPlusOne('analytics.example.co.uk');

// Returns 'example.co.uk'
computeEffectiveTldPlusOne('https://analytics.example.co.uk/path');

Składnia

computeEffectiveTldPlusOne(domainOrUrl);

Parametry

Parametr	Typ	Opis
domainOrUrl	ciąg znaków	Domena lub adres URL, na podstawie których ma zostać obliczona eTLD+1.

Powiązane uprawnienia

Brak.

---

createRegex

Tworzy nowy obiekt regex i zwraca go w obiekcie. Nie możesz bezpośrednio uzyskać dostępu do wyrażenia regularnego. Możesz jednak przekazać go do interfejsu API testRegex, String.replace(), String.match() i String.search().

Zwraca wartość null, jeśli wyrażenie regularne jest nieprawidłowe lub Re2 jest niedostępny na serwerze.

Ten interfejs API korzysta z implementacji Re2. Obraz Dockera serwera musi być w wersji 2.0.0 lub nowszej.

Przykład

const createRegex = require('createRegex');

const domainRegex = createRegex('\\w+\\.com', 'i');

// Returns '/foobar'
'example.com/foobar'.replace(domainRegex, '');

Składnia

createRegex(pattern, flags);

Parametry

Parametr	Typ	Opis
pattern	ciąg znaków	Tekst wyrażenia regularnego.
flags	ciąg znaków	Opcjonalny ciąg znaków zawierający flagi dla tworzonego wyrażenia regularnego. Obsługiwane są opcje „g” (globalna) i „i” (bez rozróżniania wielkości liter). Wszystkie pozostałe znaki są ignorowane.

Powiązane uprawnienia

Brak.

Minimalna wersja obrazu

2.0.0

---

decodeUri

Dekoduje wszystkie zakodowane znaki w podanym identyfikatorze URI. Zwraca ciąg tekstowy, który reprezentuje odkodowany identyfikator URI. Zwraca wartość undefined, gdy otrzyma nieprawidłowy argument.

Przykład

const decodeUri = require('decodeUri');

const decodedUrl = decodeUri(data.encodedUrl);
if (decodedUrl) {
  // ...
}

Składnia

decodeUri(encoded_uri);

Parametry

Parametr	Typ	Opis
encoded_uri	ciąg znaków	Identyfikator URI zakodowany za pomocą funkcji encodeUri() lub w inny sposób.

Powiązane uprawnienia

Brak.

---

decodeUriComponent

Dekoduje wszystkie zakodowane znaki w podanym komponencie URI. Zwraca ciąg reprezentujący odkodowany komponent identyfikatora URI. Zwraca wartość undefined, gdy otrzyma nieprawidłowe dane wejściowe.

Przykład

const decodeUriComponent = require('decodeUriComponent');

const decodedQuery = decodeUriComponent(data.query);
if (decodedQuery) {
  // ...
}

Składnia

decodeUriComponent(encoded_uri_component);

Parametry

Parametr	Typ	Opis
encoded_uri_component	ciąg znaków	Komponent identyfikatora URI zakodowany przez encodeUriComponent() lub w inny sposób.

Powiązane uprawnienia

Brak.

---

encodeUri

Zwraca zakodowany identyfikator URI, stosując ucieczki znaków specjalnych. Zwraca ciąg znaków reprezentujący podany ciąg znaków zakodowany jako identyfikator URI.

Przykład

const encodeUri = require('encodeUri');
const sendHttpGet = require('sendHttpGet');

sendHttpGet('https://www.example.com/' + encodeUri(pathInput));

Składnia

encodeUri(uri);

Parametry

Parametr	Typ	Opis
uri	ciąg znaków	Pełny identyfikator URI.

Powiązane uprawnienia

Brak.

---

encodeUriComponent

Zwraca zakodowany identyfikator URI, stosując ucieczki znaków specjalnych. Zwraca ciąg znaków reprezentujący podany ciąg znaków zakodowany jako identyfikator URI.

Przykład

const encodeUriComponent = require('encodeUriComponent');
const sendHttpGet = require('sendHttpGet');

sendHttpGet('https://www.example.com/?' + encodeUriComponent(queryInput));

Składnia

encodeUriComponent(str);

Parametry

Parametr	Typ	Opis
str	ciąg znaków	Składnik adresu URI.

Powiązane uprawnienia

Brak.

---

extractEventsFromMpv1

Przekształca przychodzące żądanie Measurement Protocol w wersji 1 w listę zdarzeń w formacie schematu zjednoczonego. Zwraca listę wyodrębnionych zdarzeń. Wyrzuca błąd, jeśli żądanie ma nieprawidłowy format.

Przykład

const extractEventsFromMpv1 = require('extractEventsFromMpv1');
const isRequestMpv1 = require('isRequestMpv1');

if (isRequestMpv1()) {
  const events = extractEventsFromMpv1();
  for (let i = 0; i < events.length; ++i) {
    const event = events[i];
    // Process event.
  }
}

Składnia

extractEventsFromMpv1();

Powiązane uprawnienia

Wymaga uprawnień read_request. Uprawnienia muszą być skonfigurowane tak, aby zezwalały na dostęp do co najmniej:

• body
• query parameters

---

extractEventsFromMpv2

Przekształca przychodzące żądanie Measurement Protocol V2 w listę zdarzeń w formacie schematu zjednoczonego. Zwraca listę wyodrębnionych zdarzeń. Wyrzuca błąd, jeśli żądanie ma nieprawidłowy format.

Przykład

const extractEventsFromMpv2 = require('extractEventsFromMpv2');
const isRequestMpv2 = require('isRequestMpv2');

if (isRequestMpv2()) {
  const events = extractEventsFromMpv2();
  for (let i = 0; i < events.length; ++i) {
    const event = events[i];
    // Process event.
  }
}

Składnia

extractEventsFromMpv2();

Powiązane uprawnienia

Wymaga uprawnień read_request. Uprawnienia muszą być skonfigurowane tak, aby zezwalały na dostęp do co najmniej:

• body
• query parameters

---

fromBase64

Dekoduje ciąg tekstowy zakodowany w formacie Base64. Zwraca undefined, jeśli dane wejściowe są nieprawidłowe.

Składnia

fromBase64(base64EncodedString);

Parametry

Parametr	Typ	Opis
base64EncodedString	ciąg znaków	Ciąg zakodowany w formacie Base64.

Przykład

const fromBase64 = require('fromBase64');

const greeting = fromBase64('aGVsbG8=');
if (greeting === 'hello') {
  // ...
}

Powiązane uprawnienia

Brak.

---

generateRandom

Zwraca losową liczbę (liczbę całkowitą) z podanego zakresu.

Przykład

const generateRandom = require('generateRandom');

const randomValue = generateRandom(0, 10000000);

Składnia

generateRandom(min, max);

Parametry

Parametr	Typ	Opis
min	liczba	Minimalna potencjalna wartość zwracanej liczby całkowitej (włącznie).
max	liczba	Maksymalna potencjalna wartość zwracanej liczby całkowitej (włącznie).

Powiązane uprawnienia

Brak.

---

getAllEventData

Zwraca kopię danych zdarzenia.

Składnia

getAllEventData();

Powiązane uprawnienia

read_event_data

---

getClientName

Zwraca ciąg tekstowy zawierający nazwę bieżącego klienta.

Składnia

getClientName();

Powiązane uprawnienia

read_container_data

---

getContainerVersion

Zwraca obiekt zawierający dane o bieżącym kontenerze. Zwrócony obiekt będzie zawierać te pola:

{
  containerId: string,
  debugMode: boolean,
  environmentName: string,
  environmentMode: boolean,
  previewMode: boolean,
  version: string,
}

Przykład

const getContainerVersion = require('getContainerVersion');

const containerVersion = getContainerVersion();
const containerId = containerVersion['containerId'];
const isDebug = containerVersion['debugMode'];

Składnia

getContainerVersion();

Powiązane uprawnienia

read_container_data

---

getCookieValues

Zwraca tablicę zawierającą wartości wszystkich plików cookie o danej nazwie.

Przykład

const getCookieValues = require('getCookieValues');

const lastVisit = getCookieValues('lastVisit')[0];
if (lastVisit) {
  // ...
}

Składnia

getCookieValues(name[, noDecode]);

Parametry

Parametr	Typ	Opis
name	ciąg znaków	Nazwa pliku cookie.
noDecode	wartość logiczna	Jeśli true, wartości plików cookie nie zostaną odkodowane przed zwróceniem. Domyślna wartość to false.

Powiązane uprawnienia

get_cookies

---

getEventData

Zwraca kopię wartości na podanej ścieżce w danych zdarzenia. Zwraca undefined, jeśli nie ma danych o zdarzeniu lub nie ma wartości na danej ścieżce.

Przykład

const getEventData = require('getEventData');

const campaignId = getEventData('campaign.id');
const itemId = getEventData('items.0.id');
const referrer = getEventData('page_referrer');

Parametry

Parametr	Typ	Opis
keyPath	dowolny	Ścieżka klucza, w której poszczególne komponenty są rozdzielone kropkami. Komponentami ścieżki mogą być klucze w obiekcie lub indeksy w tablicy. Jeśli keyPath nie jest ciągiem znaków, jest on przekształcany w ciąg znaków.

Składnia

getEventData(keyPath);

Powiązane uprawnienia

read_event_data

---

getGoogleAuth

Zwraca obiekt autoryzacji, który po użyciu z sendHttpGet lub sendHttpRequest będzie zawierać nagłówek autoryzacji dla interfejsów Google Cloud APIs. Ten interfejs API używa domyślnego uwierzytelniania aplikacji do automatycznego znajdowania danych logowania w środowisku serwera.

Przykład

const getGoogleAuth = require('getGoogleAuth');
const logToConsole = require('logToConsole');
const sendHttpGet = require('sendHttpGet');

const auth = getGoogleAuth({
  scopes: ['https://www.googleapis.com/auth/datastore']
});

sendHttpGet(
  'https://firestore.googleapis.com/v1/projects/my-project/databases/(default)/documents/collection/document',
  {authorization: auth}
).then((result) => {
  if (result.statusCode >= 200 && result.statusCode < 300) {
    logToConsole('Result: ' + result.body);
    data.gtmOnSuccess();
  } else {
    data.gtmOnFailure();
  }
});

Składnia

getGoogleAuth(scopes);

Parametry

Parametr	Typ	Opis
scopes	Tablica	Tablica zakresów interfejsu API Google OAuth 2.0, do których ma być wysłane żądanie dostępu.

Powiązane uprawnienia

Wymaga uprawnień use_google_credentials. Uprawnienie musi być skonfigurowane z co najmniej 1 dozwolonym zakresem.

---

getGoogleScript

Pobiera zasób z wstępnie zdefiniowanego zbioru skryptów Google i zwraca obietnice z tym skryptem i powiązanymi z nim metadanymi do pamięci podręcznej.

Obietnica zostanie przekształcona w obiekt zawierający 2 klucze: script i metadata. Jeśli żądanie nie powiedzie się, obietnica zostanie odrzucona za pomocą klucza reason.

Obiekt metadata będzie zawierać następujące metadane dotyczące pamięci podręcznej na podstawie nagłówków odpowiedzi zasobu. Każde pole będzie obecne tylko wtedy, gdy odpowiedni nagłówek będzie obecny w odpowiedzi zasobu.

{
  'cache-control': string,
  'expires': string,
  'last-modified': string,
}

Przykład

const getGoogleScript = require('getGoogleScript');

getGoogleScript('ANALYTICS').then((result) => {
  // Operate on result.script and result.metadata here.
});

Składnia

getGoogleScript(script[, options]);

Parametry

Parametr	Typ	Opis
script	ciąg znaków	Nazwa skryptu. Obsługiwane systemy pisma to: 'ANALYTICS', 'GTAG' i 'GTM'. Opcja 'ANALYTICS'pobiera skrypt Google Analytics z adresu https://www.google-analytics.com/analytics.js. Opcja 'GTAG' pobiera skrypt globalnego tagu witryny (gtag.js) z https://www.googletagmanager.com/gtag/js. Opcja 'GTM' pobiera skrypt Menedżera tagów Google z adresu https://www.googletagmanager.com/gtm.js.
options	object	Opcjonalne opcje żądania. Poniżej znajdziesz obsługiwane opcje.

Opcje

Opcja	Typ	Opis
id	ciąg znaków	Dotyczy 'GTAG' z identyfikatorem pomiaru gtag i 'GTM' z identyfikatorem kontenera internetowego (np. GTM-XXXX).
debug	dowolny	Jeśli wartość to prawda, żąda i zwraca wersję debugową skryptu pomiarowego.
timeout	liczba	Czas oczekiwania na żądanie w milisekundach. Wartości niedodatnie są ignorowane. Jeśli żądanie zostanie anulowane, wywołanie zostanie wywołane z wartością undefined dla wartości skryptu i {} dla obiektu metadanych.

Nierozpoznane klucze opcji są ignorowane.

Powiązane uprawnienia

Wymaga uprawnień send_http. Uprawnienia muszą być skonfigurowane tak, aby zezwalały na dostęp do co najmniej:

• Zezwól na używanie domen Google

---

getRemoteAddress

Zwraca ciąg znaków adresu IP, z którego pochodzi żądanie, np. 12.345.67.890 w przypadku adresu IPv4 lub 2001:0db8:85a3:0:0:8a2e:0370:7334 w przypadku adresu IPv6. Aby to zrobić, odczytuje nagłówki żądania, takie jak Forwarded i X-Forwarded-For. Uwaga: ten interfejs API dokłada wszelkich starań, aby wykryć adres IP źródłowy, ale nie może zagwarantować, że wynik będzie dokładny.

Składnia

getRemoteAddress();

Powiązane uprawnienia

Wymaga uprawnień read_request. Uprawnienia muszą być skonfigurowane tak, aby zezwalały na dostęp do co najmniej:

• Nagłówki Forwarded i X-Forwarded-For
• Zdalny adres IP

---

getRequestBody

Zwraca treść żądania jako ciąg tekstowy, jeśli jest obecny, lub undefined w przeciwnym razie.

Składnia

getRequestBody();

Powiązane uprawnienia

read_request

---

getRequestHeader

Zwraca wartość nagłówka żądania o nazwie jako ciąg znaków (jeśli występuje) lub undefined (w przeciwnym razie). Jeśli nagłówek jest powtarzany, zwrócone wartości są łączone za pomocą funkcji ', '.

Przykład

const getRequestHeader = require('getRequestHeader');

const host = getRequestHeader('host');

Składnia

getRequestHeader(headerName);

Parametry

Parametr	Typ	Opis
headerName	ciąg znaków	Nazwa nagłówka. Wielkość liter w tej wartości nie ma znaczenia.

Powiązane uprawnienia

read_request

---

getRequestMethod

Zwraca metodę żądania, np. 'GET' lub 'POST', jako ciąg znaków.

Przykład

const getRequestMethod = require('getRequestMethod');

if (getRequestMethod() === 'POST') {
  // Handle the POST request here.
}

Składnia

getRequestMethod();

Powiązane uprawnienia

Brak.

---

getRequestPath

Zwraca ścieżkę żądania bez ciągu zapytania. Jeśli np. adres URL to '/foo?id=123', zwraca to '/foo'. Automatycznie usuwa z ścieżki prefiks adresu URL kontenera serwera. Jeśli na przykład adres URL kontenera serwera to https://example.com/analytics, a ścieżka żądania to '/analytics/foo', zwracana jest wartość '/foo'.

Przykład

const getRequestPath = require('getRequestPath');

const requestPath = getRequestPath();
if (requestPath === '/') {
  // Handle a request for the root path.
}

Składnia

getRequestPath();

Powiązane uprawnienia

read_request

---

getRequestQueryParameter

Zwraca odkodowaną wartość parametru ciągu zapytania o określonej nazwie jako ciąg znaków lub undefined, jeśli parametr nie jest obecny. Jeśli parametr jest powtórzony w składniku zapytania, zwracana jest pierwsza wartość, która się w nim pojawia.

Przykład

const getRequestQueryParameter = require('getRequestQueryParameter');

const query = getRequestQueryParameter('query');
if (query) {
  // Process query here.
}

Składnia

getRequestQueryParameter(name);

Parametry

Parametr	Typ	Opis
name	ciąg znaków	Nazwa parametru zapytania.

Powiązane uprawnienia

read_request

---

getRequestQueryParameters

Zwraca parametry zapytania przychodzącego żądania HTTP jako obiekt, który mapuje nazwy parametrów zapytania na odpowiednie wartości. Nazwy i wartości parametrów są dekodowane.

Przykład

const getRequestQueryParameters = require('getRequestQueryParameters');

const queryParameters = getRequestQueryParameters();
if (queryParameters['search']) {
  // Handle the search query here.
  const maxResults = queryParameters['max_results'];
}

Składnia

getRequestQueryParameters();

Powiązane uprawnienia

read_request

---

getRequestQueryString

Zwraca zapytanie jako ciąg znaków bez wiodącego znaku zapytania lub pusty ciąg znaków, jeśli adres URL żądania nie zawiera ciągu zapytania.

Przykład

const getRequestQueryString = require('getRequestQueryString');

const queryString = getRequestQueryString();
if (queryString !== '') {
  // Handle the query string.
}

Składnia

getRequestQueryString();

Powiązane uprawnienia

read_request

---

getTimestamp

Wycofany. Używaj funkcji getTimestampMillis.

Zwraca liczbę, która reprezentuje bieżący czas w milisekundach od początku epoki Unixa, zwracany przez funkcję Date.now().

Składnia

getTimestamp();

Powiązane uprawnienia

Brak.

---

getTimestampMillis

Zwraca liczbę, która reprezentuje bieżący czas w milisekundach od początku epoki Unixa, zwracany przez funkcję Date.now().

Składnia

getTimestampMillis();

Powiązane uprawnienia

Brak.

---

getType

Zwraca ciąg znaków opisujący typ danej wartości.

Typ danych	Zwracana wartość
ciąg znaków	'string'
liczba	'number'
wartość logiczna	'boolean'
null	'null'
undefined	'undefined'
Tablica	'array'
Obiekt	'object'
Funkcja	'function'

Przykład

const getType = require('getType');

const type = getType(value);
if (type === 'string') {
  // Handle string input.
} else if (type === 'number') {
  // Handle numeric input.
} else {
  logToConsole('Unsupported input type: ', type);
}

Składnia

getType(value);

Parametry

Parametr	Typ	Opis
value	dowolny	Wartość wejściowa.

Powiązane uprawnienia

Brak.

---

hmacSha256

Oblicza zakodowany podpis za pomocą kodu uwierzytelniania wiadomości opartego na skrótach (HMAC) z SHA-256. Domyślnie używane jest kodowanie base64url.

Aby korzystać z tego interfejsu API, ustaw zmienną środowiskową SGTM_CREDENTIALS na serwerze na ścieżkę do zaszyfrowanego w formacie UTF-8 pliku klucza JSON o takim formacie:

{
  "keys": {
    "key1": "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXowMTIzNDU2Nzg5",
    "key2": "OTg3NjU0MzIxMHp5eHd2dXRzcnFwb25tbGtqaWhnZmVkY2Jh",
    ...
  }
}

Wartości to klucze HMAC zakodowane w formacie base64. Tekst w formacie JSON nie może zaczynać się znacznikiem kolejności bajtów.

Przykład

const hmacSha256 = require('hmacSha256');
const toBase64 = require('toBase64');

const header = toBase64('{"alg":"HS256","typ":"JWT"}', {urlEncoding: true});
const claim = toBase64('{"sub":"1234567890","iat":1698164946}', {urlEncoding: true});
const signature = hmacSha256(header + '.' + claim, 'key1');

const jwt = header + "." + claim + '.' + signature;

Składnia

hmacSha256(data, keyId, options)

Parametry

Parametr	Typ	Opis
data	ciąg znaków	Dane do obliczenia wartości HMAC.
keyId	ciąg znaków	Identyfikator klucza z pliku klucza JSON odwołującego się do klucza, którego chcesz użyć.
options	object	Opcjonalna konfiguracja interfejsu API. (patrz Opcje poniżej).

Opcje

Opcja	Typ	Opis
outputEncoding	ciąg znaków	Określa format kodowania wartości zwracanej. Obsługiwane formaty to hex, base64 i base64url. Jeśli nie zostanie podany, przyjmuje domyślnie base64url.

Powiązane uprawnienia

use_custom_private_keys

Minimalna wersja obrazu

1.0.0

---

isRequestMpv1

Zwraca wartość true, jeśli żądanie jest żądaniem Measurement Protocol w wersji 1, a w przeciwnym razie – wartość false.

Przykład

const isRequestMpv1 = require('isRequestMpv1');

if (isRequestMpv1()) {
  // Handle Measurement Protocol V1 request.
  const events = extractEventsFromMpv1();
}

Składnia

isRequestMpv1();

Powiązane uprawnienia

Brak.

---

isRequestMpv2

Zwraca wartość true, jeśli żądanie jest żądaniem Measurement Protocol w wersji 2, a w przeciwnym razie zwraca wartość false.

Przykład

const isRequestMpv2 = require('isRequestMpv2');

if (isRequestMpv2()) {
  // Handle Measurement Protocol V2 request.
  const events = extractEventsFromMpv2();
}

Składnia

isRequestMpv2();

Powiązane uprawnienia

Brak.

---

logToConsole

Zapisuje argumenty w konsoli.

Te logi są widoczne w Eksploratorze logów w konsoli Google Cloud. W Eksploratorze logów uruchom zapytanie logName =~ "stdout", aby wyświetlić wpisy w logu utworzone przez ten interfejs API.

Przykład

const logToConsole = require('logToConsole');

const that = 123;
const those = { ... };
logToConsole('that is: ', that, ' and those is: ', those);

Składnia

logToConsole(argument1[, argument2, ...]);

Parametry

Interfejs API przyjmuje co najmniej 1 argument, który w razie potrzeby jest konwertowany na ciąg znaków i rejestrowany w konsoli.

Powiązane uprawnienia

logging

---

makeInteger

Przekształca podawaną wartość na liczbę (liczbę całkowitą).

Składnia

makeInteger(value);

Parametry

Parametr	Typ	Opis
value	dowolny typ	Wartość do przekonwertowania.

Powiązane uprawnienia

Brak.

---

makeNumber

Przekształca podawaną wartość na liczbę.

Składnia

makeNumber(value);

Parametry

Parametr	Typ	Opis
value	dowolny typ	Wartość do przekonwertowania.

Powiązane uprawnienia

Brak.

---

makeString

Zwraca podana wartość jako ciąg tekstowy.

Składnia

makeString(value);

Parametry

Parametr	Typ	Opis
value	dowolny typ	Wartość do przekonwertowania.

Powiązane uprawnienia

Brak.

---

makeTableMap

Konwertuje prosty obiekt tabeli z 2 kolumnami na Map. Służy on do zmiany pola szablonu SIMPLE_TABLE z 2 kolumnami na format łatwiejszy do zarządzania.

Funkcja ta może na przykład konwertować obiekt tabeli:

[
  {'key': 'k1', 'value': 'v1'},
  {'key': 'k2', 'value': 'v2'}
]

na mapie:

{
  'k1': 'v1',
  'k2': 'v2'
}

Zwraca obiekt: przekształcone Map pary klucz-wartość zostały dodane do obiektu lub null w przeciwnym razie.

Składnia

makeTableMap(tableObj, keyColumnName, valueColumnName);

Parametry

Parametr	Typ	Opis
tableObj	Wyświetl listę	Obiekt tabeli do przekonwertowania. To lista map, w której każdy wiersz tabeli odpowiada jednemu elementowiMap. Każda nazwa właściwości w obiekcie wiersza jest nazwą kolumny, a wartość właściwości jest wartością kolumny w wierszu.
keyColumnName	ciąg znaków	Nazwa kolumny, której wartości staną się kluczami w przekształconym pliku.Map
valueColumnName	ciąg znaków	Nazwa kolumny, której wartości staną się wartościami w konwertowanej kolumnie Map.

Powiązane uprawnienia

Brak.

---

parseUrl

Zwraca obiekt zawierający wszystkie elementy składowe danego adresu URL, podobnie jak obiekt URL.

Ten interfejs API zwróci wartość undefined w przypadku dowolnego nieprawidłowego adresu URL. W przypadku prawidłowo sformatowanych adresów URL pola, których nie ma w ciągu znaków adresu URL, będą miały wartość pustego ciągu znaków. W przypadku pola searchParams będzie to pusty obiekt.

Zwrócony obiekt będzie zawierać te pola:

{
  href: string,
  origin: string,
  protocol: string,
  username: string,
  password: string,
  host: string,
  hostname: string,
  port: string,
  pathname: string,
  search: string,
  searchParams: Object<string, (string|Array)>,
  hash: string,
}

Przykład

const parseUrl = require('parseUrl');

const urlObject = parseUrl('https://abc:[e-mail]:8080/foo?param=val%2Cue#bar');

Składnia

parseUrl(url);

Parametry

Parametr	Typ	Opis
url	ciąg znaków	Pełny adres URL, który zostanie przeanalizowany.

Powiązane uprawnienia

Brak.

---

returnResponse

Wyczyszcza odpowiedź, która została wcześniej ustawiona przez inne szablony za pomocą interfejsów API, które modyfikują odpowiedź, w tym setCookie, setPixelResponse, setResponseBody, setResponseHeader i setResponseStatus. Domyślnie kod stanu HTTP to 200, pusta treść i brak nagłówków.

Zalecamy używanie tego interfejsu API w ramach szablonu klienta.

Składnia

returnResponse();

Przykład

Zobacz przykład runContainer.

Powiązane uprawnienia

return_response

---

runContainer

Wykonuje logikę kontenera (zmiennych, reguł i tagów) w zakresie zdarzenia. Jeśli ten interfejs API zostanie wywołany podczas wykonywania kontenera, kontener zostanie uruchomiony ponownie.

Wywołania zwrotne onComplete i onStart otrzymują funkcję o nazwie bindToEvent. Użyj aplikacji bindToEvent, aby uruchomić interfejs API w kontekście zdarzenia. Więcej informacji znajdziesz w przykładzie addEventCallback.

Zalecamy używanie tego interfejsu API w ramach szablonu klienta.

Przykład

const returnResponse = require('returnResponse');
const runContainer = require('runContainer');

// Runs the container with a simple pageview event and then returns a response.
runContainer({'event_name': 'pageview'}, () => returnResponse());

Składnia

runContainer(event, onComplete, onStart);

Parametry

Parametr	Typ	Opis
event	object	Parametry zdarzenia.
onComplete	function	Funkcja wywoływana po zakończeniu działania wszystkich tagów.
onStart	function	Funkcja wywołania zwrotnego, która jest wywoływana natychmiast, zanim tagi zaczną się uruchamiać.

Powiązane uprawnienia

run_container

---

sendEventToGoogleAnalytics

Wysyła do Google Analytics pojedyncze zdarzenie za pomocą Common Event Data i zwraca obietnice, która jest obiektem z kluczem location lub odrzuca obiekt z kluczem reason. Miejsce docelowe, czyli Google Analytics 4, jest określane na podstawie identyfikatora pomiaru w danych zdarzenia.

Pole location ma wartość nagłówka location, jeśli ten nagłówek jest obecny.

Przykład

const logToConsole = require('logToConsole');
const sendEventToGoogleAnalytics = require('sendEventToGoogleAnalytics');
const setResponseHeader = require('setResponseHeader');
const setResponseStatus = require('setResponseStatus');

// Sends an event to Google Analytics and returns failure if the request did not
// succeed. Additionally, if the request resulted in a redirect request, the
// code nominates a redirect response to be returned.
sendEventToGoogleAnalytics(event).then((response) => {
  if (response.location) {
    setResponseHeader('location', response.location);
    setResponseStatus(302);
  } else {
    setResponseStatus(200);
  }
  data.gtmOnSuccess();
}).catch((error) => {
  logToConsole(error.reason);
  setResponseStatus(500);
  data.gtmOnFailure();
});

Składnia

sendEventToGoogleAnalytics(event);

Parametry

Parametr	Typ	Opis
event	object	Zdarzenie w formacie ujednoliconego schematu.

Powiązane uprawnienia

Wymaga uprawnień send_http. Uprawnienia muszą być skonfigurowane tak, aby zezwalały na dostęp do co najmniej:

• Zezwól na używanie domen Google

---

sendHttpGet

Wysyła żądanie HTTP GET do określonego adresu URL i zwraca obietnicę, która zwraca wynik po zakończeniu żądania lub po przekroczeniu limitu czasu.

Rozwiązany wynik to obiekt zawierający 3 klucze: statusCode, headers i body. Jeśli żądanie się nie powiedzie (np. nieprawidłowy adres URL, brak trasy do hosta, niepowodzenie negocjacji SSL itp.), obietnica zostanie odrzucona z powodem: {reason: 'failed'}. Jeśli opcja timeout została ustawiona, a prośba przekroczyła limit czasu, obietnica zostanie odrzucona z wiadomością: {reason: 'timed_out'}

Przykład

const sendHttpGet = require('sendHttpGet');

// Returns the response body as the value for a variable.
return sendHttpGet('https://example.com/item/' + data.itemId, {
  headers: {key: 'value'},
  timeout: 500,
}).then((result) => result.body, () => undefined);

Składnia

sendHttpGet(url[, options]);

Parametry

Parametr	Typ	Opis
url	ciąg znaków	Żądany adres URL.
options	object	Opcjonalne opcje prośby. (patrz Opcje poniżej).

Opcje

Opcja	Typ	Opis
headers	ciąg znaków	dodatkowe nagłówki żądania.
timeout	liczba	Czas oczekiwania (w milisekundach) przed przerwaniem żądania. Domyślna wartość to 15000.
authorization	object	Opcjonalny obiekt autoryzacji z wywołania do getGoogleAuth, który służy do uwzględniania nagłówków autoryzacji podczas wysyłania żądań do googleapis.com.

Powiązane uprawnienia

send_http

---

sendHttpRequest

Wysyła żądanie HTTP do określonego adresu URL i zwraca obietnice, która po zakończeniu żądania lub przekroczeniu limitu czasu zostaje rozwiązana z odpowiedzią.

Rozwiązany wynik to obiekt zawierający 3 klucze: statusCode, headers i body. Jeśli żądanie się nie powiedzie (np. nieprawidłowy adres URL, brak trasy do hosta, niepowodzenie negocjacji SSL itp.), obietnica zostanie odrzucona z powodem: {reason: 'failed'}. Jeśli opcja timeout została ustawiona, a prośba przekroczyła limit czasu, obietnica zostanie odrzucona z wiadomością: {reason: 'timed_out'}

Przykład

const sendHttpRequest = require('sendHttpRequest');
const setResponseBody = require('setResponseBody');
const setResponseHeader = require('setResponseHeader');
const setResponseStatus = require('setResponseStatus');

const postBody = 'interaction=click&campaign=promotion&medium=email';
// Sends a POST request and nominates response based on the response to the POST
// request.
sendHttpRequest('https://example.com/collect', {
  headers: {key: 'value'},
  method: 'POST',
  timeout: 500,
}, postBody).then((result) => {
  setResponseStatus(result.statusCode);
  setResponseBody(result.body);
  setResponseHeader('cache-control', result.headers['cache-control']);
});

Składnia

sendHttpRequest(url[, options[, body]]);

Parametry

Parametr	Typ	Opis
url	ciąg znaków	Żądany adres URL.
options	object	Opcjonalne opcje prośby. (patrz Opcje poniżej).
body	ciąg znaków	Opcjonalna treść żądania.

Opcje

Opcja	Typ	Opis
headers	ciąg znaków	dodatkowe nagłówki żądania.
method	object	Metoda żądania. Domyślna wartość to GET.
timeout	liczba	Czas oczekiwania (w milisekundach) przed przerwaniem żądania. Domyślna wartość to 15000.
authorization	object	Opcjonalny obiekt autoryzacji z wywołania do getGoogleAuth, który służy do uwzględniania nagłówków autoryzacji podczas wysyłania żądań do googleapis.com.

Powiązane uprawnienia

send_http

---

sendPixelFromBrowser

Wysyła do przeglądarki polecenie załadowania podanego adresu URL jako tagu <img>. Ten protokół poleceń jest obsługiwany w tagach internetowych Google Tag Manager dla GA4 i Google Analytics: zdarzenie GA. Musisz skonfigurować adres URL kontenera serwera. Więcej informacji znajdziesz w instrukcjach.

Ten interfejs API zwraca false, jeśli żądanie wejściowe nie obsługuje protokołu poleceń lub jeśli odpowiedź została już wyczyszczona. W przeciwnym razie interfejs API zwraca wartość true.

Przykład:

const sendPixelFromBrowser = require('sendPixelFromBrowser');

sendPixelFromBrowser('https://example.com/?id=123');

Składnia

sendPixelFromBrowser(url)

Parametry

Parametr	Typ	Opis
url	ciąg znaków	Adres URL do wysłania do przeglądarki.

Powiązane uprawnienia

send_pixel_from_browser

---

setCookie

Ustawia lub usuwa plik cookie z określonymi opcjami.

Aby usunąć plik cookie, należy ustawić plik cookie z tą samą ścieżką i domeną, z jaką został utworzony, oraz przypisać mu wartość expires, która jest w przeszłości, np. "Thu, 01 Jan 1970 00:00:00 GMT".

Pamiętaj, że aby odpowiedź została wysłana z powrotem do klienta, musisz wywołać metodę returnResponse.

Przykład

const setCookie = require('setCookie');

// Sets an httpOnly cookie with a max-age of 3600.
setCookie('cookieName', 'cookieValue', {'max-age': 3600, httpOnly: true});

Składnia

setCookie(name, value[, options[, noEncode]]);

Parametry

Parametr	Typ	Opis
name	ciąg znaków	Nazwa pliku cookie. Wielkość liter w nazwie nie ma znaczenia.
value	ciąg znaków	Wartość pliku cookie.
options	object	Opcjonalne atrybuty plików cookie:domain, expires, fallbackDomain, httpOnly, max-age, path, secure i sameSite. (patrz sekcja Opcje poniżej).
noEncode	wartość logiczna	Jeśli wartość to prawda, wartość pliku cookie nie zostanie zakodowana. Domyślna wartość to false.

Opcje

• domain: host, do którego zostanie wysłany plik cookie. Jeśli ustawisz specjalną wartość „auto”, host zostanie automatycznie policzony według tej strategii:

  • eTLD+1 nagłówka Forwarded (jeśli występuje).
  • eTLD+1 nagłówka X-Forwarded-Host (jeśli występuje).
  • eTLD+1 w nagłówku Host.

• expires: maksymalny okres ważności pliku cookie. Musi to być ciąg znaków z datą w formacie UTC, np. „So, 26 Oct 1985 08:21:00 GMT”. Jeśli ustawione są parametry expires i max-age, pierwszeństwo ma parametr max-age.

• httpOnly: uniemożliwia JavaScriptowi dostęp do pliku cookie, jeśli true.

• max-age: liczba sekund do wygaśnięcia pliku cookie. Wartość 0 lub ujemna spowoduje natychmiastowe wygaśnięcie pliku cookie. Jeśli ustawione są parametry expires i max-age, pierwszeństwo ma parametr max-age.

• ścieżka: ścieżka, która musi występować w żądanym adresie URL, w przeciwnym razie przeglądarka nie wyśle nagłówka Cookie.

• secure: jeśli ustawisz wartość true, plik cookie zostanie wysłany na serwer tylko wtedy, gdy żądanie zostanie wysłane z punktu końcowego https:.

• sameSite: określa, że plik cookie nie może być wysyłany z żądaniami z wielu źródeł. Wymagana jest wartość 'strict', 'lax' lub 'none'.

Powiązane uprawnienia

set_cookie

---

setPixelResponse

Ustawia treść odpowiedzi na GIF 1 x 1, ustawia nagłówek Content-Type na „image/gif”, ustawia nagłówki pamięci podręcznej tak, aby przeglądarki użytkowników nie zapisywały odpowiedzi w pamięci podręcznej, oraz ustawia stan odpowiedzi na 200.

Pamiętaj, że aby odpowiedź została wysłana z powrotem do klienta, musisz wywołać metodę returnResponse.

Składnia

setPixelResponse();

Powiązane uprawnienia

Wymaga uprawnień access_response. Uprawnienia muszą być skonfigurowane tak, aby zezwalały na dostęp do co najmniej:

• headers – musisz zezwolić na te klucze:
  • content-type
  • cache-control
  • expires
  • pragma
• body
• status

---

setResponseBody

Ustawia treść odpowiedzi na argument.

Pamiętaj, że aby odpowiedź została wysłana z powrotem do klienta, musisz wywołać metodę returnResponse.

Składnia

setResponseBody(body[, encoding]);

Parametry

Parametr	Typ	Opis
body	ciąg znaków	Wartość do ustawienia jako treść odpowiedzi.
encoding	ciąg znaków	Kodowanie znaków w ciele odpowiedzi (domyślnie 'utf8'). Obsługiwane wartości to 'ascii', 'utf8', 'utf16le', 'ucs2', 'base64', 'latin1', 'binary' i 'hex'.

Powiązane uprawnienia

Wymaga uprawnień access_response. Uprawnienia muszą być skonfigurowane tak, aby zezwalały na dostęp do co najmniej:

• body

---

setResponseHeader

Ustawia nagłówek w odpowiedzi, która zostanie zwrócona. Jeśli nagłówek o tej nazwie (niezależnie od wielkości liter) został wcześniej ustawiony przez ten interfejs API, to ostatnie wywołanie zastąpi lub usunie wartość ustawioną przez poprzedniego wywołującego.

Pamiętaj, że aby odpowiedź została wysłana z powrotem do klienta, musisz wywołać metodę returnResponse.

Składnia

setResponseHeader(name, value);

Parametry

Parametr	Typ	Opis
name	ciąg znaków	Nazwa nagłówka. W nazwach nagłówków HTTP wielkość liter nie jest rozróżniana, więc nazwa nagłówka będzie zapisana małymi literami.
value	ciąg znaków undefined	Wartość nagłówka. Jeśli jest to wartość null lub nieokreślona, nagłówek o danej nazwie zostanie usunięty z odpowiedzi, która zostanie zwrócona.

Powiązane uprawnienia

Wymaga uprawnień access_response. Uprawnienia muszą być skonfigurowane tak, aby zezwalały na dostęp do co najmniej:

• headers

---

setResponseStatus

Ustawia kod stanu HTTP odpowiedzi, która zostanie zwrócona.

Pamiętaj, że aby odpowiedź została wysłana z powrotem do klienta, musisz wywołać metodę returnResponse.

Składnia

setResponseStatus(statusCode);

Parametry

Parametr	Typ	Opis
statusCode	liczba	Kod stanu HTTP, który ma zostać zwrócony.

Powiązane uprawnienia

Wymaga uprawnień access_response. Uprawnienia muszą być skonfigurowane tak, aby zezwalały na dostęp do co najmniej:

• status

---

sha256

Oblicza skrót SHA-256 danych wejściowych i wywołuje funkcję wywołania zwrotnego z skrótem zakodowanym w formacie Base64, chyba że obiekt options określa inny kod wyjściowy.

Podpis i zachowanie tego interfejsu API odpowiadają interfejsowi sha256 API dla kontenerów internetowych. Jednak w przypadku szablonów niestandardowych w kontenerach serwera należy używać interfejsu sha256Sync API, aby uprościć kod.

Przykład

const encodeUriComponent = require('encodeUriComponent');
const sendHttpGet = require('sendHttpGet');
const sha256 = require('sha256');

sha256('inputString', (digest) => {
  sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digest));
});

sha256('inputString', (digest) => {
  sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digest));
}, {outputEncoding: 'hex'});

Składnia

sha256(input, onSuccess, options = undefined);

Parametry

Parametr	Typ	Opis
input	ciąg znaków	Ciąg do zaszyfrowania.
onSuccess	function	Jest wywoływany z wynikiem digest zakodowanym w formacie base64, chyba że obiekt options określa inny kod wyjściowy.
options	object	Opcjonalny obiekt options do określania kodowania wyjściowego. Jeśli jest określony, obiekt powinien zawierać klucz outputEncoding z wartością base64 lub hex.

Powiązane uprawnienia

Brak.

---

sha256Sync

Oblicza i zwraca skrót SHA-256 wejścia zakodowany w formacie base64, chyba że obiekt options określa inny kod wyjściowy.

Przykład

const encodeUriComponent = require('encodeUriComponent');
const sendHttpGet = require('sendHttpGet');
const sha256Sync = require('sha256Sync');

const digestBase64 = sha256Sync('inputString');
const digestHex = sha256Sync('inputString', {outputEncoding: 'hex'});
sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digestBase64));
sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digestHex));

Składnia

sha256Sync(input, options = undefined);

Parametry

Parametr	Typ	Opis
input	ciąg znaków	Ciąg do zaszyfrowania.
options	object	Opcjonalny obiekt options do określania kodowania wyjściowego. Jeśli jest określony, obiekt powinien zawierać klucz outputEncoding z wartością base64 lub hex.

Powiązane uprawnienia

Brak.

---

templateDataStorage

Zwraca obiekt z metodami dostępu do pamięci danych szablonu. Przechowywanie danych w szablonie umożliwia udostępnianie danych w ramach poszczególnych wykonań pojedynczego szablonu. Dane przechowywane w magazynie danych szablonów są przechowywane na serwerze, na którym działa kontener. W większości przypadków kontener jest obsługiwany przez wiele serwerów, więc przechowywanie danych w magazynie danych szablonów nie gwarantuje, że każda kolejna prośba będzie miała dostęp do tych danych.

„Dane” w nazwie „templateDataStorage” oznaczają, że za pomocą tego interfejsu API można przechowywać tylko proste typy danych, które nie są funkcjami. Wszystkie funkcje lub odwołania do funkcji przekazywane do interfejsu API będą przechowywane jako null.

Uwaga: prośby pochodzące z trybu debugowania lub podglądu albo z edytora szablonów mają dostęp do miejsca na dane szablonów, które jest inicjowane jako puste i zachowuje się tylko przez czas trwania prośby (aby nie mieszać danych debugowania ani testowania z danymi produkcyjnymi).

Uwaga: w przeciwieństwie do Web Storage API, templateDataStorage nie serializuje ani deserializuje danych w postaci ciągów znaków.

Składnia

const templateDataStorage = require('templateDataStorage');

// Returns a copy of the value stored for the given key, or null if nothing
// is stored with that key.
templateDataStorage.getItemCopy(key);

// Stores a copy of the value for the given key (or removes the data stored
// for the given key if the input value is null).
templateDataStorage.setItemCopy(key, value);

// Removes the value stored for the given key, if present.
templateDataStorage.removeItem(key);

// Deletes all values stored for the current template.
templateDataStorage.clear();

Przykład

const sendHttpGet = require('sendHttpGet');
const setResponseBody = require('setResponseBody');
const setResponseStatus = require('setResponseStatus');
const templateDataStorage = require('templateDataStorage');

// Check to see if the item is in the cache.
const cachedBody = templateDataStorage.getItemCopy(data.key);
if (cachedBody) {
  setResponseBody(cachedBody);
  data.gtmOnSuccess();
  return;
}

sendHttpGet(data.url).then((result) => {
  if (result.statusCode >= 200 && result.statusCode < 300) {
    setResponseBody(result.body);
    templateDataStorage.setItemCopy(data.key, result.body);
    data.gtmOnSuccess();
  } else {
    data.gtmOnFailure();
  }
  setResponseStatus(result.statusCode);
});

Powiązane uprawnienia

access_template_storage

---

testRegex

Testuje ciąg znaków pod kątem wyrażenia regularnego utworzonego za pomocą interfejsu API createRegex. Zwraca true, jeśli wyrażenie regularne pasuje. W przeciwnym razie zwraca wartość false.

Wyrażenie regularne utworzone z flagą globalną jest zależne od stanu. Więcej informacji znajdziesz w dokumentacji RegExp.

Przykład

const createRegex = require('createRegex');
const testRegex = require('testRegex');

const domainRegex = createRegex('\\w+\\.com', 'i');

// createRegex returns null if the regex is invalid or Re2 is not available.
if (domainRegex === null) return;

// Returns true
testRegex(domainRegex, 'example.com/foobar');

Składnia

testRegex(regex, string);

Parametry

Parametr	Typ	Opis
regex	Obiekt	Wyrażenie regularne, które ma być testowane, zwrócone przez interfejs API createRegex.
string	ciąg znaków	Testowy ciąg znaków do sprawdzenia.

Powiązane uprawnienia

Brak.

---

toBase64

Koduje ciąg tekstowy w formacie base64 lub base64url. Domyślnie używane jest kodowanie base64.

Składnia

toBase64(input, options);

Parametry

Parametr	Typ	Opis
input	ciąg znaków	Ciąg do zakodowania.
options	object	Opcjonalna konfiguracja interfejsu API. (patrz Opcje poniżej).

Opcje

Opcja	Typ	Opis	Wersja minimalna
urlEncoding	wartość logiczna	Jeśli ma wartość Prawda, wynik zostanie zakodowany w formacie base64url.	1.0.0

Przykład

const toBase64 = require('toBase64');

const base64Hello = toBase64('hello');
const base64UrlHello = toBase64('hello', {urlEncoding: true});

Powiązane uprawnienia

Brak.

---

BigQuery

Zwraca obiekt, który udostępnia funkcje BigQuery.

Funkcja BigQuery.insert umożliwia zapisywanie danych w tabeli BigQuery. Zwraca obietnice, która jest realizowana po pomyślnym wstawieniu lub odrzucana w przypadku błędu.

Gdy wstawienie się powiedzie, obietnica zostanie spełniona bez argumentów.

Jeśli wstawienie się nie powiedzie, obietnica zostanie odrzucona z listą obiektów zawierających przyczynę błędu i opcjonalnie obiekt wiersza, jeśli wystąpił błąd. Możliwe, że część żądania została zrealizowana, a część nie. W tym przypadku obietnica jest odrzucana z listą błędów dla każdego wiersza z obiektem wiersza, aby ułatwić odróżnienie wierszy, które zostały wstawione (patrz Przykłady błędów poniżej). Więcej informacji znajdziesz w dokumentacji BigQuery dotyczącej komunikatów o błędach.

Składnia

BigQuery.insert(connectionInfo, rows[, options]);

Parametry

Parametr	Typ	Opis
connectionInfo	object	Określa informacje wymagane do połączenia z tabelą BigQuery. Jest 1 parametr opcjonalny i 2 wymagane parametry: projectId – opcjonalny identyfikator projektu Google Cloud Platform. Jeśli nie zostanie pominięty, projectId zostanie pobrany z zmiennej środowiskowej GOOGLE_CLOUD_PROJECT, o ile ustawienie uprawnień access_bigquery dla identyfikatora projektu ma wartość * lub GOOGLE_CLOUD_PROJECT. Jeśli kontener serwera działa w Google Cloud, wartość GOOGLE_CLOUD_PROJECT będzie już ustawiona na identyfikator projektu Google Cloud. datasetId – identyfikator zbioru danych BigQuery. tableId – identyfikator tabeli BigQuery.
rows	Tablica	Wiersze do wstawienia w tabeli.
options	object	Opcjonalne opcje żądania. Obsługiwane opcje to: ignoreUnknownValues i skipInvalidRows. Nieznane klucze opcji są ignorowane. (patrz sekcja Opcje poniżej).

Opcje

Parametr	Typ	Opis
ignoreUnknownValues	wartość logiczna	Jeśli ustawisz wartość true, akceptuj wiersze zawierające wartości, które nie są zgodne ze schematem. Nieznane wartości są ignorowane. Domyślna wartość to false.
skipInvalidRows	wartość logiczna	Jeśli ustawisz wartość true, wstaw wszystkie prawidłowe wiersze żądania, nawet jeśli istnieją nieprawidłowe wiersze. Domyślna wartość to false.

Przykłady błędów

Błąd „Nie znaleziono modułu” oznacza, że kontener serwera prawdopodobnie działa na podstawie starszej wersji obrazu, która nie zawierała jeszcze modułu BigQuery. Ponownie wdrożyć kontener serwera z tymi samymi ustawieniami za pomocą naszego skryptu wdrażania. Moduł zostanie automatycznie uwzględniony po zakończeniu operacji.

Błąd niewystąpienia ma zwykle jeden obiekt błędu z kluczem reason:

[{reason: 'invalid'}]

Błąd w wstawieniu może zawierać wiele obiektów błędu z tablicą errors i obiektem row. Oto przykład odpowiedzi z błędem po wstawieniu 2 wierszy, z których tylko jeden zawiera błąd:

[
  {
    "errors": [
      {
        "reason":"invalid"
      }
    ],
    "row": {
      "string_col":"otherString",
      "number_col":-3,
      "bool_col":3
    }
  },
  {
    "errors": [
      {
        "reason":"stopped"
      }
    ],
    "row": {
      "string_col":"stringValue",
      "number_col":5,
      "bool_col:false
    }
  }
]

Przykład

const BigQuery = require('BigQuery');

const connectionInfo = {
  'projectId': 'gcp-cloud-project-id',
  'datasetId': 'destination-dataset',
  'tableId': 'destination-table',
};

const rows = [{
  'column1': 'String1',
  'column2': 1234,
}];

const options = {
  'ignoreUnknownValues': true,
  'skipInvalidRows': false,
};

BigQuery.insert(connectionInfo, rows, options)
  .then(data.gtmOnSuccess, data.gtmOnFailure);

Powiązane uprawnienia

access_bigquery

---

Firestore

Zwraca obiekt, który udostępnia funkcje Firestore.

Ten interfejs API obsługuje tylko Firestore w trybie natywnym, a nie Firestore w trybie Datastore. Interfejs API obsługuje tylko domyślną bazę danych.

Firestore.read

Funkcja Firestore.read odczytuje dane z dokumentu Firestore i zwróci obietnice, która zwraca obiekt zawierający 2 klucze: id i data. Jeśli dokumentu nie ma, obietnica odrzuca się, przekazując obiekt zawierający klucz reason o wartości not_found.

Uwaga: domyślnie usługa Firestore.read przechowuje w pamięci podręcznej swoją odpowiedź przez cały czas wykonywania kontenera. Aby wyłączyć buforowanie, zapoznaj się z sekcją Opcje poniżej. Buforowanie jest automatycznie wyłączane podczas każdej transakcji.

Składnia

Firestore.read(path[, options]);

Parametry

Parametr	Typ	Opis
path	ciąg znaków	Ścieżka do dokumentu lub kolekcji. Nie może zaczynać się ani kończyć ukośnikiem „/”.
options	object	Opcjonalne opcje prośby. Obsługiwane opcje to: projectId, disableCache i transaction. Nieznane klucze opcji są ignorowane. (patrz sekcja Opcje poniżej).

Opcje

Parametr	Typ	Opis
projectId	ciąg znaków	Opcjonalnie. Identyfikator projektu Google Cloud Platform. Jeśli nie zostanie podany, wartość projectId zostanie pobrana ze zmiennej środowiskowej GOOGLE_CLOUD_PROJECT, o ile ustawienie uprawnień dla identyfikatora projektu ma wartość * lub GOOGLE_CLOUD_PROJECT. Jeśli kontener serwera działa w Google Cloud, GOOGLE_CLOUD_PROJECT będzie już mieć ustawiony identyfikator projektu Google Cloud.
disableCache	wartość logiczna	Opcjonalnie. Określa, czy pamięć podręczna ma być wyłączona. Domyślnie jest włączone przechowywanie w pamięci podręcznej, które przechowuje wyniki w pamięci podręcznej przez czas trwania żądania.
transaction	ciąg znaków	Opcjonalnie. Wartość pobrana z Firestore.runTransaction(). Oznacza operację do użycia w ramach transakcji.

Przykład

const Firestore = require('Firestore');

return Firestore.read('collection/document', {
  projectId: 'gcp-cloud-project-id',
}).then((result) => result.data.key, () => undefined);

Firestore.write

Funkcja Firestore.write zapisuje dane w dokumencie lub kolekcji Firestore. Jeśli ścieżka prowadzi do kolekcji, zostanie utworzony dokument z losowo wygenerowanym identyfikatorem. Jeśli ścieżka prowadzi do dokumentu, który nie istnieje, zostanie on utworzony. Ten interfejs API zwraca obietnicę, która przekształca się w identyfikator dokumentu dodanego lub zmodyfikowanego. Jeśli użyjesz opcji transakcji, interfejs API nadal zwróci obietnicę, ale nie będzie ona zawierać identyfikatora, ponieważ zapisy są grupowane.

Składnia

Firestore.write(path, input[, options]);

Parametry

Parametr	Typ	Opis
path	ciąg znaków	Ścieżka do dokumentu lub kolekcji. Nie może zaczynać się ani kończyć ukośnikiem „/”.
input	object	Wartość do zapisania w dokumencie. Jeśli opcja scalania jest ustawiona, interfejs API scali klucze z danych wejściowych z dokumentem.
options	object	Opcjonalne opcje prośby. Obsługiwane opcje to: projectId, merge i transaction. Nieznane klucze opcji są ignorowane. (patrz sekcja Opcje poniżej).

Opcje

Parametr	Typ	Opis
projectId	ciąg znaków	Opcjonalnie. Identyfikator projektu Google Cloud Platform. Jeśli nie zostanie podany, wartość projectId zostanie pobrana ze zmiennej środowiskowej GOOGLE_CLOUD_PROJECT, o ile ustawienie uprawnień dla identyfikatora projektu ma wartość * lub GOOGLE_CLOUD_PROJECT. Jeśli kontener serwera działa w Google Cloud, GOOGLE_CLOUD_PROJECT będzie już mieć ustawiony identyfikator projektu Google Cloud.
merge	wartość logiczna	Opcjonalnie. Jeśli ustawisz wartość true, klucze z danych zostaną scalone z dokumentem. W przeciwnym razie metoda zastąpi cały dokument. Domyślna wartość to false.
transaction	ciąg znaków	Opcjonalnie. Wartość pobrana z Firestore.runTransaction(). Oznacza operację do użycia w ramach transakcji.

Przykład

const Firestore = require('Firestore');

const input = {key1: 'value1', key2: 12345};

Firestore.write('collection/document', input, {
  projectId: 'gcp-cloud-project-id',
  merge: true,
}).then((id) => {
  data.gtmOnSuccess();
}, data.gtmOnFailure);

Firestore.query

Funkcja Firestore.query wysyła zapytanie do podanej kolekcji i zwraca obietnicę, która przekształca się w tablicę dokumentów Firestore pasujących do warunków zapytania. Obiekt dokumentu Firestore jest taki sam jak podany powyżej w sekcji Firestore.read. Jeśli nie ma dokumentów pasujących do warunków zapytania, zwrócona obietnica będzie miała postać pustej tablicy.

Uwaga: domyślnie usługa Firestore.query przechowuje w pamięci podręcznej swoją odpowiedź przez cały czas wykonywania kontenera. Aby wyłączyć buforowanie, zapoznaj się z sekcją Opcje poniżej. Zapisywanie w pamięci podręcznej jest automatycznie wyłączane podczas każdej transakcji.

Uwaga: Firestore automatycznie tworzy indeks dla każdego pola. Aby tworzyć zapytania dotyczące wielu pól, w przypadku określonej kolekcji może być konieczne utworzenie indeksu złożonego. Więcej informacji znajdziesz w dokumentacji Firestore na temat indeksów złożonych.

Składnia

Firestore.query(collection, queryConditions[, options]);

Parametry

Parametr	Typ	Opis
collection	ciąg znaków	Ścieżka do kolekcji. Nie może zaczynać się ani kończyć ukośnikiem „/”.
queryConditions	Tablica	Tablica warunków zapytania. Każde zapytanie ma postać tablicy z 3 wartościami: key, operator i expectedValue. np.: [[‘id’, ‘<’, ‘5’], [‘state’, ‘==’, ‘CA’]]. Warunki są łączone za pomocą operatora AND, aby utworzyć wynik zapytania. Listę zgodnych operatorów zapytań znajdziesz w  operatorach zapytań Firehose.
options	object	Opcjonalne opcje prośby. Obsługiwane opcje to: projectId, disableCache, limit i transaction. Nieznane klucze opcji są ignorowane. (patrz sekcja Opcje poniżej).

Opcje

Parametr	Typ	Opis
projectId	ciąg znaków	Opcjonalnie. Identyfikator projektu Google Cloud Platform. Jeśli nie zostanie podany, wartość projectId zostanie pobrana ze zmiennej środowiskowej GOOGLE_CLOUD_PROJECT, o ile ustawienie uprawnień dla identyfikatora projektu ma wartość * lub GOOGLE_CLOUD_PROJECT. Jeśli kontener serwera działa w Google Cloud, GOOGLE_CLOUD_PROJECT będzie już mieć ustawiony identyfikator projektu Google Cloud.
disableCache	wartość logiczna	Opcjonalnie. Określa, czy pamięć podręczna ma być wyłączona. Domyślnie jest włączone przechowywanie w pamięci podręcznej, które przechowuje wyniki w pamięci podręcznej przez czas trwania żądania.
limit	liczba	Opcjonalnie. Zmienia maksymalną liczbę wyników zwracanych przez zapytanie. Domyślnie jest to 5.
transaction	ciąg znaków	Opcjonalnie. Wartość pobrana z Firestore.runTransaction(). Oznacza operację do użycia w ramach transakcji.

Przykład

const Firestore = require('Firestore');

const queries = const queries = [['id', '==', '5']];

return Firestore.query('collection', queries, {
  projectId: 'gcp-cloud-project-id',
  limit: 1,
}).then((documents) => documents[0].data.key, () => undefined);

Firestore.runTransaction

Funkcja Firestore.runTransaction umożliwia użytkownikowi jednoczesne odczytywanie i zapisywanie danych w Firestore. Jeśli wystąpi jednoczesny zapis lub inny konflikt transakcji, transakcja zostanie ponownie podjęta maksymalnie 2 razy. Jeśli po 3 próbach nie uda się tego zrobić, interfejs API odrzuci żądanie z błędem. Ten interfejs API zwraca obietnicę, która dla każdej operacji zapisu tworzy tablicę identyfikatorów dokumentów, jeśli transakcja zakończyła się pomyślnie, a w przeciwnym razie odrzuca ją z błędem.

Składnia

Firestore.runTransaction(callback[, options]);

Parametry

Parametr	Typ	Opis
callback	function	Funkcja wywołania zwrotnego, która jest wywoływana z identyfikatorem transakcji w postaci ciągu znaków. Identyfikator transakcji można przekazać do wywołań interfejsu API służących do odczytu, zapisu i wysyłania zapytań. Ta funkcja wywołania zwrotnego musi zwracać obietnicę. Funkcja callback może zostać wywołana maksymalnie 3 razy, zanim zakończy się niepowodzeniem.
options	object	Opcjonalne opcje prośby. Obsługiwana jest tylko opcja projectId. Nieznane klucze opcji są ignorowane. (patrz sekcja Opcje poniżej).

Opcje

Parametr	Typ	Opis
projectId	ciąg znaków	Opcjonalnie. Identyfikator projektu Google Cloud Platform. Jeśli nie zostanie podany, wartość projectId zostanie pobrana ze zmiennej środowiskowej GOOGLE_CLOUD_PROJECT, o ile ustawienie uprawnień dla identyfikatora projektu ma wartość * lub GOOGLE_CLOUD_PROJECT. Jeśli kontener serwera działa w Google Cloud, GOOGLE_CLOUD_PROJECT będzie już mieć ustawiony identyfikator projektu Google Cloud.

Przykład

const Firestore = require('Firestore');

const path = 'collection/document';
const projectId = 'gcp-cloud-project-id';

Firestore.runTransaction((transaction) => {
  const transactionOptions = {
    projectId: projectId,
    transaction: transaction,
  };
  // Must return a promise.
  return Firestore.read(path, transactionOptions).then((result) => {
    const newInputCount = result.data.inputCount + 1;
    const input = {key1: 'value1', inputCount: newInputCount};
    return Firestore.write(path, input, transactionOptions);
  });
}, {
  projectId: projectId
}).then((ids) => {
  data.gtmOnSuccess();
}, data.gtmOnFailure);

Przykład błędu

Błędy występujące w każdej funkcji Firestore zostaną odrzucone z obiektem zawierającym klucz reason:

Firestore.read(...).then(onSuccess, (error) => {
  if (error.reason === 'unknown') {
    // Handle the unknown error here.
  }
});

Przyczyny błędów mogą obejmować kody błędów interfejsu REST Firestore API.

Powiązane uprawnienia

access_firestore

---

JSON

Zwraca obiekt, który udostępnia funkcje JSON.

Funkcja parse() analizuje ciąg znaków JSON, aby utworzyć wartość lub obiekt opisany przez ten ciąg. Jeśli nie można przeanalizować wartości (np. ze względu na nieprawidłowy format JSON), funkcja zwróci wartość undefined. Jeśli wartość wejściowa nie jest ciągiem znaków, zostanie ona przekonwertowana na ciąg znaków.

Funkcja stringify() konwertuje dane wejściowe na ciąg znaków w formacie JSON. Jeśli nie można przeanalizować wartości (np. obiekt zawiera cykl), metoda zwróci wartość undefined.

Przykład

const JSON = require('JSON');

// The JSON input string is converted to an object.
const object = JSON.parse('{"foo":"bar"}');

// The input object is converted to a JSON string.
const str = JSON.stringify({foo: 'bar'});

Składnia

JSON.parse(stringInput);
JSON.stringify(value);

Powiązane uprawnienia

Brak.

---

Math

Obiekt udostępniający funkcje Math.

Składnia

const Math = require('Math');

// Retrieve the absolute value.
const absolute = Math.abs(-3);

// Round the input down to the nearest integer.
const roundedDown = Math.floor(3.6);

// Round the input up to the nearest integer.
const roundedUp = Math.ceil(2.2);

// Round the input to the nearest integer.
const rounded = Math.round(3.1);

// Return the largest argument.
const biggest = Math.max(1, 3);

// Return the smallest argument.
const smallest = Math.min(3, 5);

// Return the first argument raised to the power of the second argument.
const powerful = Math.pow(3, 1);

// Return the square root of the argument.
const unsquared = Math.sqrt(9);

Parametry

Parametry funkcji matematycznych są konwertowane na liczby.

Powiązane uprawnienia

Brak.

---

Messages

Interfejsy API wymienione poniżej współpracują ze sobą, umożliwiając przekazywanie komunikatów między różnymi częściami kontenera.

---

addMessageListener

Dodaje funkcję, która nasłuchuje wiadomości określonego typu. Gdy wiadomość tego typu jest wysyłana za pomocą interfejsu sendMessage API (zazwyczaj przez tag), wywołanie zwrotne jest wykonywane synchronicznie. Funkcja wywołania zwrotnego jest wywoływana z 2 parametrami:

1. messageType:string
2. message:Object

Jeśli wywołanie zwrotne zostanie dodane w kliencie, będzie ono otrzymywać wiadomości z wszystkich zdarzeń tworzonych przez tego klienta. Jeśli wywołanie zwrotne ma otrzymywać wiadomości tylko z określonego zdarzenia, powiążesz ten interfejs API z tym zdarzeniem za pomocą funkcji bindToEvent interfejsu API runContainer.onStart Zobacz przykład.

Składnia

const addMessageListener = require('addMessageListener');

addMessageListener('send_pixel', (messageType, message) => {
  // This will be run whenever something sends a 'send_pixel' message.
});

Parametry

Parametr	Typ	Opis
messageType	ciąg znaków	Typ wiadomości, której należy słuchać. Jeśli wartość nie jest ciągiem znaków, zostanie przekonwertowana na ciąg znaków.
callback	function	Funkcja wywołania zwrotnego, która ma być wykonywana po wysłaniu wiadomości o odpowiednim typie. Jeśli wywołanie zwrotne nie jest funkcją, interfejs API nie wykona żadnej czynności.

Przykład

const addMessageListener = require('addMessageListener');
const claimRequest = require('claimRequest');
const extractEventsFromMpv1 = require('extractEventsFromMpv1');
const returnResponse = require('returnResponse');
const runContainer = require('runContainer');

claimRequest();
addMessageListener('send_pixel', (messageType, message) => {
  // This will be run whenever a tag sends a 'send_pixel' message.
});

const events = extractEventsFromMpv1();
let eventsCompleted = 0;
events.forEach((event, i) => {
  runContainer(events[i], /* onComplete= */ () => {
    if (events.length === ++eventsCompleted) {
      returnResponse();
    }
  }, /* onStart= */ (bindToEvent) => {
    if (i === 0) {
      bindToEvent(addMessageListener)('send_pixel', (messageType, message) => {
        // This will be called whenever a tag for the first event sends a
        // 'send_pixel' message.
      });
    }
  });
});

Powiązane uprawnienia

Wymaga uprawnień use_message. Uprawnienie musi być skonfigurowane tak, aby zezwalało na:

• Typ wiadomości z Usage listen lub listen_and_send.

---

hasMessageListener

Zwraca wartość „True” (Prawda), jeśli dla danego typu wiadomości został dodany odbiornik wiadomości. W przeciwnym razie zwraca wartość „fałsz”.

Składnia

const hasMessageListener = require('hasMessageListener');

hasMessageListener('send_pixel');

Powiązane uprawnienia

Brak.

---

sendMessage

Wysyła wiadomość określonego typu do zarejestrowanego słuchacza. Możesz go używać do wysyłania wiadomości z tagu z powrotem do klienta, który uruchomił kontener.

Składnia

const sendMessage = require('sendMessage');

sendMessage('send_pixel', {url: 'https://analytics.example.com/collect'});

Parametry

Parametr	Typ	Opis
messageType	ciąg znaków	Typ wiadomości do wysłania. Jeśli wartość nie jest ciągiem znaków, zostanie ona przekonwertowana na ciąg znaków.
message	object	Wiadomość do wysłania. Jeśli wiadomość nie jest obiektem, interfejs API nie wykona żadnej akcji.

Powiązane uprawnienia

Wymaga uprawnień use_message. Uprawnienie musi być skonfigurowane tak, aby zezwalało na:

• Typ wiadomości z Usage listen_and_send lub send.

---

Object

Zwraca obiekt, który udostępnia metody Object.

Metoda keys() zapewnia zachowanie standardowej biblioteki Object.keys(). Zwraca tablicę nazw właściwości zliczalnych danego obiektu w tym samym porządku, w jakim występuje w pętli for...in.... Jeśli wartość wejściowa nie jest obiektem, zostanie skonwertowana na obiekt.

Metoda values() zapewnia zachowanie standardowej biblioteki Object.values(). Zwraca tablicę wartości własnych właściwości zliczalnych danego obiektu w tym samym porządku, w jakim występuje w pętli for...in.... Jeśli wartość wejściowa nie jest obiektem, zostanie ona skonwertowana na obiekt.

Metoda entries() zapewnia zachowanie standardowej biblioteki Object.entries(). Zwraca tablicę par własności enumerable [key, value] danego obiektu w tym samym porządku, w jakim działa pętla for...in.... Jeśli wartość wejściowa nie jest obiektem, zostanie ona skonwertowana na obiekt.

Metoda freeze() zapewnia zachowanie funkcji Object.freeze() z biblioteki standardowej. Obiekt zamrożony nie może już zostać zmieniony. Zamrożenie obiektu uniemożliwia dodawanie do niego nowych właściwości, usuwanie istniejących właściwości oraz zmianę wartości istniejących właściwości. freeze() zwraca ten sam obiekt, który został przekazany. Argument typu prymitywnego lub null zostanie potraktowany jak zamrożony obiekt i zwrócony.

Metoda delete() zapewnia zachowanie operatora usuwania biblioteki standardowej. Usuwa z obiektu podany klucz, chyba że obiekt jest zablokowany. Podobnie jak operator usuwania z standardowej biblioteki zwraca true, jeśli pierwsza wartość wejściowa (objectInput) jest obiektem, który nie jest zamrożony, nawet jeśli druga wartość wejściowa (keyToDelete) określa klucz, który nie istnieje. W pozostałych przypadkach zwraca wartość false. Różni się on jednak od operatora usuwania z standardowej biblioteki pod następującymi względami:

• Wartość keyToDelete nie może być ciągiem znaków oddzielonych kropkami, który określa klucz zagnieżdżony.
• Funkcji delete() nie można używać do usuwania elementów z tablicy.
• Za pomocą polecenia delete() nie można usuwać usług z zakresu globalnego.

Składnia

Object.keys(objectInput)
Object.values(objectInput)
Object.entries(objectInput)
Object.freeze(objectInput)
Object.delete(objectInput, keyToDelete)

Parametry

Object.keys

Parametr	Typ	Opis
objectInput	dowolny	Obiekt, którego klucze mają być zliczane. Jeśli dane wejściowe nie są obiektem, zostaną skonwertowane do obiektu.

Object.values

Parametr	Typ	Opis
objectInput	dowolny	Obiekt, którego wartości mają być zliczane. Jeśli dane wejściowe nie są obiektem, zostaną skonwertowane na obiekt.

Object.entries

Parametr	Typ	Opis
objectInput	dowolny	Obiekt, którego pary klucz-wartość mają być wyliczane. Jeśli dane wejściowe nie są obiektem, zostaną skonwertowane na obiekt.

Object.freeze

Parametr	Typ	Opis
objectInput	dowolny	Obiekt do zamrożenia. Jeśli dane wejściowe nie są obiektem, zostaną potraktowane jako zamrożone.

Object.delete

Parametr	Typ	Opis
objectInput	dowolny	Obiekt, którego klucz ma zostać usunięty.
keyToDelete	ciąg znaków	Klucz najwyższego poziomu, który chcesz usunąć.

Przykład

const Object = require('Object');

// The keys of an object are enumerated in an array.
const keys = Object.keys({foo: 'bar'});

// The values of an object are enumerated in an array.
const values = Object.values({foo: 'bar'});

// The key/value pairs of an object are enumerated in an array.
const entries = Object.entries({foo: 'bar'});

// The input object is frozen.
const frozen = Object.freeze({foo: 'bar'});

// The key is removed from the input object.
const obj1 = {deleteme: 'value'};
Object.delete(obj1, 'deleteme');
// Only a top-level key can be specified as the key to delete.
const obj2 = {nested: {key: 'value'}};
Object.delete(obj2, 'nested.key'); // This has no effect.
Object.delete(obj2.nested, 'key'); // This deletes the nested key.

---

Promise

Zwraca obiekt, który udostępnia metody interakcji z obietnicami.

Obietnice są funkcjonalnie równoważne obietnicom JavaScript. Każde wystąpienie ma trzy metody, które zwracają obietnicę, która umożliwia dalsze działanie po jej ustabilizowaniu:

• .then() – obsługuje zarówno zamknięte, jak i odrzucone zgłoszenia. Jako parametrów przyjmuje 2 funkcje zwracające wartości: jedną w przypadku powodzenia i jedną w przypadku niepowodzenia.
• .catch() – obsługuje tylko odrzucone zgłoszenia. Przyjmuje jako parametr 1 wywołanie zwrotne.
• .finally() – umożliwia uruchomienie kodu niezależnie od tego, czy obietnica została spełniona, czy odrzucona. Przyjmuje jako parametr funkcję wywołania zwrotnego, która jest wywoływana z branym argumentem.

Zmienna zwracająca obietnicę jest równa wartości rozwiązanej obietnicy lub false, jeśli obietnica została odrzucona.

Uwaga: obietnica JS w piaskownicy przekracza limit czasu (zostaje odrzucona) po 5 sekundach, jeśli nie zostanie zrealizowana.

Przykład

promise.then((resolvedValue) => {
    // Handles when promise resolves.
  }, (rejectedValue) => {
    // Handles when promise rejects.
  });
promise.catch((rejectedValue) => {
    // Handles when promise rejects.
  });
promise.finally(() => {
    // Runs regardless of whether or not the previous promise resolves or
    // rejects.
  });

Promise.all

Zwraca obietnicę, która:

• rozwiązuje się, gdy wszystkie dane wejściowe zostaną rozwiązane lub
• odrzuca, gdy którykolwiek z danych wejściowych zostanie odrzucony

Składnia

Promise.all(inputs);

Parametry

Parametr	Typ	Opis
inputs	Tablica	Tablica wartości lub obietnic. Jeśli dane wejściowe nie są obietnicą, są przekazywane tak, jakby były wartością rozwiązania obietnicy. Wyrzuca błąd, jeśli dane wejściowe nie są tablicą.

Przykład

const Promise = require('Promise');
const sendHttpGet = require('sendHttpGet');

return Promise.all(['a', sendHttpGet('https://example.com')])
  .then((results) => {
    // results will equal: ['a', {statusCode: 200, headers: {}, body: ''}]
  });

Powiązane uprawnienia

Brak.

Promise.create

Tworzy obietnicę, która pod względem funkcjonalności jest równoważna obietnicy JavaScript.

Składnia

Promise.create(resolver);

Parametry

Parametr	Typ	Opis
resolver	function	Funkcja, która jest wywoływana z 2 funkcjami: resolve i reject. Zwrócone obietnice zostaną rozwiązane lub odrzucone, gdy wywołany zostanie odpowiedni parametr. Wyrzuca błąd, jeśli resolver nie jest funkcją.

Przykład

const Promise = require('Promise');

return Promise.create((resolve, reject) => {
  // Do asynchronous work that eventually calls resolve() or reject()
});

Powiązane uprawnienia

Brak.

Testowanie interfejsów API

Te interfejsy API współpracują z testami JavaScript w piaskownicy, aby tworzyć testy niestandardowych szablonów w Menedżerze tagów Google. Te testowe interfejsy API nie wymagają oświadczenia require(). [Więcej informacji o testach szablonów niestandardowych].

---

assertApi

Zwraca obiekt dopasowujący, który może służyć do płynnego formułowania twierdzeń dotyczących danego interfejsu API.

Składnia

assertApi(apiName)

Parametry

Parametr	Typ	Opis
apiName	ciąg znaków	Nazwa interfejsu API do sprawdzenia; ten sam ciąg znaków, który został przekazany do funkcji require().

Dopasowywacze

• Subject.wasCalled()
• Subject.wasNotCalled()
• Subject.wasCalledWith(...expected)
• Subject.wasNotCalledWith(...expected)

Przykłady

assertApi('sendPixel').wasCalled();
assertApi('getUrl').wasNotCalled();
assertApi('makeNumber').wasCalledWith('8');
assertApi('setInWindow').wasNotCalledWith('myVar', 'theWrongValue');

---

assertThat

Interfejs API assertThat jest wzorowany na bibliotece [Truth] firmy Google. Zwraca obiekt, którego można użyć do płynnego formułowania twierdzeń dotyczących wartości tematu. Nieudane założenie spowoduje natychmiastowe przerwanie testu i oznaczenie go jako nieudanego. Niepowodzenie jednego testu nie wpłynie jednak na inne przypadki testowe.

Składnia

assertThat(actual, opt_message)

Parametry

Parametr	Typ	Opis
actual	dowolny	Wartość do użycia w testach płynności.
opt_message	ciąg znaków	Opcjonalny komunikat do wydrukowania, jeśli asercja się nie powiedzie.

Dopasowywacze

Dopasowywanie	Opis
isUndefined()	Twierdzi, że temat to undefined.
isDefined()	Twierdzi, że temat nie jest undefined.
isNull()	Twierdzi, że temat to null.
isNotNull()	Twierdzi, że temat nie jest null.
isFalse()	Twierdzi, że temat to false.
isTrue()	Twierdzi, że temat to true.
isFalsy()	Twierdzi, że temat jest fałszywy. Wartości fałszywe to undefined, null, false, NaN, 0 i „” (pusty ciąg znaków).
isTruthy()	Potwierdza, że temat jest prawdziwy. Wartości fałszywe to undefined, null, false, NaN, 0 i „” (pusty ciąg znaków).
isNaN()	Sprawdza, czy temat ma wartość NaN.
isNotNaN()	Sprawdza, czy argument jest dowolną wartością inną niż NaN.
isInfinity()	Określa, czy argument jest dodatnią lub ujemną nieskończonością.
isNotInfinity()	Określa, że argument jest dowolną wartością oprócz dodatniej lub ujemnej nieskończoności.
isEqualTo(expected)	Twierdzi, że temat jest równy podanej wartości. Jest to porównanie wartości, a nie porównanie z wartością referencyjną. Zawartość obiektów i tablic porównywana jest rekurencyjnie.
isNotEqualTo(expected)	Twierdzenie, że argument subject nie jest równy podanej wartości. Jest to porównanie wartości, a nie porównanie z wartością referencyjną. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
isAnyOf(...expected)	Twierdzi, że podmiot jest równy jednej z podanych wartości. Jest to porównanie wartości, a nie porównanie z wartością referencyjną. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
isNoneOf(...expected)	Twierdzenie, że argument subject nie jest równy żadnej z podanych wartości. To jest porównanie wartości, a nie porównanie z wartością referencyjną. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
isStrictlyEqualTo(expected)	Twierdzi, że podmiot jest ściśle równy (===) podanej wartości.
isNotStrictlyEqualTo(expected)	Twierdzenie, że podmiot nie jest ściśle równy (!==) danej wartości.
isGreaterThan(expected)	Twierdzi, że argument jest większy niż (>) podana wartość w uporządkowanym porównaniu.
isGreaterThanOrEqualTo(expected)	Twierdzenie, że podmiot jest większy lub równy (>=) podanej wartości w uporządkowanym porównaniu.
isLessThan(expected)	Określa, że argument jest mniejszy (<) od podanej wartości w porównywaniu uporządkowanym.
isLessThanOrEqualTo(expected)	Potwierdza, że argument jest mniejszy lub równy (<=) podanej wartości w uporządkowanym porównaniu.
contains(...expected)	Sprawdza, czy argument jest tablicą lub ciągiem znaków zawierającym wszystkie podane wartości w dowolnej kolejności. Jest to porównanie wartości, a nie porównanie z wartością referencyjną. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
doesNotContain(...expected)	Określa, że argument jest tablicą lub ciągiem znaków, który nie zawiera żadnej z podanych wartości. Jest to porównanie wartości, a nie porównanie z wartością referencyjną. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
containsExactly(...expected)	Określa, że argument jest tablicą zawierającą wszystkie podane wartości w dowolnej kolejności i bez innych wartości. Jest to porównanie wartości, a nie porównanie z wartością referencyjną. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
doesNotContainExactly(...expected)	Twierdzi, że argument jest tablicą zawierającą inny zbiór wartości niż podany w dowolnej kolejności. Jest to porównanie wartości, a nie porównanie z wartością referencyjną. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
hasLength(expected)	Zakłada, że argument jest tablicą lub ciągiem znaków o określonej długości. Jeśli wartość nie jest tablicą ani ciągiem znaków, assercja zawsze kończy się niepowodzeniem.
isEmpty()	Sprawdza, czy argument jest tablicą lub ciągiem znaków, który jest pusty (długość = 0). Założenie zawsze zawodzi, jeśli wartość nie jest tablicą lub ciągiem znaków.
isNotEmpty()	Sprawdza, czy argument jest tablicą lub ciągiem znaków, który nie jest pusty (długość > 0). Założenie zawsze zawodzi, jeśli wartość nie jest tablicą lub ciągiem znaków.
isArray()	Zakłada, że typ tematu to tablica.
isBoolean()	Zakłada, że typ tematu to wartość logiczna.
isFunction()	Twierdzi, że typ tematu to funkcja.
isNumber()	Sprawdza, czy typ tematu jest liczbą.
isObject()	Zakłada, że typ podmiotu to obiekt.
isString()	Zakłada, że typ tematu jest ciągiem znaków.

Przykłady

assertThat(undefined).isUndefined();
assertThat(id, 'ID must be defined').isDefined();
assertThat(null).isNull();
assertThat(undefined).isNotNull();
assertThat(true).isTrue();
assertThat(false).isFalse();
assertThat(1).isTruthy();
assertThat('').isFalsy();
assertThat(1/0).isInfinity();
assertThat(0).isNotInfinity();
assertThat(-'foo').isNaN();
assertThat(100).isNotNaN();
assertThat(sentUrl).isEqualTo('https://endpoint.example.com/?account=12345');
assertThat(category).isNotEqualTo('premium');
assertThat(5).isAnyOf(1, 2, 3, 4, 5);
assertThat(42).isNoneOf('the question', undefined, 41.9);
assertThat('value').isStrictlyEqualTo('value');
assertThat('4').isNotStrictlyEqualTo(4);
assertThat(['a', 'b', 'c']).contains('a', 'c');
assertThat(['x', 'y', 'z']).doesNotContain('f');
assertThat(['1', '2', '3']).containsExactly('3', '2', '1');
assertThat(['4', '5']).doesNotContainExactly('4');
assertThat('a string').hasLength(8);
assertThat([]).isEmpty();
assertThat('another string').isNotEmpty();

---

fail

natychmiast kończy bieżący test i wypisuje podany komunikat (jeśli został podany).

Składnia

fail(opt_message);

Parametry

Parametr	Typ	Opis
opt_message	ciąg znaków	Opcjonalny tekst komunikatu o błędzie.

Przykład

fail('This test has failed.');

---

mock

Interfejs API mock umożliwia zastąpienie działania interfejsów API w sandboksie. Mockowanie interfejsu API jest bezpieczne w użyciu w kodzie szablonu, ale działa tylko w trybie testowym. Przed każdym testem symulacje są resetowane.

Składnia

mock(apiName, returnValue);

Parametry

Parametr	Typ	Opis
apiName	ciąg znaków	Nazwa interfejsu API, który ma być symulowany; ten sam ciąg znaków, który został przekazany do funkcji require()
returnValue	dowolny	Wartość do zwrócenia dla interfejsu API lub funkcji wywoływanej zamiast interfejsu API. Jeśli returnValue to funkcja, to jest ona wywoływana zamiast interfejsu API w piaskownicy. Jeśli returnValue to cokolwiek innego niż funkcja, zwracana jest ta wartość zamiast interfejsu API w piaskownicy.

Przykłady

mock('encodeUri', "https://endpoint.example.com/?account=12345");
mock('sendPixel', function(url, onSuccess, onFailure) {
    onSuccess();
});

---

mockObject

Interfejs API mockObject umożliwia zastąpienie działania interfejsów API w piaskownicy, które zwracają obiekt. Interfejs API jest bezpieczny do użycia w kodzie szablonu, ale działa tylko w trybie testowym. Przed każdym testem symulacje są resetowane.

Składnia

mockObject(apiName, objectMock);

Parametry

Parametr	Typ	Opis
apiName	ciąg znaków	Nazwa interfejsu API, który ma być symulowany; ten sam ciąg znaków, który został przekazany do funkcji require()
objectMock	object	Wartość do zwrócenia dla interfejsu API lub funkcji wywoływanej zamiast interfejsu API. Musi to być obiekt.

Przykłady

const storage = {};
let firestoreId = 1;

function asTestPromise(result) {
  return {
    then: (callback) => callback(result)
  };
}

mockObject('Firestore', {
  write: (collection, input) => {
    storage[collection + '/' + (++firestoreId)] = input;
    return asTestPromise(firestoreId);
  },
  read: (document) => asTestPromise({data: storage[document]})
});

---

runCode

Uruchamia kod szablonu, czyli zawartość karty Kod, w bieżącym środowisku testowym z danym obiektem danych wejściowych.

Składnia

runCode(data)

Parametry

Parametr	Typ	Opis
data	object	Obiekt danych, który ma być użyty w teście.

Zwracana wartość

Zwraca wartość zmiennej w przypadku szablonów zmiennych; zwraca undefined w przypadku wszystkich innych typów szablonów.

Przykład

runCode({field1: 123, field2: 'value'});

---