Interfejsy API tagowania po stronie serwera

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

addEventCallback

Rejestruje wywołanie zwrotne, które zostanie wywołane na końcu zdarzenia. Wywołanie zwrotne zostanie wywołane, gdy zostaną wykonane wszystkie tagi zdarzenia. Do 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 uzyskać więcej informacji, 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, która ma zostać wywołana na końcu zdarzenia.

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), stan jego wykonania (status) i czas jego wykonania (executionTime). Dane tagu będą też zawierać dodatkowe metadane tagu, które zostały w nim skonfigurowane.

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

Planuje asynchroniczne wywołanie funkcji. Funkcja zostanie wywołana po zwróceniu bieżącego kodu. 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 zgłosić żądanie. Po odebraniu żądania kontener nie uruchamia dodatkowych klientów.

Ten interfejs API zgłasza 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 asynchronicznym wywołaniu zwrotnym, takim jak w funkcji callLater lub runContainer onComplete).

Klient powinien zgłosić żądanie za pomocą tego interfejsu API przed wywołaniem interfejsu API 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) podanej domeny lub adresu URL. eTLD+1 jest obliczana przez ocenę domeny pod kątem reguł listy sufiksów publicznych. eTLD+1 to zwykle domena najwyższego poziomu, w której można ustawić plik cookie.

Jeśli argument ma wartość null lub jest niezdefiniowany, zwracana jest niezmieniona wartość argumentu. W przeciwnym razie argument jest wymuszany na ciąg znaków. Jeśli argument nie jest prawidłową domeną lub adresem URL, zwracany jest pusty ciąg znaków. 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 string Domena lub adres URL, dla którego ma zostać obliczona wartość eTLD+1.

Powiązane uprawnienia

Brak.

createRegex

Tworzy nową instancję wyrażenia regularnego i zwraca ją opakowaną w obiekt. Nie możesz uzyskać bezpośredniego dostępu do wyrażenia regularnego. Możesz jednak przekazać go do interfejsu 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 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 string Tekst wyrażenia regularnego.
flags string Opcjonalny ciąg znaków zawierający flagi tworzonego wyrażenia regularnego. Obsługiwane są flagi `g` (globalne) i `i` (bez rozróżniania wielkości liter). Wszystkie inne znaki są ignorowane.

Powiązane uprawnienia

Brak.

Minimalna wersja graficzna

2.0.0

decodeUri

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

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ą encodeUri() lub w inny sposób.

Powiązane uprawnienia

Brak.

decodeUriComponent

Dekoduje wszystkie zakodowane znaki w podanym komponencie identyfikatora URI. Zwraca ciąg znaków, który reprezentuje zdekodowany komponent identyfikatora URI. Zwraca undefined, gdy dane wejściowe są nieprawidłowe.

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 Komponent identyfikatora URI, który został zakodowany za pomocą encodeUriComponent() lub w inny sposób.

Powiązane uprawnienia

Brak.

encodeUri

Zwraca zakodowany identyfikator URI (Uniform Resource Identifier) przez pominięcie znaków specjalnych. Zwraca ciąg tekstowy, który reprezentuje podany ciąg tekstowy 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 (Uniform Resource Identifier) przez pominięcie znaków specjalnych. Zwraca ciąg tekstowy, który reprezentuje podany ciąg tekstowy 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 Komponent identyfikatora URI.

Powiązane uprawnienia

Brak.

extractEventsFromMpv1

Tłumaczy przychodzące żądanie Measurement Protocol w wersji 1 na listę zdarzeń w formacie ujednoliconego schematu. Zwraca listę wyodrębnionych zdarzeń. Jeśli żądanie nie ma prawidłowego formatu, zgłasza błąd.

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 uprawnienia read_request. Uprawnienie musi być skonfigurowane tak, aby zezwalać na dostęp co najmniej do:

  • body
  • query parameters

extractEventsFromMpv2

Tłumaczy przychodzące żądanie Measurement Protocol V2 na listę zdarzeń w formacie ujednoliconego schematu. Zwraca listę wyodrębnionych zdarzeń. Jeśli żądanie nie ma prawidłowego formatu, zgłasza błąd.

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 uprawnienia read_request. Uprawnienie musi być skonfigurowane tak, aby zezwalać na dostęp co najmniej do:

  • body
  • query parameters

fromBase64

