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 na końcu zdarzenia. Wywołanie zwrotne zostanie wywołane, gdy wszystkie tagi zdarzenia zostaną wykonane. Funkcja zwrotna otrzymuje 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 określonym zdarzeniem za pomocą funkcji bindToEvent interfejsu API runContainer. Więcej informacji znajdziesz w przykładzie.

Składnia

const addEventCallback = require('addEventCallback');

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

Parametry

Parametr Typ Opis
callback function Funkcja, która ma zostać wywołana po zakończeniu wydarzenia.

Obiekt eventData zawiera te dane:

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

Przykład

W przypadku klienta:

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

Planuje asynchroniczne wywołanie funkcji. Funkcja zostanie wywołana po zwróceniu bieżącego kodu. Jest to odpowiednik 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

Użyj tego interfejsu API w kliencie, aby odebrać żądanie. Gdy żądanie zostanie odebrane, kontener nie uruchamia dodatkowych klientów.

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

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

Przykład

const claimRequest = require('claimRequest');

claimRequest();

Składnia

claimRequest();

Powiązane uprawnienia

Brak.

computeEffectiveTldPlusOne

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

Jeśli argument ma wartość null lub undefined, zwracana jest jego wartość bez zmian. 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 przyrostków publicznych, zwracana jest niezmieniona wartość argumentu.

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 string Domena lub adres URL, na podstawie którego ma zostać obliczona wartość eTLD+1.

Powiązane uprawnienia

Brak.

createRegex

Tworzy nową instancję wyrażenia regularnego i zwraca ją w obiekcie. Nie możesz bezpośrednio uzyskać dostępu do wyrażenia regularnego. Możesz jednak przekazać go do interfejsów API testRegex, String.replace(), String.match() i String.search().

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

Ten interfejs API korzysta z implementacji Re2. Obraz Dockera serwera musi być w 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 string Tekst wyrażenia regularnego.
flags string Opcjonalny ciąg znaków zawierający flagi tworzonego wyrażenia regularnego. Obsługiwane są flagi „g” (global) i „i” (ignore case). Wszystkie pozostałe znaki są ignorowane.

Powiązane uprawnienia

Brak.

Minimalna wersja obrazu

2.0.0

decodeUri

Dekoduje wszystkie zakodowane znaki w podanym URI. Zwraca ciąg tekstowy, który reprezentuje zdekodowany identyfikator URI. Zwraca undefined, gdy otrzyma nieprawidłowe dane wejściowe.

Przykład

const decodeUri = require('decodeUri');

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

Składnia

decodeUri(encoded_uri);

Parametry

Parametr Typ Opis
encoded_uri string 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 zdekodowany komponent URI. Zwraca undefined, gdy podano 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 string Składnik URI, który został zakodowany za pomocą funkcji encodeUriComponent() lub w inny sposób.

Powiązane uprawnienia

Brak.

encodeUri

Zwraca zakodowany identyfikator URI, w którym znaki specjalne zostały zastąpione znakami ucieczki. 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 string Pełny identyfikator URI.

Powiązane uprawnienia

Brak.

encodeUriComponent

Zwraca zakodowany identyfikator URI, w którym znaki specjalne zostały zastąpione znakami ucieczki. 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 string Składnik identyfikatora URI.

Powiązane uprawnienia

Brak.

extractEventsFromMpv1

Tłumaczy przychodzące żądanie Measurement Protocol w wersji 1 na listę zdarzeń w formacie Unified Schema. Zwraca listę wyodrębnionych zdarzeń. Zwraca 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ć na dostęp co najmniej do:

  • body
  • query parameters

extractEventsFromMpv2

Tłumaczy przychodzące żądanie Measurement Protocol w wersji 2 na listę zdarzeń w formacie Unified Schema. Zwraca listę wyodrębnionych zdarzeń. Zwraca 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ć na dostęp co najmniej do:

  • body
  • query parameters

fromBase64

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

Składnia

fromBase64(base64EncodedString);

Parametry