Dekoduje ciąg zakodowany w formacie base64. Jeśli dane wejściowe są nieprawidłowe, zwraca undefined.

Składnia

fromBase64(base64EncodedString);

Parametry

Parametr Typ Opis
base64EncodedString string Ciąg znaków 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

getAnonymizedIpAddress

Zwraca zanonimizowany ciąg tekstowy reprezentujący adres IP, z którego pochodzi żądanie.

W przypadku adresów IPv4 ostatni oktet jest maskowany do 0 (np. 198.51.100.42 staje się 198.51.100.0). W przypadku adresów IPv6 ostatnie 80 bitów jest maskowane do zer, a pierwsze 48 bitów jest zachowywane (np. 2001:db8:cafe:1234:5678:90ab:cdef:1234 staje się 2001:db8:cafe::).

Zwraca "::", jeśli adres IP jest nieprawidłowy lub nie można go rozpoznać, więc wynik można zawsze bezpiecznie używać jako ip_override.

Przykład

const getAnonymizedIpAddress = require('getAnonymizedIpAddress');

const anonymizedIp = getAnonymizedIpAddress();

Składnia

getAnonymizedIpAddress();

Powiązane uprawnienia

user_ip

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 boolean Jeśli true, wartości plików cookie nie zostaną zdekodowane przed zwróceniem. Domyślna wartość to false.

Powiązane uprawnienia

get_cookies

getEventData

Zwraca kopię wartości w podanej ścieżce w danych zdarzenia. Zwraca undefined, jeśli nie ma danych zdarzenia lub nie ma wartości w podanej ś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 any Ś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 Google Cloud API. 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 interfejsów API Google protokołu OAuth 2.0, o dostęp do których chcesz poprosić.

Powiązane uprawnienia

Wymaga uprawnienia 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 buforowania.

Obiekt Promise zostanie przekształcony w obiekt zawierający 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 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 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 https://www.googletagmanager.com/gtm.js.
options object Opcjonalne opcje żądania. Poniżej znajdziesz obsługiwane opcje.

Opcje

Opcja Typ Opis
id string Dotyczy 'GTAG' z identyfikatorem pomiaru gtag i 'GTM' z identyfikatorem kontenera internetowego (np. GTM-XXXX).
debug any Jeśli ma wartość „prawda”, żąda wersji debugowania skryptu pomiarowego i ją zwraca.
timeout number Czas oczekiwania na żądanie w milisekundach. Wartości nieujemne są ignorowane. Jeśli upłynie limit czasu żądania, wywołanie zwrotne zostanie wywołane z wartością undefined dla skryptu i {} dla obiektu metadanych.

Nierozpoznane klucze opcji są ignorowane.

Powiązane uprawnienia

Wymaga uprawnienia send_http. Uprawnienie musi być skonfigurowane tak, aby zezwalać na dostęp do co najmniej tych elementów:

  • Zezwalanie na używanie domen w Google Domains

getRemoteAddress

Zwraca ciąg tekstowy 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 żądania, takie jak Forwarded i X-Forwarded-For. Uwaga: ten interfejs API stara się wykryć źródłowy adres IP, ale nie gwarantuje, że wynik będzie dokładny.

Składnia

getRemoteAddress();

Powiązane uprawnienia

Wymaga uprawnienia read_request. Uprawnienie musi 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 znaków, 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 istnieje, lub undefined w przeciwnym razie. Jeśli nagłówek się powtarza, zwracane wartości są łączone za pomocą ', '.

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 wartości nie jest rozróżniana.

Powiązane uprawnienia

read_request

getRequestMethod

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

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 na przykład adres URL to '/foo?id=123', funkcja zwraca '/foo'. Automatycznie usuwa prefiks adresu URL kontenera serwera ze ścieżki. Jeśli np. adres URL kontenera serwera to https://example.com/analytics, a ścieżka żądania to '/analytics/foo', zwrócona zostanie 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 występuje. Jeśli parametr powtarza się w ciągu 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 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 jako ciąg 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 metody getTimestampMillis.

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

Składnia

getTimestamp();

Powiązane uprawnienia

Brak.

getTimestampMillis

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

Składnia

getTimestampMillis();

Powiązane uprawnienia

Brak.

getType

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

Typ wejściowy Zwrócona wartość
string 'string'
number 'number'
boolean '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 any Wartość wejściowa.

Powiązane uprawnienia

Brak.

hmacSha256

Oblicza zakodowany podpis przy użyciu kodu uwierzytelniania wiadomości (HMAC) z SHA-256. Domyślna wartość to kodowanie base64url.

Aby używać tego interfejsu API, ustaw zmienną środowiskową SGTM_CREDENTIALS na serwerze na ścieżkę pliku klucza JSON zakodowanego w formacie UTF-8 o następującym 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 odwołuje się do klucza, którego należy użyć.
options object Opcjonalna konfiguracja interfejsu API. (zobacz Opcje poniżej).

Opcje

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

Powiązane uprawnienia

use_custom_private_keys

Minimalna wersja graficzna

1.0.0

isRequestMpv1

Zwraca true, jeśli żądanie przychodzące jest żądaniem Measurement Protocol w wersji 1, lub false w przeciwnym razie.

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 true, jeśli przychodzące żądanie jest żądaniem Measurement Protocol w wersji 2, lub false w przeciwnym razie.

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. Uruchom zapytanie logName =~ "stdout" w Eksploratorze logów, aby wyświetlić wpisy 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

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

Składnia

makeInteger(value);

Parametry

Parametr Typ Opis
value any type Wartość do przekonwertowania.

Powiązane uprawnienia

Brak.

makeNumber

Przekształca podaną wartość w liczbę.

Składnia

makeNumber(value);

Parametry

Parametr Typ Opis
value any type Wartość do przekonwertowania.

Powiązane uprawnienia

Brak.

makeString

Zwraca podaną wartość jako ciąg znaków.

Składnia

makeString(value);

Parametry

Parametr Typ Opis
value any type Wartość do przekonwertowania.

Powiązane uprawnienia

Brak.

makeTableMap

Konwertuje prosty obiekt tabeli z 2 kolumnami na Map. Służy do zmiany pola szablonu SIMPLE_TABLE z 2 kolumnami na format, którym łatwiej zarządzać.

Ta funkcja może na przykład przekonwertować obiekt tabeli:

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

na mapę:

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

Zwraca obiekt: dodano do niego przekonwertowane pary klucz-wartość Map lub null.

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 obiekcie Map.
valueColumnName string Nazwa kolumny, której wartości staną się wartościami w przekonwertowanym elemencie Map.

Powiązane uprawnienia

Brak.

parseUrl

Zwraca obiekt, który zawiera wszystkie części składowe danego adresu URL, podobnie jak obiekt URL.

W przypadku nieprawidłowego adresu URL 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 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

Usuwa 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 z szablonu klienta.

Składnia

returnResponse();

Przykład

Zobacz przykład runContainer.

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 zdarzenia. Więcej informacji znajdziesz w przykładzie addEventCallback.

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

Powiązane uprawnienia

run_container

sendEventToGoogleAnalytics

Wysyła do Google Analytics pojedyncze zdarzenie, korzystając z wspólnych danych zdarzenia, i zwraca obietnicę, która rozwiązuje się do obiektu z kluczem location lub odrzuca do obiektu z kluczem reason. Miejsce docelowe, czyli Google Analytics, jest określane na podstawie identyfikatora pomiaru w danych zdarzenia.

Pole location jest ustawione na nagłówek location, jeśli jest on 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 uprawnienia send_http. Uprawnienie musi być skonfigurowane tak, aby zezwalać na dostęp do co najmniej tych elementów:

  • Zezwalanie na używanie domen w Google Domains

sendHttpGet