Parametr Typ Opis
base64EncodedString string 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ę (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 number Minimalna potencjalna wartość zwracanej liczby całkowitej (włącznie).
max number 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 podanej nazwie.

Przykład

const getCookieValues = require('getCookieValues');

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

Składnia

getCookieValues(name[, noDecode]);

Parametry

Parametr Typ Opis
name string Nazwa pliku cookie.
noDecode wartość logiczna Jeśli wartość to true, wartości plików cookie nie będą dekodowane przed zwróceniem. Domyślna wartość to false.

Powiązane uprawnienia

get_cookies

getEventData

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

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, zostanie przekształcony 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 API Google Cloud. 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 protokołu OAuth 2.0 interfejsu API Google, o które chcesz poprosić o dostęp.

Powiązane uprawnienia

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

getGoogleScript

Pobiera zasób z określonego zestawu skryptów Google i zwraca obietnicę ze skryptem i powiązanymi metadanymi pamięci podręcznej.

Obietnica zostanie rozwiązana w obiekcie zawierającym 2 klucze: script i metadata. Jeśli żądanie się nie powiedzie, obietnica zostanie odrzucona z kluczem reason.

Obiekt metadata będzie zawierać te metadane buforowania na podstawie nagłówków odpowiedzi zasobu. Każde pole będzie obecne tylko wtedy, gdy odpowiedni nagłówek znajduje się 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 string Nazwa skryptu. Obsługiwane skrypty to 'ANALYTICS', 'GTAG' i 'GTM'.

Opcja 'ANALYTICS' pobiera skrypt Google Analytics z 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 domeny https://www.googletagmanager.com/gtm.js.
options object Opcjonalne opcje żądania. Obsługiwane opcje znajdziesz poniżej.

Opcje

Opcja Typ Opis
id string Dotyczy 'GTAG' z identyfikatorem pomiaru gtag i 'GTM' z identyfikatorem kontenera internetowego (np. GTM-XXXX).
debug dowolny Jeśli wartość jest prawdziwa, żąda i zwraca wersję debugowania skryptu pomiarowego.
timeout number Czas oczekiwania na żądanie w milisekundach. Wartości nie dodatnie są ignorowane. Jeśli żądanie przekroczy limit czasu, wywołanie zwrotne 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 co najmniej do:

  • Zezwól na używanie domen Google

getRemoteAddress

Zwraca ciąg znaków reprezentujący adres IP, z którego pochodzi żądanie, np. 12.345.67.890 w przypadku IPv4 lub 2001:0db8:85a3:0:0:8a2e:0370:7334 w przypadku IPv6, odczytując nagłówki żądań, takie jak Forwarded i X-Forwarded-For. Uwaga: ten interfejs API podejmuje próbę wykrycia pierwotnego adresu IP, 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ć na dostęp co najmniej do:

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

getRequestBody

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

Składnia

getRequestBody();

Powiązane uprawnienia

read_request

getRequestHeader

Zwraca wartość nazwanego nagłówka żądania jako ciąg tekstowy, jeśli jest obecny, lub undefined w przeciwnym razie. Jeśli nagłówek jest powtórzony, zwrócone wartości są łączone za pomocą znaku ', '.

Przykład

const getRequestHeader = require('getRequestHeader');

const host = getRequestHeader('host');

Składnia

getRequestHeader(headerName);

Parametry

Parametr Typ Opis
headerName string Nazwa nagłówka. Wielkość liter w tej wartości nie jest rozróżniana.

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', funkcja zwraca '/foo'. Automatycznie usuwa z ścieżki prefiks adresu URL kontenera serwera. Jeśli np. adres URL kontenera serwera to https://example.com/analytics, a ścieżka żądania to '/analytics/foo', ta funkcja zwraca 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 zdekodowaną wartość nazwanego parametru ciągu zapytania jako ciąg znaków lub undefined, jeśli parametr nie jest obecny. Jeśli parametr powtarza się w ciągu zapytania, zwracana jest pierwsza wartość, która pojawia się w tym ciągu.

Przykład

const getRequestQueryParameter = require('getRequestQueryParameter');

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

Składnia

getRequestQueryParameter(name);

Parametry

Parametr Typ Opis
name string 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 w żądaniu w postaci ciągu znaków bez początkowego 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

Wycofano. Zalecamy używanie funkcji getTimestampMillis.

Zwraca liczbę reprezentującą bieżący czas w milisekundach od początku epoki systemu Unix, zgodnie z wartością zwracaną przez Date.now().

Składnia

getTimestamp();

Powiązane uprawnienia

Brak.

getTimestampMillis

Zwraca liczbę reprezentującą bieżący czas w milisekundach od początku epoki systemu Unix, zgodnie z wartością zwracaną przez Date.now().

Składnia

getTimestampMillis();

Powiązane uprawnienia

Brak.

getType

Zwraca ciąg tekstowy opisujący typ danej wartości.

Typ wejściowy Zwracana wartość
string 'string'
number '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 HMAC z SHA-256. Domyślnie używane jest kodowanie base64url.

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

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

Wartości to klucze HMAC zakodowane w formacie base64. Tekst JSON nie może zaczynać się od znacznika 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 string Dane do obliczenia wartości HMAC.
keyId string Identyfikator klucza z pliku kluczy JSON, który odnosi się do klucza, którego chcesz użyć.
options object Opcjonalna konfiguracja interfejsu API. (Zobacz Opcje poniżej).

Opcje

Opcja Typ Opis
outputEncoding string Określa format kodowania wartości zwracanej. Obsługiwane formaty to hex, base64 lub base64url. Jeśli nie zostanie podana, domyślnie przyjmuje wartość base64url.

Powiązane uprawnienia

use_custom_private_keys

Minimalna wersja obrazu

1.0.0

isRequestMpv1

Zwraca wartość true, jeśli przychodzące żądanie jest żądaniem Measurement Protocol w wersji 1, lub false w innych przypadkach.

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 przychodzące żądanie jest żądaniem Measurement Protocol 2, lub false w innych przypadkach.

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 logach 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, z którego każdy jest w razie potrzeby konwertowany na ciąg znaków i rejestrowany w konsoli.

Powiązane uprawnienia

logging

makeInteger

Konwertuje podaną wartość na liczbę (całkowitą).

Składnia

makeInteger(value);

Parametry

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

Powiązane uprawnienia

Brak.

makeNumber

Konwertuje podaną wartość na liczbę.

Składnia

makeNumber(value);

Parametry

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

Powiązane uprawnienia

Brak.

makeString

Zwraca podaną 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 do przekształcania pola szablonu SIMPLE_TABLE z 2 kolumnami w łatwiejszy w obsłudze format.

Na przykład ta funkcja może przekształcić obiekt tabeli:

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

na mapę:

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

Zwraca obiekt: dodano do niego przekonwertowane Map par klucz-wartość lub null w innych przypadkach.

Składnia

makeTableMap(tableObj, keyColumnName, valueColumnName);

Parametry

Parametr Typ Opis
tableObj Wyświetl listę Obiekt tabeli do przekonwertowania. Jest to lista map, w której każdy element Map reprezentuje wiersz w tabeli. 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 string Nazwa kolumny, której wartości staną się kluczami w przekonwertowanym plikuMap.
valueColumnName string Nazwa kolumny, której wartości staną się wartościami w przekonwertowanym polu Map.

Powiązane uprawnienia

Brak.

parseUrl

Zwraca obiekt zawierający wszystkie części składowe danego adresu URL, podobnie jak obiekt URL.

W przypadku nieprawidłowego adresu URL ten interfejs API zwróci wartość undefined. W przypadku prawidłowo sformatowanych adresów URL pola, które nie występują w ciągu adresu URL, będą miały wartość pustego ciągu znaków lub, w przypadku pola searchParams, pustego obiektu.

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:xyz@example.com:8080/foo?param=val%2Cue#bar');

Składnia

parseUrl(url);

Parametry

Parametr Typ Opis
url string Pełny adres URL, który zostanie przeanalizowany.

Powiązane uprawnienia

Brak.

returnResponse

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

Zalecamy używanie tego interfejsu API w szablonie klienta.

Składnia

returnResponse();

Przykład

Zobacz runContainer przykład.

Powiązane uprawnienia

return_response

runContainer

Uruchamia logikę kontenera (zmienne, reguły, tagi) 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 bindToEvent, aby uruchomić interfejs API w kontekście wydarzenia. Więcej informacji znajdziesz w przykładzie addEventCallback.

Zalecamy używanie tego interfejsu API w szablonie 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 Wywołanie zwrotne, które jest wywoływane po uruchomieniu wszystkich tagów.
onStart function Funkcja zwrotna wywoływana natychmiast, zanim zaczną się uruchamiać tagi.

Powiązane uprawnienia

run_container

sendEventToGoogleAnalytics

Wysyła do Google Analytics pojedyncze zdarzenie za pomocą danych zdarzenia wspólnego i zwraca obietnicę, która jest rozwiązywana jako obiekt z kluczem location lub odrzucana jako obiekt z kluczem reason. Miejsce docelowe, czyli Google Analytics 4, jest określane na podstawie identyfikatora pomiaru w danych zdarzenia.

Pole location jest ustawione na nagłówek location, jeśli 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 co najmniej do:

  • Zezwól na używanie domen Google

sendHttpGet

Wysyła żądanie HTTP GET na określony adres URL i zwraca obietnicę, która jest realizowana z wynikiem po zakończeniu żądania lub przekroczeniu limitu czasu.

Wynikiem jest obiekt zawierający 3 klucze: statusCode, headers i body. Jeśli żądanie się nie powiedzie (np. nieprawidłowy adres URL, brak trasy do hosta, nieudane negocjacje SSL itp.), obietnica zostanie odrzucona z błędem: {reason: 'failed'}. Jeśli opcja timeout została ustawiona, a limit czasu żądania upłynął, obietnica zostanie odrzucona z tym błędem: {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 string Żądany adres URL.
options object Opcjonalne opcje żądania. (Zobacz Opcje poniżej).

Opcje

Opcja Typ Opis
headers string Dodatkowe nagłówki żądań.
timeout number Czas oczekiwania (w milisekundach) przed przerwaniem żądania. Domyślna wartość to 15000.
authorization object Opcjonalny obiekt autoryzacji z wywołania funkcji getGoogleAuth, który umożliwia dołączanie nagłówków autoryzacji podczas wysyłania żądań do usługi googleapis.com.

Powiązane uprawnienia

send_http

sendHttpRequest

Wysyła żądanie HTTP na określony adres URL i zwraca obietnicę, która jest spełniana po zakończeniu żądania lub przekroczeniu limitu czasu.

Wynikiem jest obiekt zawierający 3 klucze: statusCode, headers i body. Jeśli żądanie się nie powiedzie (np. nieprawidłowy adres URL, brak trasy do hosta, nieudane negocjacje SSL itp.), obietnica zostanie odrzucona z błędem: {reason: 'failed'}. Jeśli opcja timeout została ustawiona, a limit czasu żądania upłynął, obietnica zostanie odrzucona z tym błędem: {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 string Żądany adres URL.
options object Opcjonalne opcje żądania. (Zobacz Opcje poniżej).
body string Opcjonalna treść żądania.

Opcje

Opcja Typ Opis
headers string Dodatkowe nagłówki żądań.
method object Metoda żądania. Domyślna wartość to GET.
timeout number Czas oczekiwania (w milisekundach) przed przerwaniem żądania. Domyślna wartość to 15000.
authorization object Opcjonalny obiekt autoryzacji z wywołania funkcji getGoogleAuth, który umożliwia dołączanie nagłówków autoryzacji podczas wysyłania żądań do usługi googleapis.com.

Powiązane uprawnienia

send_http

sendPixelFromBrowser

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

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

Przykład:

const sendPixelFromBrowser = require('sendPixelFromBrowser');

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

Składnia

sendPixelFromBrowser(url)

Parametry

Parametr Typ Opis
url string Adres URL, który ma zostać wysłany do przeglądarki.

Powiązane uprawnienia

send_pixel_from_browser

setCookie

Ustawia lub usuwa plik cookie z określonymi opcjami.

Aby usunąć plik cookie, musisz ustawić plik cookie z tą samą ścieżką i domeną, w której został utworzony, i przypisać mu wartość wygaśnięcia z przeszłości, np. "Thu, 01 Jan 1970 00:00:00 GMT".

Pamiętaj, że aby odpowiedź została odesłana do klienta, musisz wywołać funkcję 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 string Nazwa pliku cookie. W nazwie nie jest rozróżniana wielkość liter.
value string Wartość pliku cookie.
options object Opcjonalne atrybuty plików cookie:domain, expires, fallbackDomain, httpOnly, max-age, path, secure i sameSite. (Zobacz Opcje poniżej).
noEncode wartość logiczna Jeśli wartość to „prawda”, wartość pliku cookie nie będzie kodowana. 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 obliczony zgodnie z tą strategią:

    • eTLD+1 nagłówka Forwarded, jeśli jest obecny.
    • eTLD+1 nagłówka X-Forwarded-Host, jeśli jest obecny.
    • eTLD+1 nagłówka Host.

  • expires: maksymalny okres ważności pliku cookie. Musi to być ciąg daty w formacie UTC, np. „Sat, 26 Oct 1985 08:21:00 GMT”. Jeśli ustawione są zarówno wartości expires, jak i max-age, pierwszeństwo ma wartość 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ść zero lub ujemna spowoduje natychmiastowe wygaśnięcie pliku cookie. Jeśli ustawione są zarówno parametr expires, jak i parametr max-age, pierwszeństwo ma parametr max-age.

  • path: ś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 będzie wysyłany na serwer tylko wtedy, gdy żądanie zostanie wysłane z punktu końcowego https:.

  • sameSite: potwierdza, że plik cookie nie może być wysyłany w przypadku żądań z innych domen. Musi to być wartość 'strict', 'lax' lub 'none'.

Powiązane uprawnienia

set_cookie

setPixelResponse

Ustawia treść odpowiedzi na GIF-a o rozmiarach 1x1, ustawia nagłówek Content-Type na „image/gif”, ustawia nagłówki buforowania tak, aby agenci użytkownika nie buforowali odpowiedzi, i ustawia stan odpowiedzi na 200.

Pamiętaj, że aby odpowiedź została odesłana do klienta, musisz wywołać funkcję returnResponse.

Składnia

setPixelResponse();

Powiązane uprawnienia

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

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

setResponseBody

Ustawia treść odpowiedzi na argument.

Pamiętaj, że aby odpowiedź została odesłana do klienta, musisz wywołać funkcję returnResponse.

Składnia

setResponseBody(body[, encoding]);

Parametry

Parametr Typ Opis
body string Wartość, która ma być ustawiona jako treść odpowiedzi.
encoding string Kodowanie znaków treści 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ć na dostęp co najmniej do:

  • body

setResponseHeader

Ustawia nagłówek w zwracanej odpowiedzi. Jeśli nagłówek o tej nazwie (bez uwzględniania wielkości liter) został wcześniej ustawiony przez ten interfejs API, późniejsze wywołanie zastąpi lub wyczyści wartość ustawioną przez poprzedniego wywołującego.

Pamiętaj, że aby odpowiedź została odesłana do klienta, musisz wywołać funkcję returnResponse.

Składnia

setResponseHeader(name, value);

Parametry

Parametr Typ Opis
name string Nazwa nagłówka. W nazwach nagłówków HTTP nie jest rozróżniana wielkość liter, więc nazwa nagłówka zostanie zapisana małymi literami.
value string undefined Wartość nagłówka. Jeśli wartość to null lub undefined, powoduje to usunięcie nazwanego nagłówka z odpowiedzi, która zostanie zwrócona.

Powiązane uprawnienia

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

  • headers

setResponseStatus

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

Pamiętaj, że aby odpowiedź została odesłana do klienta, musisz wywołać funkcję returnResponse.

Składnia

setResponseStatus(statusCode);

Parametry

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

Powiązane uprawnienia

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

  • status

sha256

Oblicza skrót SHA-256 danych wejściowych i wywołuje wywołanie zwrotne ze skrótem zakodowanym w formacie base64, chyba że obiekt options określa inne kodowanie wyjściowe.

Sygnatura i działanie tego interfejsu API są zgodne z interfejsem sha256 API w przypadku kontenerów internetowych. Szablony niestandardowe w kontenerach serwera powinny jednak 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 string Ciąg znaków do zaszyfrowania.
onSuccess function Wywoływana z wynikowym skrótem zakodowanym w formacie Base64, chyba że obiekt options określa inne kodowanie wyjściowe.
options object Opcjonalny obiekt opcji określający kodowanie danych wyjściowych. Jeśli obiekt został określony, powinien zawierać klucz outputEncoding z wartością base64 lub hex.

Powiązane uprawnienia

Brak.

sha256Sync

Oblicza i zwraca skrót SHA-256 danych wejściowych zakodowany w formacie base64, chyba że obiekt options określa inne kodowanie wyjściowe.

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 string Ciąg znaków do zaszyfrowania.
options object Opcjonalny obiekt opcji określający kodowanie danych wyjściowych. Jeśli obiekt został określony, 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 szablonu umożliwia udostępnianie danych w ramach wielu wykonań jednego szablonu. Dane przechowywane w pamięci danych szablonu są zachowywane na serwerze, na którym działa kontener. W większości przypadków kontener jest uruchamiany na wielu serwerach, więc przechowywanie danych w pamięci danych szablonu nie gwarantuje, że każde kolejne żądanie będzie miało do nich dostęp.

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

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

Sprawdza, czy ciąg znaków pasuje do wyrażenia regularnego utworzonego za pomocą interfejsu createRegex API. Zwraca true, jeśli wyrażenie regularne jest zgodne. W przeciwnym razie zwraca wartość false.

Wyrażenie regularne utworzone z flagą globalną jest stanowe. Szczegółowe informacje 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 do testowania, zwracane przez interfejs createRegex API.
string string Ciąg testowy do przetestowania.

Powiązane uprawnienia

Brak.

toBase64

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

Składnia

toBase64(input, options);

Parametry

Parametr Typ Opis
input string Ciąg znaków do zakodowania.
options object Opcjonalna konfiguracja interfejsu API. (Zobacz 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 obietnicę, która jest spełniana po pomyślnym wstawieniu lub odrzucana w przypadku błędu.

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

Jeśli wstawianie się nie powiedzie, obietnica zostanie odrzucona z listą obiektów zawierających przyczynę błędu i ewentualnie obiekt wiersza, jeśli wystąpi błąd. Możliwe jest, że część żądania zostanie 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 wstawionych wierszy (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. Dostępny jest 1 parametr opcjonalny i 2 parametry wymagane:
  • projectId – opcjonalny identyfikator projektu Google Cloud Platform. Jeśli ten parametr zostanie pominięty, wartość projectId zostanie pobrana ze 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, zmienna 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 do tabeli.
options object Opcjonalne opcje żądania. Obsługiwane opcje to:ignoreUnknownValues i skipInvalidRows. Nieznane klucze opcji są ignorowane. (Zobacz Opcje poniżej).

Opcje

Parametr Typ Opis
ignoreUnknownValues wartość logiczna Jeśli ta opcja jest ustawiona na true, akceptuj wiersze zawierające wartości, które nie pasują do schematu. Nieznane wartości są ignorowane. Domyślna wartość to false.
skipInvalidRows wartość logiczna Jeśli ustawisz wartość true, wstawisz 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 korzysta ze starszej wersji naszego obrazu, która nie zawierała jeszcze modułu BigQuery. Ponownie wdróż kontener serwera z tymi samymi ustawieniami, korzystając z naszego skryptu wdrażania. Po zakończeniu operacji moduł zostanie automatycznie uwzględniony.

Błąd związany z brakiem wstawienia zwykle zawiera 1 obiekt błędu z kluczem reason:

[{reason: 'invalid'}]

Błąd wstawiania może zawierać wiele obiektów błędów z tablicą errors i obiektem row. Oto przykład odpowiedzi o błędzie podczas wstawiania 2 wierszy, z których tylko 1 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 też tylko domyślną bazę danych.

Firestore.read

Funkcja Firestore.read odczytuje dane z dokumentu Firestore i zwraca obietnicę, która jest rozwiązywana jako obiekt zawierający 2 klucze: id i data. Jeśli dokument nie istnieje, obietnica zostanie odrzucona z obiektem zawierającym klucz reason o wartości not_found.

Składnia

Firestore.read(path[, options]);

Parametry

Parametr Typ Opis
path string Ścieżka do dokumentu lub kolekcji. Nie może zaczynać się ani kończyć znakiem „/”.
options object Opcjonalne opcje żądania. Obsługiwane opcje to: projectId, disableCache i transaction. Klucze opcji Unknown są ignorowane. (Zobacz Opcje poniżej).

Opcje

Parametr Typ Opis
projectId string Opcjonalnie. Identyfikator projektu Google Cloud Platform. Jeśli ten parametr zostanie pominięty, wartość projectId zostanie pobrana ze zmiennej środowiskowej GOOGLE_CLOUD_PROJECT, o ile ustawienie uprawnień access_firestore dla identyfikatora projektu ma wartość * lub GOOGLE_CLOUD_PROJECT. Jeśli kontener serwera działa w Google Cloud, zmienna GOOGLE_CLOUD_PROJECT będzie już ustawiona na identyfikator projektu Google Cloud.
disableCache wartość logiczna Opcjonalnie. Określa, czy pamięć podręczna ma zostać wyłączona. Pamięć podręczna jest domyślnie włączona, co oznacza, że wyniki będą przechowywane w pamięci podręcznej przez czas trwania żądania.
transaction string Opcjonalnie. Wartość pobrana z funkcji Firestore.runTransaction(). Oznacza operację, która ma być używana w 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 jest rozwiązywana jako identyfikator dodanego lub zmodyfikowanego dokumentu. Jeśli użyjesz opcji transakcji, interfejs API nadal zwróci obietnicę, ale nie będzie ona zawierać identyfikatora, ponieważ zapisy są wykonywane w pakietach.

Składnia

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

Parametry

Parametr Typ Opis
path string Ścieżka do dokumentu lub kolekcji. Nie może zaczynać się ani kończyć znakiem „/”.
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 żądania. Obsługiwane opcje to: projectId, merge i transaction. Nieznane klucze opcji są ignorowane. (Zobacz Opcje poniżej).

Opcje

Parametr Typ Opis
projectId string Opcjonalnie. Identyfikator projektu Google Cloud Platform. Jeśli ten parametr zostanie pominięty, wartość projectId zostanie pobrana ze zmiennej środowiskowej GOOGLE_CLOUD_PROJECT, o ile ustawienie uprawnień access_firestore dla identyfikatora projektu ma wartość * lub GOOGLE_CLOUD_PROJECT. Jeśli kontener serwera działa w Google Cloud, zmienna GOOGLE_CLOUD_PROJECT będzie już ustawiona na identyfikator projektu Google Cloud.
merge wartość logiczna Opcjonalnie. Jeśli wartość to true, klucze z danych wejściowych zostaną scalone z dokumentem. W przeciwnym razie metoda zastąpi cały dokument. Domyślna wartość to false.
transaction string Opcjonalnie. Wartość pobrana z funkcji Firestore.runTransaction(). Oznacza operację, która ma być używana w 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 jest rozwiązywana jako tablica dokumentów Firestore pasujących do warunków zapytania. Obiekt dokumentu Firestore jest taki sam jak wymieniony powyżej w sekcji Firestore.read. Jeśli nie ma dokumentów spełniających warunki zapytania, zwrócona obietnica zostanie rozwiązana jako pusta tablica.

Składnia

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

Parametry

Parametr Typ Opis
collection string Ścieżka do kolekcji. Nie może zaczynać się ani kończyć znakiem „/”.
queryConditions Tablica Tablica warunków zapytania. Każde zapytanie ma postać tablicy z 3 wartościami: klucz, operator i oczekiwanaWartość. np.: [[‘id’, ‘<’, ‘5’], [‘state’, ‘==’, ‘CA’]].

Warunki są połączone operatorem AND, aby utworzyć wynik zapytania. Listę zgodnych operatorów zapytań znajdziesz w operatorach zapytań Firestore.
options object Opcjonalne opcje żądania. Obsługiwane opcje to: projectId, disableCache, limit i transaction. Klucze opcji Unknown są ignorowane. (Zobacz Opcje poniżej).

Opcje

Parametr Typ Opis
projectId string Opcjonalnie. Identyfikator projektu Google Cloud Platform. Jeśli ten parametr zostanie pominięty, wartość projectId zostanie pobrana ze zmiennej środowiskowej GOOGLE_CLOUD_PROJECT, o ile ustawienie uprawnień access_firestore dla identyfikatora projektu ma wartość * lub GOOGLE_CLOUD_PROJECT. Jeśli kontener serwera działa w Google Cloud, zmienna GOOGLE_CLOUD_PROJECT będzie już ustawiona na identyfikator projektu Google Cloud.
disableCache wartość logiczna Opcjonalnie. Określa, czy pamięć podręczna ma zostać wyłączona. Pamięć podręczna jest domyślnie włączona, co oznacza, że wyniki będą przechowywane w pamięci podręcznej przez czas trwania żądania.
limit number Opcjonalnie. Zmienia maksymalną liczbę wyników zwracanych przez zapytanie. Domyślna wartość to 5.
transaction string Opcjonalnie. Wartość pobrana z funkcji Firestore.runTransaction(). Oznacza operację, która ma być używana w 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 atomowe odczytywanie i zapisywanie danych w Firestore. Jeśli wystąpi jednoczesny zapis lub inny konflikt transakcji, transakcja zostanie ponowiona maksymalnie 2 razy. Jeśli po 3 próbach nie uda się tego zrobić, interfejs API odrzuci żądanie i zwróci błąd. Ten interfejs API zwraca obietnicę, która w przypadku powodzenia transakcji jest rozwiązywana jako tablica identyfikatorów dokumentów dla każdej operacji zapisu, a w przypadku niepowodzenia jest odrzucana z błędem.

Składnia

Firestore.runTransaction(callback[, options]);

Parametry

Parametr Typ Opis
callback function Wywołanie zwrotne, które jest wywoływane z identyfikatorem transakcji w formie ciągu znaków. Identyfikator transakcji można przekazywać do wywołań interfejsu API do odczytu, zapisu i wykonywania zapytań. To wywołanie zwrotne musi zwracać obietnicę. Wywołanie zwrotne może zostać wykonane maksymalnie 3 razy, zanim zakończy się niepowodzeniem.
options object Opcjonalne opcje żądania. Jedyną obsługiwaną opcją jest projectId. Nieznane klucze opcji są ignorowane. (Zobacz Opcje poniżej).

Opcje

Parametr Typ Opis
projectId string Opcjonalnie. Identyfikator projektu Google Cloud Platform. Jeśli ten parametr zostanie pominięty, wartość projectId zostanie pobrana ze zmiennej środowiskowej GOOGLE_CLOUD_PROJECT, o ile ustawienie uprawnień access_firestore dla identyfikatora projektu ma wartość * lub GOOGLE_CLOUD_PROJECT. Jeśli kontener serwera działa w Google Cloud, zmienna GOOGLE_CLOUD_PROJECT będzie już ustawiona na 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 są dostępne w każdej funkcji Firestore i będą odrzucane z obiektem zawierającym klucz reason:

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

Przyczyny błędu mogą obejmować m.in. kody błędów interfejsu Firestore REST 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. nieprawidłowy format JSON), funkcja zwróci undefined. Jeśli wartość wejściowa nie jest ciągiem znaków, zostanie przekształcona w ciąg znaków.

Funkcja stringify() konwertuje dane wejściowe na ciąg znaków w formacie JSON. Jeśli wartości nie można przeanalizować (np. obiekt ma cykl), metoda zwraca 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ą przekształcane w liczby.

Powiązane uprawnienia

Brak.

Messages

Te interfejsy API współpracują ze sobą, aby umożliwić przekazywanie wiadomości między różnymi częściami kontenera.

addMessageListener

Dodaje funkcję, która nasłuchuje wiadomości określonego typu. Gdy wiadomość tego typu zostanie wysłana za pomocą interfejsu sendMessage API (zwykle przez tag), wywołanie zwrotne zostanie wykonane synchronicznie. Wywołanie zwrotne jest wykonywane z 2 parametrami:

  1. messageType:string
  2. message:Object

Jeśli wywołanie zwrotne zostanie dodane w kliencie, będzie otrzymywać wiadomości ze wszystkich zdarzeń utworzonych przez tego klienta. Jeśli wywołanie zwrotne ma otrzymywać wiadomości tylko z określonego zdarzenia, powiąż ten interfejs API ze zdarzeniem za pomocą bindToEvent w funkcji onStart interfejsu API runContainer. 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 string Typ wiadomości, której chcesz nasłuchiwać. Jeśli wartość nie jest ciągiem znaków, zostanie przekształcona w ciąg znaków.
callback function Funkcja zwrotna, która ma zostać uruchomiona po wysłaniu wiadomości odpowiedniego typu. Jeśli wywołanie zwrotne nie jest funkcją, interfejs API nie podejmie żadnych działań.

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. Uprawnienia muszą być skonfigurowane tak, aby zezwalać co najmniej na:

  • Typ wiadomości z wartością Usage równą listen lub listen_and_send.

hasMessageListener

Zwraca wartość „true”, jeśli dodano odbiornik wiadomości dla danego typu 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 odbiorcy. Może to służyć 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 string Typ wiadomości do wysłania. Jeśli wartość nie jest ciągiem znaków, zostanie przekształcona w ciąg znaków.
message object Wiadomość do wysłania. Jeśli wiadomość nie jest obiektem, interfejs API nie podejmie żadnych działań.

Powiązane uprawnienia

Wymaga uprawnień use_message. Uprawnienia muszą być skonfigurowane tak, aby zezwalać co najmniej na:

  • Typ wiadomości z wartością Usage równą listen_and_send lub send.

Object

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

Metoda keys() zapewnia działanie Object.keys() biblioteki standardowej. Zwraca tablicę nazw własnych, wyliczalnych właściwości danego obiektu w tej samej kolejności, w jakiej zrobiłaby to pętla for...in.... Jeśli wartość wejściowa nie jest obiektem, zostanie przekształcona w obiekt.

Metoda values() zapewnia działanie funkcji Object.values() z biblioteki standardowej. Zwraca tablicę wartości własnych właściwości obiektu, które można wyliczyć, w tej samej kolejności, w jakiej zwróciłaby je pętla for...in.... Jeśli wartość wejściowa nie jest obiektem, zostanie przekształcona w obiekt.

Metoda entries() zapewnia działanie funkcji Object.entries() z biblioteki standardowej. Zwraca tablicę par [key, value] własnych, wyliczalnych właściwości danego obiektu w tej samej kolejności, w jakiej zwróciłaby je pętla for...in.... Jeśli wartość wejściowa nie jest obiektem, zostanie przekształcona w obiekt.

Metoda freeze() zapewnia działanie Object.freeze() z biblioteki standardowej. Zamrożonego obiektu nie można już zmieniać. Zamrożenie obiektu uniemożliwia dodawanie do niego nowych właściwości, usuwanie istniejących właściwości i zmianę wartości istniejących właściwości. freeze() zwraca ten sam obiekt, który został przekazany. Argument typu prostego lub argument o wartości null będzie traktowany jako zamrożony obiekt i zostanie zwrócony.

Metoda delete() zapewnia działanie operatora usuwania z biblioteki standardowej. Usuwa podany klucz z obiektu, chyba że obiekt jest zamrożony. Podobnie jak operator usuwania w bibliotece standardowej zwraca wartość 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ę jednak od operatora usuwania z biblioteki standardowej tym, że:

  • keyToDelete nie może być ciągiem znaków rozdzielonym kropkami, który określa klucz zagnieżdżony.
  • Nie można użyć funkcji delete() do usunięcia elementów z tablicy.
  • Za pomocą parametru delete() nie można usuwać żadnych 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ą zostać wyliczone. Jeśli dane wejściowe nie są obiektem, zostaną przekształcone w obiekt.

Object.values

Parametr Typ Opis
objectInput dowolny Obiekt, którego wartości mają być wyliczane. Jeśli dane wejściowe nie są obiektem, zostaną przekształcone w 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ą przekształcone w obiekt.

Object.freeze

Parametr Typ Opis
objectInput dowolny Obiekt do zamrożenia. Jeśli dane wejściowe nie są obiektem, będą traktowane jako zamrożony obiekt.

Object.delete

Parametr Typ Opis
objectInput dowolny Obiekt, którego klucz ma zostać usunięty.
keyToDelete string Klucz najwyższego poziomu do usunięcia.

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żda instancja ma 3 metody, które zwracają obiekt Promise, co umożliwia dalsze działanie po rozstrzygnięciu obietnicy:

  • .then() – obsługuje zarówno rozwiązane, jak i odrzucone zgłoszenia. Przyjmuje 2 funkcje zwrotne jako parametry: jedną w przypadku powodzenia i jedną w przypadku niepowodzenia.
  • .catch() – obsługuje tylko odrzucone zgłoszenia. Przyjmuje jedno wywołanie zwrotne jako parametr.
  • .finally() – umożliwia uruchomienie kodu niezależnie od tego, czy obietnica została spełniona czy odrzucona. Przyjmuje jako parametr jedną funkcję wywołania zwrotnego, która jest wywoływana bez argumentu.

Zmienna, która zwraca obietnicę, jest równa rozwiązanej wartości obietnicy lub false, jeśli obietnica zostanie odrzucona.

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:

  • zostanie rozwiązana, gdy wszystkie dane wejściowe zostaną rozwiązane, lub
  • odrzuca, gdy którekolwiek z danych wejściowych zostanie odrzucone.

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 rozwiązaną wartością obietnicy. Zwraca 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 jest funkcjonalnie 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ócony obiekt Promise zostanie rozwiązany lub odrzucony, gdy zostanie wywołany odpowiedni parametr. Zwraca błąd, jeśli funkcja rozpoznawania 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 JavaScriptu w piaskownicy, aby tworzyć testy szablonów niestandardowych w Menedżerze tagów Google. Te interfejsy API do testowania nie wymagają require()oświadczenia. [Więcej informacji o testach szablonów niestandardowych]

assertApi

Zwraca obiekt dopasowania, którego można użyć do płynnego tworzenia asercji dotyczących danego interfejsu API.

Składnia

assertApi(apiName)

Parametry

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

Dopasowywanie

  • 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 assertThat API jest wzorowany na bibliotece [Truth] Google. Zwraca obiekt, którego można użyć do płynnego tworzenia asercji dotyczących wartości obiektu. Błąd asercji natychmiast zatrzyma test i oznaczy go jako nieudany. Niepowodzenie w jednym teście 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 string Opcjonalna wiadomość do wydrukowania, jeśli asercja się nie powiedzie.

Dopasowywanie

Matcher Opis
isUndefined() Potwierdza, że podmiot jest undefined.
isDefined() Potwierdza, że podmiot nie jest undefined.
isNull() Potwierdza, że podmiot jest null.
isNotNull() Potwierdza, że podmiot nie jest null.
isFalse() Potwierdza, że podmiot jest false.
isTrue() Potwierdza, że podmiot jest true.
isFalsy() Sprawdza, czy obiekt jest fałszywy. Wartości fałszywe to undefined, null, false, NaN, 0 i „” (pusty ciąg znaków).
isTruthy() Sprawdza, czy element jest prawdziwy. Wartości fałszywe to undefined, null, false, NaN, 0 i „” (pusty ciąg znaków).
isNaN() Sprawdza, czy podmiot jest wartością NaN.
isNotNaN() Sprawdza, czy obiekt ma dowolną wartość inną niż NaN.
isInfinity() Sprawdza, czy wartość jest dodatnią lub ujemną nieskończonością.
isNotInfinity() Sprawdza, czy wartość nie jest dodatnią ani ujemną nieskończonością.
isEqualTo(expected) Sprawdza, czy obiekt jest równy podanej wartości. Jest to porównanie wartości, a nie porównanie referencyjne. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
isNotEqualTo(expected) Sprawdza, czy podmiot nie jest równy podanej wartości. Jest to porównanie wartości, a nie porównanie referencyjne. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
isAnyOf(...expected) Sprawdza, czy obiekt jest równy jednej z podanych wartości. Jest to porównanie wartości, a nie porównanie referencyjne. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
isNoneOf(...expected) Stwierdza, że podmiot nie jest równy żadnej z podanych wartości. To porównanie wartości, a nie porównanie referencyjne. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
isStrictlyEqualTo(expected) Sprawdza, czy obiekt jest ściśle równy (===) podanej wartości.
isNotStrictlyEqualTo(expected) Stwierdza, że podmiot nie jest ściśle równy (!==) podanej wartości.
isGreaterThan(expected) Sprawdza, czy wartość jest większa niż (>) podana wartość w porównaniu uporządkowanym.
isGreaterThanOrEqualTo(expected) Sprawdza, czy wartość jest większa lub równa (>=) podanej wartości w porównaniu uporządkowanym.
isLessThan(expected) Sprawdza, czy wartość jest mniejsza niż (<) podana wartość w porównaniu uporządkowanym.
isLessThanOrEqualTo(expected) Sprawdza, czy wartość jest mniejsza lub równa (<=) podanej wartości w porównaniu uporządkowanym.
contains(...expected) Sprawdza, czy obiekt jest tablicą lub ciągiem znaków, który zawiera wszystkie podane wartości w dowolnej kolejności. Jest to porównanie wartości, a nie porównanie referencyjne. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
doesNotContain(...expected) Sprawdza, czy obiekt jest tablicą lub ciągiem, który nie zawiera żadnej z podanych wartości. Jest to porównanie wartości, a nie porównanie referencyjne. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
containsExactly(...expected) Sprawdza, czy obiekt jest tablicą, która zawiera wszystkie podane wartości w dowolnej kolejności i nie zawiera żadnych innych wartości. Jest to porównanie wartości, a nie porównanie referencyjne. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
doesNotContainExactly(...expected) Sprawdza, czy obiekt jest tablicą, która zawiera inny zestaw wartości niż podane wartości w dowolnej kolejności. To porównanie wartości, a nie porównanie referencyjne. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
hasLength(expected) Sprawdza, czy obiekt jest tablicą lub ciągiem znaków o podanej długości. Jeśli wartość nie jest tablicą ani ciągiem znaków, asercja zawsze kończy się niepowodzeniem.
isEmpty() Sprawdza, czy obiekt jest pustą tablicą lub pustym ciągiem znaków (długość ≤ 0). Jeśli wartość nie jest tablicą ani ciągiem znaków, asercja zawsze kończy się niepowodzeniem.
isNotEmpty() Sprawdza, czy obiekt jest tablicą lub ciągiem znaków, który nie jest pusty (długość > 0). Jeśli wartość nie jest tablicą ani ciągiem znaków, asercja zawsze kończy się niepowodzeniem.
isArray() Sprawdza, czy typ podmiotu jest tablicą.
isBoolean() Sprawdza, czy typ podmiotu to wartość logiczna.
isFunction() Sprawdza, czy typ obiektu jest funkcją.
isNumber() Sprawdza, czy typ podmiotu jest liczbą.
isObject() Stwierdza, że typ podmiotu jest obiektem.
isString() Sprawdza, czy typ podmiotu 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 przerywa bieżący test i wyświetla podany komunikat (jeśli został podany).

Składnia

fail(opt_message);

Parametry

Parametr Typ Opis
opt_message string Opcjonalny tekst komunikatu o błędzie.

Przykład

fail('This test has failed.');

mock

Interfejs mock API umożliwia zastępowanie działania interfejsów API w piaskownicy. Interfejs Mock API można bezpiecznie stosować w kodzie szablonu, ale działa on tylko w trybie testowym. Makiety są resetowane przed uruchomieniem każdego testu.

Składnia

mock(apiName, returnValue);

Parametry

Parametr Typ Opis
apiName string Nazwa interfejsu API do symulacji. Jest to ten sam ciąg znaków, który został przekazany do funkcji require()
returnValue dowolny Wartość do zwrócenia w przypadku interfejsu API lub funkcji wywoływanej zamiast interfejsu API. Jeśli returnValue jest funkcją, jest ona wywoływana zamiast interfejsu Sandboxed API. Jeśli returnValue jest czymś innym niż funkcją, zwracana jest ta wartość zamiast interfejsu Sandboxed API.

Przykłady

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

mockObject

Interfejs mockObject API umożliwia zastąpienie działania interfejsów Sandboxed API, które zwracają obiekt. Interfejs API jest bezpieczny w użyciu w kodzie szablonu, ale działa tylko w trybie testowym. Makiety są resetowane przed uruchomieniem każdego testu.

Składnia

mockObject(apiName, objectMock);

Parametry

Parametr Typ Opis
apiName string Nazwa interfejsu API do symulacji. Jest to ten sam ciąg znaków, który został przekazany do funkcji require()
objectMock object Wartość do zwrócenia w przypadku 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, a w przypadku wszystkich innych typów szablonów zwraca undefined.

Przykład

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