Wysyła żądanie GET HTTP do określonego adresu URL i zwraca obietnicę, która jest rozwiązywana z wynikiem po zakończeniu żądania lub po upływie 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 błędem: {reason: 'failed'}. Jeśli opcja timeout została ustawiona i upłynął limit czasu żądania, obietnica zostanie odrzucona z powodu: {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 URL.
options object Opcjonalne opcje żądania. (zobacz Opcje poniżej).

Opcje

Opcja Typ Opis
headers string Dodatkowe nagłówki żądań.
timeout number Limit czasu (w milisekundach), po którym żądanie zostanie przerwane. Domyślna wartość to 15000.
authorization object Opcjonalny obiekt autoryzacji z wywołania getGoogleAuth do dołączania nagłówków autoryzacji podczas wysyłania żądań do googleapis.com.

Powiązane uprawnienia

send_http

sendHttpRequest

Wysyła żądanie HTTP na określony adres URL i zwraca obietnicę, która jest rozwiązywana po zakończeniu żądania lub po upływie 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 błędem: {reason: 'failed'}. Jeśli opcja timeout została ustawiona i upłynął limit czasu żądania, obietnica zostanie odrzucona z powodu: {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 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 Limit czasu (w milisekundach), po którym żądanie zostanie przerwane. Domyślna wartość to 15000.
authorization object Opcjonalny obiekt autoryzacji z wywołania getGoogleAuth do dołączania nagłówków autoryzacji podczas wysyłania żądań do 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 na potrzeby Google Analytics i w tagach internetowych Google Analytics: zdarzenie GA. Musisz skonfigurować adres URL kontenera serwera. Więcej informacji znajdziesz w instrukcjach.

Ten interfejs API zwraca false, jeśli żądanie przychodzące nie obsługuje protokołu poleceń lub jeśli odpowiedź została już opróżniona. W przeciwnym razie ten 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 string Adres URL, który zostanie 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ą, z którą został utworzony, i przypisać mu wartość wygaśnięcia, 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ć 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. Wielkość liter w nazwie nie jest rozróżniana.
value string Wartość pliku cookie.
options object Opcjonalne atrybuty plików cookie:domain, expires, fallbackDomain, httpOnly, max-age, path, secure i sameSite. (patrz Opcje poniżej).
noEncode boolean 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 zliczony według tej strategii:

    • 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 znaków daty w formacie UTC, np. „Sat, 26 Oct 1985 08:21:00 GMT”. Jeśli ustawione są obie zasady (expires i max-age), pierwszeństwo ma zasada max-age.

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

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

  • path: ścieżka, która musi istnieć 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 do serwera tylko wtedy, gdy żądanie zostanie wysłane z punktu końcowego https:.

  • sameSite: potwierdza, że plik cookie nie może być wysyłany z żądaniami współdzielenia. Musi to być 'strict', 'lax' lub 'none'.

Powiązane uprawnienia

set_cookie

setPixelResponse

Ustawia treść odpowiedzi na GIF-a 1 x 1, nagłówek Content-Type na „image/gif”, nagłówki pamięci podręcznej tak, aby klient użytkownika nie zapisywał odpowiedzi w pamięci podręcznej, a stan odpowiedzi na 200.

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

Składnia

setPixelResponse();

Powiązane uprawnienia

Wymaga uprawnienia access_response. Uprawnienie musi 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 wysłana z powrotem do klienta, musisz wywołać funkcję returnResponse.

Składnia

setResponseBody(body[, encoding]);

Parametry

Parametr Typ Opis
body string Wartość, która ma zostać 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 uprawnienia access_response. Uprawnienie musi być skonfigurowane tak, aby zezwalać na dostęp co najmniej do:

  • body

setResponseHeader

Ustawia nagłówek w odpowiedzi, która zostanie zwrócona. Jeśli nagłówek o tej nazwie (wielkość liter nie jest rozróżniana) został wcześniej ustawiony przez ten interfejs API, ostatnie wywołanie zastąpi lub wyczyści wartość ustawioną przez poprzednie wywołanie.

Pamiętaj, że aby odpowiedź została wysłana z powrotem 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 będzie zapisana małymi literami.
value string undefined Wartość nagłówka. Jeśli wartość jest pusta lub niezdefiniowana, powoduje to usunięcie nazwanego nagłówka z odpowiedzi, która zostanie zwrócona.

Powiązane uprawnienia

Wymaga uprawnienia access_response. Uprawnienie musi 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 wysłana z powrotem 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 uprawnienia access_response. Uprawnienie musi 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.

Ta sygnatura i zachowanie interfejsu API odpowiadają interfejsowi API sha256 dla kontenerów internetowych. Szablony niestandardowe w kontenerach serwera powinny jednak używać interfejsu API sha256Sync, aby kod był prostszy.

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, który ma zostać zahaszowany.
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 jest 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 zakodowanych 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, który ma zostać zahaszowany.
options object Opcjonalny obiekt opcji określający kodowanie danych wyjściowych. Jeśli obiekt jest określony, powinien zawierać klucz outputEncoding z wartością base64 lub hex.

Powiązane uprawnienia

Brak.

templateDataStorage

Zwraca obiekt z metodami dostępu do magazynu danych szablonu. Magazyn danych szablonu umożliwia udostępnianie danych między wykonaniami pojedynczego szablonu. Dane przechowywane w magazynie danych szablonu pozostają 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 magazynie danych szablonu nie gwarantuje, że każde kolejne żądanie będzie miało dostęp do danych.

„Dane” w nazwie „templateDataStorage” oznaczają, że za pomocą tego interfejsu API można przechowywać tylko zwykłe 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 ciąg znaków pod kątem wyrażenia regularnego utworzonego za pomocą interfejsu API createRegex. Zwraca wartość true, jeśli wyrażenie regularne pasuje. 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 przetestowania, zwrócone przez interfejs createRegex API.
string string Testowy ciąg znaków do przetestowania.

Powiązane uprawnienia

Brak.

toBase64

Koduje ciąg znaków jako base64 lub base64url. Domyślnie jest to 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 boolean Jeśli ma wartość true, 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 udanym wstawieniu lub odrzucana w przypadku błędu.

Po pomyślnym wstawieniu 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że się zdarzyć, że część żądania zostanie zrealizowana pomyślnie, a inne części nie. W takim przypadku obietnica zostanie odrzucona z listą błędów dla każdego wiersza z obiektem wiersza, aby ułatwić rozróżnienie, które wiersze 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 Definiuje 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 zostanie pominięty, projectId zostanie pobrany 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 w chmurze 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. (patrz Opcje poniżej).

Opcje

Parametr Typ Opis
ignoreUnknownValues boolean Jeśli jest ustawiona na true, akceptowane są wiersze zawierające wartości, które nie pasują do schematu. Wartości nieznane będą ignorowane. Domyślna wartość to false.
skipInvalidRows boolean Jeśli ustawisz wartość true, zostaną wstawione wszystkie prawidłowe wiersze żądania, nawet jeśli występują 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 jeszcze modułu BigQuery. Wdróż ponownie kontener serwera z tymi samymi ustawieniami, korzystając z naszego skryptu wdrażania. Moduł zostanie automatycznie uwzględniony po zakończeniu operacji.

Błąd inny niż błąd wstawiania zwykle ma 1 obiekt błędu z kluczem reason:

[{reason: 'invalid'}]

Błąd wstawiania może zawierać wiele obiektów błędu z tablicą errors i obiektem row. Poniżej znajdziesz przykład odpowiedzi z błędem po wstawieniu 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 tylko domyślną bazę danych.

Firestore.read

Funkcja Firestore.read odczytuje dane z dokumentu Firestore i zwraca obietnicę, która rozwiązuje się do obiektu zawierającego 2 klucze: id i data. Jeśli dokument nie istnieje, obietnica zostanie odrzucona z obiektem zawierającym klucz reason równy 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. Nieznane klucze opcji są ignorowane. (patrz Opcje poniżej).

Opcje

Parametr Typ Opis
projectId string Opcjonalnie. Identyfikator projektu Google Cloud Platform. Jeśli zostanie pominięty, projectId zostanie pobrany ze zmiennej środowiskowej GOOGLE_CLOUD_PROJECT, o ile ustawienie access_firestore zbioru uprawnień 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 w chmurze Google Cloud.
disableCache boolean Opcjonalnie. Określa, czy wyłączyć pamięć podręczną. Buforowanie jest domyślnie włączone, co oznacza, że wyniki będą przechowywane w pamięci podręcznej przez czas trwania żądania.
transaction string Opcjonalnie. Wartość pobrana z 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 do identyfikatora dodanego lub zmodyfikowanego dokumentu. Jeśli używana jest opcja transakcji, interfejs API nadal zwraca obietnicę, ale nie zawiera identyfikatora, ponieważ zapisy są grupowane.

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. (patrz Opcje poniżej).

Opcje

Parametr Typ Opis
projectId string Opcjonalnie. Identyfikator projektu Google Cloud Platform. Jeśli zostanie pominięty, projectId zostanie pobrany ze zmiennej środowiskowej GOOGLE_CLOUD_PROJECT, o ile ustawienie access_firestore zbioru uprawnień 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 w chmurze Google Cloud.
merge boolean Opcjonalnie. Jeśli ustawiono wartość true, klucze z danych wejściowych są scalane z dokumentem. W przeciwnym razie metoda zastępuje cały dokument. Domyślna wartość to false.
transaction string Opcjonalnie. Wartość pobrana z 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 danej kolekcji i zwraca obietnicę, która rozwiązuje się do tablicy dokumentów Firestore spełniających warunki zapytania. Obiekt dokumentu Firestore jest taki sam jak ten wymieniony powyżej w sekcji Firestore.read. Jeśli nie ma dokumentów spełniających warunki zapytania, zwrócona obietnica zostanie rozwiązana do pustej tablicy.

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: 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 artykule o  operatorach zapytań Firestore.
options object Opcjonalne opcje żądania. Obsługiwane opcje to: projectId, disableCache, limit i transaction. Nieznane klucze opcji są ignorowane. (patrz Opcje poniżej).

Opcje

Parametr Typ Opis
projectId string Opcjonalnie. Identyfikator projektu Google Cloud Platform. Jeśli zostanie pominięty, projectId zostanie pobrany ze zmiennej środowiskowej GOOGLE_CLOUD_PROJECT, o ile ustawienie access_firestore zbioru uprawnień 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 w chmurze Google Cloud.
disableCache boolean Opcjonalnie. Określa, czy wyłączyć pamięć podręczną. Buforowanie jest domyślnie włączone, 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. Wartość domyślna to 5.
transaction string Opcjonalnie. Wartość pobrana z 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 niepodzielny odczyt i zapis w Firestore. Jeśli wystąpi konflikt jednoczesnego zapisu lub innej 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. Jeśli transakcja się powiedzie, ten interfejs API zwraca obietnicę, która rozwiązuje się do tablicy identyfikatorów dokumentów dla każdej operacji zapisu. Jeśli transakcja się nie powiedzie, interfejs API odrzuci ją 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 postaci ciągu znaków. Identyfikator transakcji można przekazywać w wywołaniach interfejsu API odczytu/zapisu/zapytania. Ta funkcja wywołania zwrotnego musi zwracać obietnicę. Wywołanie zwrotne może zostać uruchomione maksymalnie 3 razy, zanim zakończy się niepowodzeniem.
options object Opcjonalne opcje żądania. Jedyną obsługiwaną opcją jest projectId. Nieznane klucze opcji są ignorowane. (patrz Opcje poniżej).

Opcje

Parametr Typ Opis
projectId string Opcjonalnie. Identyfikator projektu Google Cloud Platform. Jeśli zostanie pominięty, projectId zostanie pobrany ze zmiennej środowiskowej GOOGLE_CLOUD_PROJECT, o ile ustawienie access_firestore zbioru uprawnień 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 w chmurze 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ładowy błąd

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łędów 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 kod 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 nie można przeanalizować wartości (np. obiekt ma cykl), metoda zwróci 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

Te interfejsy API współpracują ze sobą, umożliwiając 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 API sendMessage (zwykle przez tag), wywołanie zwrotne zostanie uruchomione synchronicznie. Wywołanie zwrotne jest uruchamiane z 2 parametrami:

  1. messageType:string
  2. message:Object

Jeśli wywołanie zwrotne zostanie dodane w kliencie, będzie ono otrzymywać wiadomości dotyczące 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 Wywołanie zwrotne, które ma zostać uruchomione po wysłaniu wiadomości odpowiedniego typu. Jeśli wywołanie zwrotne nie jest funkcją, interfejs API nie wykona żadnej operacji.

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 uprawnienia use_message. Uprawnienie musi być skonfigurowane tak, aby zezwalać na co najmniej:

  • Typ wiadomości z Usage o wartości listen lub listen_and_send.

hasMessageListener

Zwraca wartość „true”, jeśli dla danego typu wiadomości dodano detektor wiadomości. W przeciwnym razie zwraca wartość „false” („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żna 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 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 wykona żadnej operacji.

Powiązane uprawnienia

Wymaga uprawnienia use_message. Uprawnienie musi być skonfigurowane tak, aby zezwalać na co najmniej:

  • Typ wiadomości z Usage o wartości listen_and_send lub send.

Object

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

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

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

Metoda entries() zapewnia zachowanie biblioteki standardowej Object.entries(). Zwraca tablicę par [key, value] własnych właściwości wyliczalnych danego obiektu w takiej samej kolejności jak pętla for...in.... Jeśli wartość wejściowa nie jest obiektem, zostanie przekształcona w obiekt.

Metoda freeze() zapewnia zachowanie metody Object.freeze() z biblioteki standardowej. Zablokowanego obiektu nie można już zmienić. Zablokowanie obiektu uniemożliwia dodawanie do niego nowych właściwości, usuwanie istniejących właściwości i zmienianie wartości istniejących właściwości. freeze() zwraca ten sam obiekt, który został przekazany. Argument podstawowy lub null będzie traktowany jak zamrożony obiekt i zostanie zwrócony.

Metoda delete() zapewnia działanie operatora usuwania biblioteki standardowej. Usuwa dany klucz z obiektu, chyba że obiekt jest zamrożony. Podobnie jak operator delete w bibliotece standardowej 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. We wszystkich innych przypadkach zwraca wartość false. Różni się jednak od operatora usuwania biblioteki standardowej pod tymi względami:

  • keyToDelete nie może być ciągiem znaków rozdzielonych kropkami, który określa zagnieżdżony klucz.
  • Nie można używać funkcji delete() do usuwania elementów z tablicy.
  • Nie można użyć delete() do usunięcia właściwości 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 any 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 any Obiekt, którego wartości mają zostać wyliczone. Jeśli dane wejściowe nie są obiektem, zostaną przekształcone w obiekt.

Object.entries

Parametr Typ Opis
objectInput any Obiekt, którego pary klucz-wartość mają zostać wyliczone. Jeśli dane wejściowe nie są obiektem, zostaną przekształcone w obiekt.

Object.freeze

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

Object.delete

Parametr Typ Opis
objectInput any Obiekt, którego klucz chcesz usunąć.
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.

Obiekty Promise są funkcjonalnie równoważne obiektom Promise w JavaScripcie. 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 przypadki rozwiązane, jak i odrzucone. Jako parametry przyjmuje 2 wywołania zwrotne: jedno dla przypadku powodzenia i jedno dla 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 jedno wywołanie zwrotne jako parametr, który jest wywoływany 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:

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

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. Jeśli dane wejściowe nie są tablicą, zwraca błąd.

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 JavaScriptu.

Składnia

Promise.create(resolver);

Parametry

Parametr Typ Opis
resolver function Funkcja wywoływana z 2 funkcjami – resolve i reject. Zwrócona obietnica zostanie rozwiązana lub odrzucona po wywołaniu odpowiedniego parametru. Zgłasza 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 JavaScriptu w piaskownicy, aby tworzyć testy szablonów niestandardowych w Menedżerze tagów Google. Te testowe interfejsy API nie wymagają instrukcji require(). [Więcej informacji o testach szablonów niestandardowych].

assertApi

Zwraca obiekt dopasowujący, którego można używać 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 require().

Dopasowania

  • 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] Google. Zwraca obiekt, którego można użyć do płynnego tworzenia asercji dotyczących wartości podmiotu. Niepowodzenie asercji spowoduje natychmiastowe zatrzymanie testu i oznaczenie go jako nieudanego. Niepowodzenie jednego testu nie wpłynie jednak na inne elementy testowania.

Składnia

assertThat(actual, opt_message)

Parametry

Parametr Typ Opis
actual any Wartość, która ma być używana w testach płynności.
opt_message string Opcjonalny komunikat do wyświetlenia, jeśli asercja się nie powiedzie.

Dopasowania

Matcher Opis
isUndefined() Potwierdza, że podmiot to undefined.
isDefined() Potwierdza, że podmiot nie jest undefined.
isNull() Potwierdza, że podmiot to null.
isNotNull() Potwierdza, że podmiot nie jest null.
isFalse() Potwierdza, że podmiot to false.
isTrue() Potwierdza, że podmiot to true.
isFalsy() Potwierdza, że podmiot jest fałszywy. Wartości fałszu to undefined, null, false, NaN, 0 i '' (pusty ciąg znaków).
isTruthy() Potwierdza, że podmiot jest prawdziwy. Wartości fałszu to undefined, null, false, NaN, 0 i '' (pusty ciąg znaków).
isNaN() Potwierdza, że podmiot jest wartością NaN.
isNotNaN() Potwierdza, że podmiot jest dowolną wartością inną niż NaN.
isInfinity() Potwierdza, że podmiot jest dodatnią lub ujemną nieskończonością.
isNotInfinity() Potwierdza, że podmiot jest dowolną wartością inną niż dodatnia lub ujemna nieskończoność.
isEqualTo(expected) Potwierdza, że podmiot jest równy podanej wartości. Jest to porównanie wartości, a nie odniesień. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
isNotEqualTo(expected) Potwierdza, że podmiot nie jest równy podanej wartości. Jest to porównanie wartości, a nie odniesień. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
isAnyOf(...expected) Potwierdza, że podmiot jest równy jednej z podanych wartości. Jest to porównanie wartości, a nie odniesień. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
isNoneOf(...expected) Potwierdza, że podmiot nie jest równy żadnej z podanych wartości. Jest to porównanie wartości, a nie odniesień. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
isStrictlyEqualTo(expected) Potwierdza, że podmiot jest ściśle równy (===) podanej wartości.
isNotStrictlyEqualTo(expected) Potwierdza, że podmiot nie jest ściśle równy (!==) podanej wartości.
isGreaterThan(expected) Potwierdza, że podmiot jest większy niż (>) podana wartość w porównaniu uporządkowanym.
isGreaterThanOrEqualTo(expected) Potwierdza, że podmiot jest większy lub równy (>=) podanej wartości w porównaniu uporządkowanym.
isLessThan(expected) Potwierdza, że podmiot jest mniejszy niż (<) podana wartość w uporządkowanym porównaniu.
isLessThanOrEqualTo(expected) Potwierdza, że podmiot jest mniejszy lub równy (<=) podanej wartości w porównaniu uporządkowanym.
contains(...expected) Potwierdza, że podmiot 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 odniesienia. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
doesNotContain(...expected) Potwierdza, że podmiot jest tablicą lub ciągiem znaków, który nie zawiera żadnej z podanych wartości. Jest to porównanie wartości, a nie odniesień. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
containsExactly(...expected) Potwierdza, że podmiot jest tablicą zawierającą wszystkie podane wartości w dowolnej kolejności i nie zawiera żadnych innych wartości. Jest to porównanie wartości, a nie odniesień. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
doesNotContainExactly(...expected) Potwierdza, że podmiot jest tablicą zawierającą inny zestaw wartości niż podane wartości w dowolnej kolejności. Jest to porównanie wartości, a nie odniesienia. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
hasLength(expected) Potwierdza, że podmiot 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() Potwierdza, że podmiot jest tablicą lub ciągiem znaków, który jest pusty (długość = 0). Asercja zawsze kończy się niepowodzeniem, jeśli wartość nie jest tablicą ani ciągiem znaków.
isNotEmpty() Potwierdza, że podmiot 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() Potwierdza, że typem podmiotu jest tablica.
isBoolean() Potwierdza, że typem podmiotu jest wartość logiczna.
isFunction() Potwierdza, że typ podmiotu jest funkcją.
isNumber() Potwierdza, że typem podmiotu jest liczba.
isObject() Potwierdza, że typem podmiotu jest obiekt.
isString() Potwierdza, że typem podmiotu jest ciąg 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 niepowodzeniem 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 API mock umożliwia zastąpienie działania interfejsów API w piaskownicy. Można bezpiecznie używać makiety interfejsu API w kodzie szablonu, ale działa ona tylko w trybie testowym. Przed każdym testem makiety są resetowane.

Składnia

mock(apiName, returnValue);

Parametry

Parametr Typ Opis
apiName string Nazwa interfejsu API, który ma zostać zasymulowany; ten sam ciąg znaków, który został przekazany do require()
returnValue any Wartość, która ma zostać zwrócona dla interfejsu API, lub funkcja wywoływana zamiast interfejsu API. Jeśli returnValue jest funkcją, jest ona wywoływana zamiast interfejsu Sandboxed API. Jeśli returnValue jest czymś innym niż funkcja, ta wartość jest zwracana zamiast interfejsu Sandboxed API.

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. Interfejsu API można bezpiecznie używać w kodzie szablonu, ale działa on tylko w trybie testowym. Przed każdym testem makiety są resetowane.

Składnia

mockObject(apiName, objectMock);

Parametry

Parametr Typ Opis
apiName string Nazwa interfejsu API, który ma zostać zasymulowany; ten sam ciąg znaków, który został przekazany do require()
objectMock object Wartość, która ma zostać zwrócona dla interfejsu API, lub funkcja wywoływana zamiast interfejsu API. Musi być obiektem.

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; w przypadku wszystkich innych typów szablonów zwraca undefined.

Przykład

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