Interfejsy API firm zewnętrznych

Zaawansowaną funkcją skryptów Google Ads jest możliwość integracji z danymi i usługami z interfejsów API innych firm.

W tym przewodniku znajdziesz omówienie następujących zagadnień, które pomogą Ci tworzyć skrypty łączące się z innymi usługami:

  • Tworzenie żądań HTTP: jak używać UrlFetchApp do uzyskiwania dostępu do zewnętrznych interfejsów API.
  • Uwierzytelnianie: uwzględniamy kilka typowych scenariuszy uwierzytelniania.
  • Odpowiedzi analizy składni: jak przetwarzać zwrócone dane JSON i XML.

Pobierz dane za pomocą UrlFetchApp

UrlFetchApp zapewnia podstawowe funkcje wymagane do interakcji z interfejsami API innych firm.

Ten przykład przedstawia pobieranie danych o pogodzie z OpenWeatherMap. Wybraliśmy OpenWeatherMap ze względu na stosunkowo prosty schemat autoryzacji i interfejs API.

Poproś

Dokumentacja OpenWeatherMap określa format żądania aktualnej pogody w ten sposób:

http://api.openweathermap.org/data/2.5/weather?q=[location]&apikey=[apikey]

Adres URL stanowi pierwszy przykład autoryzacji: parametr apikey jest wymagany, a jego wartość jest unikalna dla każdego użytkownika. Ten klucz uzyskuje się podczas rejestracji.

Po rejestracji żądanie użycia klucza może zostać wysłane w następujący sposób:

const location = 'London,uk';
const apikey = 'da.......................81'; // Replace with your API key
const currentWeatherUrl = `http://api.openweathermap.org/data/2.5/weather?q=${location}&apiKey=${apiKey}`;
const response = UrlFetchApp.fetch(currentWeatherUrl);
console.log(response.getContentText());

Wykonanie tego kodu powoduje wygenerowanie długiego ciągu tekstowego JSON zapisanego w oknie logowania w skryptach Google Ads.

Następnym krokiem jest przekonwertowanie go na format, którego można używać w skrypcie.

Dane JSON

Wiele interfejsów API udostępnia odpowiedzi w formacie JSON. Reprezentuje to prostąserializację obiektów JavaScript, takie jak obiekty, tablice i podstawowe typy mogą być reprezentowane i przenoszone jako ciągi znaków.

Aby przekonwertować ciąg znaków JSON – taki jak ten zwrócony przez OpenWeatherMap – z powrotem na obiekt JavaScript, użyj wbudowanej metody JSON.parse. Nawiązując do powyższego przykładu:

const json = response.getContentText();
const weatherData = JSON.parse(json);
console.log(weatherData.name);
//  "London"

Metoda JSON.parse konwertuje ciąg znaków na obiekt, który ma właściwość name.

Więcej informacji o pracy z odpowiedziami interfejsu API w różnych formatach znajdziesz w sekcji Analizuj odpowiedzi.

Obsługa błędów

Obsługiwanie błędów jest istotnym elementem podczas pracy z interfejsami API innych firm w skryptach, ponieważ te interfejsy często często się zmieniają i generują nieoczekiwane wartości odpowiedzi, np.:

  • Adres URL lub parametry interfejsu API mogą ulec zmianie bez Twojej wiedzy.
  • Twój klucz interfejsu API (lub inne dane logowania użytkownika) może wygasnąć.
  • Format odpowiedzi może ulec zmianie bez powiadomienia.

Kody stanów HTTP

Ze względu na ryzyko niespodziewanych odpowiedzi sprawdź kod stanu HTTP. Domyślnie UrlFetchApp zgłasza wyjątek w przypadku wystąpienia kodu błędu HTTP. Aby zmienić to działanie, musisz przekazać opcjonalny parametr, jak w tym przykładzie:

const options = {
  muteHttpExceptions: true
}
const response = UrlFetchApp.fetch(url, options);
// Any status code greater or equal to 400 is either a client or server error.
if (response.getResponseCode() >= 400) {
  // Error encountered, send an email alert to the developer
  sendFailureEmail();
}

Struktura odpowiedzi

Gdy interfejsy API innych firm się zmieniają, deweloperzy często nie zdają sobie sprawy ze zmian, które mogą wpłynąć na ich skrypty. Jeśli np. właściwość name zwrócona w przykładzie OpenWeatherMap zostanie zmieniona na locationName, skrypty korzystające z tej właściwości przestaną działać.

Z tego powodu warto sprawdzić, czy zwrócona struktura jest zgodna z oczekiwaniami, na przykład:

const weatherData = JSON.parse(json);
if (weatherData && weatherData.name) {
  console.log('Location is : ' + name);
} else {
  console.log('Data not in expected format');
}

Dane POST z UrlFetchApp

Wstępny przykład wykorzystujący tylko dane pobrane z OpenWeatherMap. Zwykle wywołania interfejsu API, które nie zmieniają stanu na serwerze zdalnym, korzystają z metody HTTP GET.

Metoda GET jest domyślną metodą UrlFetchApp. Niektóre wywołania interfejsu API, na przykład wywołania usługi, która wysyła SMS-y, wymagają jednak innych metod, takich jak POST lub PUT.

Aby zilustrować przykład użycia wywołań POST w UrlFetchApp, w tym przykładzie pokazano integrację ze Slackem, aplikacją do współpracy przeznaczoną do współpracy, w celu wysyłania wiadomości Slacka do użytkowników i grup Slacka.

Konfigurowanie Slacka

W tym przewodniku zakładamy, że masz już zarejestrowane konto Slack.

Tak jak w przypadku OpenWeatherMap w poprzednim przykładzie, do wysyłania wiadomości należy uzyskać token. Slack udostępnia unikalny adres URL, który umożliwia wysyłanie wiadomości do zespołu nazywany przychodzącym webhookiem.

Skonfiguruj przychodzącego webhooka, klikając Add Incoming WebHooks Integration (Dodaj integrację webhooka przychodzącego) i postępując zgodnie z instrukcjami. Proces powinien wygenerować adres URL używany do przesyłania wiadomości.

Wyślij żądanie POST

Po skonfigurowaniu webhooka przychodzącego wysłanie żądania POST wymaga użycia dodatkowych właściwości w parametrze options przekazywanym do UrlFetchApp.fetch:

  • method: jak już wspomnieliśmy, domyślna wartość to GET, ale tutaj zastępujemy ją i ustawiamy na POST.

  • payload: to dane, które zostaną wysłane do serwera w ramach żądania POST. W tym przykładzie Slack wymaga obiektu zserializowanego do formatu JSON, zgodnie z opisem w dokumentacji Slacka. W tym celu używana jest metoda JSON.stringify, a pole Content-Type jest ustawione na application/json.

      // Change the URL for the one issued to you from 'Setting up Slack'.
  const SLACK_URL = 'https://hooks.slack.com/services/AAAA/BBBB/CCCCCCCCCC';
  const slackMessage = {
    text: 'Hello, slack!'
  };

  const options = {
    method: 'POST',
    contentType: 'application/json',
    payload: JSON.stringify(slackMessage)
  };
  UrlFetchApp.fetch(SLACK_URL, options);

Przykład rozszerzonego Slacka

Powyższy przykład pokazuje minimalną liczbę dozwolonych wiadomości przychodzących do Slacka. Rozszerzony przykład pokazuje tworzenie i wysyłanie raportu skuteczności kampanii do grupy, a także niektóre opcje formatowania i wyświetlania.

Wiadomość przychodząca

Więcej informacji o wiadomościach Slacka znajdziesz w sekcji o formatowaniu wiadomości w dokumentacji Slacka.

Dane formularzy

W przykładzie powyżej dla żądania POST użyto ciągu JSON jako właściwości payload.

W zależności od formatu żądania payload UrlFetchApp tworzy żądanie POST na różne sposoby:

  • Gdy payload jest ciągiem znaków, argument ciągu jest wysyłany jako treść żądania.

  • Gdy payload jest obiektem, na przykład mapą wartości:

    {to: 'mail@example.com', subject:'Test', body:'Hello, World!'}

    Pary klucz-wartość są konwertowane na dane formularza:

    subject=Test&to=mail@example.com&body=Hello,+World!

    Poza tym nagłówek Content-Type żądania jest ustawiony na application/x-www-form-urlencoded.

Niektóre interfejsy API wymagają użycia danych formularzy podczas przesyłania żądań POST, warto więc pamiętać o automatycznej konwersji z obiektów JavaScript na dane formularzy.

Podstawowe uwierzytelnianie HTTP

Podstawowe uwierzytelnianie HTTP to jedna z najprostszych form uwierzytelniania, z której korzysta wiele interfejsów API.

Uwierzytelnianie polega na dołączeniu do każdego żądania zakodowanej nazwy użytkownika i hasła do nagłówków HTTP.

Podstawowe uwierzytelnianie HTTP

Tworzenie żądania

Aby wygenerować uwierzytelnione żądanie, musisz wykonać te czynności:

  1. Utwórz hasło, łącząc nazwę użytkownika i hasło z dwukropkiem, np. username:password.
  2. Koduj hasło w standardzie Base64, na przykład username:password zmienia się w dXNlcm5hbWU6cGFzc3dvcmQ=.
  3. Załącz do żądania nagłówek Authorization w formacie Authorization: Basic <encoded passphrase>

Poniższy fragment pokazuje, jak to zrobić za pomocą skryptów Google Ads:

const USERNAME = 'your_username';
const PASSWORD = 'your_password';
const API_URL = 'http://<place_api_url_here>';

const authHeader = 'Basic ' + Utilities.base64Encode(USERNAME + ':' + PASSWORD);
const options = {
  headers: {Authorization: authHeader}
}
// Include 'options' object in every request
const response = UrlFetchApp.fetch(API_URL, options);

Plivo

Plivo to usługa, która ułatwia wysyłanie i odbieranie SMS-ów przez interfejs API. Ten przykład pokazuje, jak wysyłać wiadomości.

  1. Zarejestruj się w Plivo.
  2. Wklej przykładowy skrypt do nowego skryptu w Google Ads.
  3. Zastąp wartości PLIVO_ACCOUNT_AUTHID i PLIVO_ACCOUNT_AUTHTOKEN wartościami z panelu zarządzania.
  4. Wstaw adres e-mail podany w skrypcie służącym do powiadamiania o błędach.
  5. Aby korzystać z Plivo, musisz kupić numery lub dodać numery do konta próbnego. Dodaj numery piaskownicy, których można używać na koncie próbnym.
  6. Dodaj zarówno numer, który będzie wyświetlany jako nadawca, jak i numer odbiorcy.
  7. Zaktualizuj PLIVO_SRC_PHONE_NUMBER w skrypcie, podając jeden z już zarejestrowanych numerów piaskownicy. Powinien to być międzynarodowy kod kraju, np. 447777123456 w przypadku numeru w Wielkiej Brytanii.

Twilio

Twilio to kolejna usługa, która ułatwia wysyłanie i odbieranie SMS-ów przez interfejs API. Ten przykład pokazuje, jak wysyłać wiadomości.

  1. Zarejestruj się w Twillio.
  2. Wklej przykładowy skrypt do nowego skryptu w Google Ads.
  3. Zastąp wartości TWILIO_ACCOUNT_SID i TWILIO_ACCOUNT_AUTHTOKEN wartościami widocznymi na stronie konsoli konta.
  4. Zastąp TWILIO_SRC_PHONE_NUMBER numerem z panelu – jest to numer upoważniony przez Twilio do wysyłania wiadomości.

OAuth 1.0

Wiele popularnych usług wykorzystuje protokół OAuth do uwierzytelniania. OAuth jest dostępny na różne sposoby.

Podczas gdy w przypadku podstawowego uwierzytelniania HTTP użytkownik ma tylko jedną nazwę użytkownika i hasło, protokół OAuth umożliwia aplikacjom innych firm dostęp do konta i danych użytkownika za pomocą danych logowania specyficznych dla tej aplikacji. Zakres dostępu będzie też zależeć od konkretnej aplikacji.

Informacje na temat protokołu OAuth 1.0 znajdziesz w przewodniku po podstawowym przewodniku OAuth. Przede wszystkim zob. 6. Uwierzytelnianie przy użyciu OAuth. W pełnym trzyetapowym protokole OAuth 1.0 proces przebiega tak:

  1. Aplikacja („Konsument”) otrzymuje token żądania.
  2. Użytkownik autoryzuje token żądania.
  3. Aplikacja wymienia token żądania na token dostępu.
  4. W przypadku wszystkich kolejnych żądań zasobów token dostępu jest używany w podpisanym żądaniu.

Jeśli usługi innych firm korzystają z protokołu OAuth 1.0 bez interakcji z użytkownikiem (np. jak wymagają tego skrypty Google Ads), kroki 1, 2 i 3 nie są możliwe. Dlatego niektóre usługi generują token dostępu ze swojej konsoli konfiguracji, co pozwala aplikacji przejść bezpośrednio do kroku 4. Jest to tzw. jednoetapowa autoryzacja OAuth 1.0.

OAuth1

OAuth 1.0 w skryptach Google Ads

W przypadku skryptów Google Ads każdy skrypt jest zwykle interpretowany jako aplikacja. Na stronie ustawień konsoli/administracyjnych danej usługi zwykle konieczne jest:

  • Ustaw konfigurację aplikacji na potrzeby reprezentowania skryptu.
  • Określ, które uprawnienia są rozszerzane do skryptu.
  • Uzyskaj klucz klienta, tajny klucz klienta, token dostępu i tajny dostęp do użycia z jednoetapową autoryzacją OAuth.

OAuth 2.0

W popularnych interfejsach API do zapewniania dostępu do danych użytkowników stosuje się protokół OAuth 2.0. Właściciel konta w danej usłudze zewnętrznej przyznaje określonym aplikacjom uprawnienia dostępu do danych użytkownika. Zaletą jest to, że właściciel:

  • Nie musi udostępniać aplikacji danych logowania do konta.
  • Mogą kontrolować, które aplikacje mają dostęp do poszczególnych danych i w jakim stopniu. Na przykład przyznany dostęp może być dostępny tylko do odczytu lub tylko do określonego podzbioru danych.

Aby korzystać w skryptach Google Ads z usług z włączoną obsługą OAuth 2.0, musisz wykonać kilka czynności:

Poza skryptem

Przyznaj skryptom Google Ads dostęp do danych użytkownika przez interfejs API innej firmy. W większości przypadków będzie to wymagać skonfigurowania aplikacji w konsoli usługi innej firmy. Ta aplikacja reprezentuje Twój skrypt Google Ads.

Określasz uprawnienia dostępu, które należy przyznać aplikacji Skrypt Google Ads. Zwykle zostaje ona przypisana do identyfikatora klienta. Dzięki temu możesz za pomocą protokołu OAuth 2 kontrolować, które aplikacje mają dostęp do Twoich danych w usłudze innej firmy i które aspekty tych danych mogą je widzieć lub modyfikować.

W skrypcie

Autoryzuj na serwerze zdalnym. W zależności od typu uwierzytelnienia, na który zezwala serwer, konieczne będzie wykonanie innego zestawu kroków, zwanego przepływem. Spowoduje to jednak wystawienie tokena dostępu, który będzie używany dla tej sesji dla wszystkich kolejnych żądań.

wysyłać żądania do interfejsu API, Przekaż token dostępu z każdym żądaniem.

Przepływy autoryzacji

Każdy typ uwierzytelnienia i odpowiadający mu przepływ są dostosowane do różnych scenariuszy użycia. Na przykład, gdy użytkownik bierze udział w sesji interaktywnej, stosuje się inny przepływ pracy, natomiast w sytuacji, gdy aplikacja musi działać w tle bez obecności użytkownika.

Dostawcy interfejsów API decydują o tym, jakie typy uwierzytelnienia będą akceptować, dzięki czemu użytkownik będzie mógł decydować o dalszej integracji swojego interfejsu API.

Implementacja

W przypadku wszystkich przepływów OAuth celem jest uzyskanie tokena dostępu, który można następnie wykorzystać do uwierzytelniania żądań przez resztę sesji.

W przykładowej bibliotece dowiesz się, jak uwierzytelniać się w przypadku poszczególnych typów przepływu. Każda z tych metod zwraca obiekt, który uzyskuje i przechowuje token dostępu oraz ułatwia uwierzytelnienie żądań.

Ogólny wzorzec użytkowania to:

// Authenticate using chosen flow type
const urlFetchObj = OAuth2.<flow method>(args);
// Make request(s) using obtained object.
const response1 = urlFetchObj.fetch(url1);
const response2 = urlFetchObj.fetch(url2, options);

Przyznanie danych logowania klienta

Przyznanie danych logowania klienta to jedna z prostszych form procesu OAuth2, w których aplikacja wymienia identyfikator i obiekt tajny, unikalny dla niej, w zamian za wystawienie tokena dostępu ograniczonego czasowo.

Dane logowania klienta

// Access token is obtained and cached.
const authUrlFetch = OAuth2.withClientCredentials(
    tokenUrl, clientId, clientSecret, optionalScope));
// Use access token in each request
const response = authUrlFetch.fetch(url);
// ... use response

Przyznanie tokena odświeżania

Przyznanie tokena odświeżania jest podobne do przyznawania danych logowania klienta, ponieważ proste żądanie wysłane do serwera zwróci token dostępu, którego można użyć w sesji.

Token odświeżania

Uzyskaj token odświeżania

Różnica w przypadku przyznania tokena odświeżania polega na tym, że szczegóły wymagane do przyznania danych logowania klienta pochodzą z konfiguracji aplikacji (na przykład w panelu sterowania usługi), ale token odświeżania jest przyznawany w ramach bardziej złożonego procesu, takiego jak przyznanie kodu autoryzacji, który wymaga interakcji z użytkownikiem:

Kod autoryzacji

Korzystanie z OAuth Playground do uzyskania tokena odświeżania

Środowisko testowe OAuth2 udostępnia interfejs użytkownika, który pozwala użytkownikowi przejść przez proces uwierzytelniania w celu uzyskania tokena odświeżania.

Za pomocą przycisku ustawień w prawym górnym rogu możesz zdefiniować wszystkie parametry przepływu OAuth, w tym:

  • Punkt końcowy autoryzacji: służy jako początek procesu autoryzacji.
  • Punkt końcowy tokena: używany z tokenem odświeżania w celu uzyskania tokena dostępu.
  • client ID and secret (Identyfikator klienta i tajny klucz): dane uwierzytelniające aplikacji.

OAuth Playground

Używanie skryptu do uzyskania tokena odświeżania

Oparta na skrypcie alternatywa do zakończenia procesu jest dostępna w przykładzie generowania tokena odświeżania.

Odśwież użycie tokena

Po przeprowadzeniu wstępnej autoryzacji usługi mogą wygenerować token odświeżania, którego można później używać w sposób podobny do procesu logowania danych klienta. Poniżej przedstawiamy 2 przykłady:

const authUrlFetch = OAuth2.withRefreshToken(tokenUrl, clientId, clientSecret,
    refreshToken, optionalScope);
const response = authUrlFetch.fetch(url);
// ... use response

Przykład Search Ads 360

Przykładem interfejsu API, którego można używać z tokenem odświeżania, jest Search Ads 360. W tym przykładzie skrypt generuje i zwraca raport. Szczegółowe informacje o innych działaniach, które można wykonać, znajdziesz w dokumentacji interfejsu Search Ads 360 API.

Tworzenie skryptu
  1. Utwórz nowy projekt w Konsoli interfejsów API i uzyskaj identyfikator klienta, tajny klucz klienta i token odświeżania, wykonując procedurę podaną w przewodniku po DoubleClick, i upewniając się, że włączysz interfejs DoubleClick Search API.
  2. Wklej przykładowy skrypt do nowego skryptu w Google Ads.
  3. Wklej przykładową bibliotekę OAuth2 pod listą kodu.
  4. Zmień skrypt tak, aby zawierał prawidłowe wartości identyfikatora klienta, tajnego klucza klienta i tokena odświeżania.

Przykład interfejsu Apps Script Execution API

Ten przykład pokazuje wykonanie funkcji w Apps Script przy użyciu interfejsu Apps Script Execution API. Dzięki temu skrypt Google Ads może być wywoływany przez skrypty Google Ads.

Tworzenie skryptu Apps Script

Utwórz nowy skrypt. Ten przykład zawiera listę 10 plików z Dysku:

function listFiles() {
  const limit = 10;
  const files = [];
  const fileIterator = DriveApp.getFiles();
  while (fileIterator.hasNext() && limit) {
    files.push(fileIterator.next().getName());
    limit--;
  }
  return files;
}
Konfigurowanie skryptu Apps Script do wykonywania
  1. Zapisz skrypt.
  2. Kliknij Zasoby > Projekt Cloud Platform.
  3. Kliknij nazwę projektu, aby otworzyć Konsolę interfejsów API.
  4. Otwórz Interfejsy API i usługi.
  5. Włącz odpowiednie interfejsy API, w tym przypadku Drive API i Apps Script Execution API.
  6. Utwórz dane logowania OAuth, wybierając opcję Dane logowania w menu.
  7. Wróć do skryptu, aby opublikować skrypt do wykonania, wybierając Publikowanie > Wdróż jako wykonywalny interfejs API.
Tworzenie skryptu Google Ads
  1. Wklej przykładowy skrypt do nowego skryptu w Google Ads.
  2. Dodatkowo wklej przykładową bibliotekę OAuth2 pod listą kodu.
  3. Zmień skrypt tak, aby zawierał prawidłowe wartości identyfikatora klienta, tajnego klucza klienta i tokena odświeżania.

Konta usługi

Alternatywnym rozwiązaniem dla powyższych typów uwierzytelniania jest koncepcja kont usług.

Konta usługi różnią się od tych powyżej tym, że nie są używane do uzyskiwania dostępu do danych użytkownika: po uwierzytelnieniu żądania są wysyłane przez konto usługi w imieniu aplikacji, a nie jako użytkownik, który może być właścicielem projektu. Jeśli na przykład konto usługi miałoby użyć interfejsu Drive API do utworzenia pliku, ten plik należałby do konta usługi i domyślnie nie byłby dostępny dla właściciela projektu.

Przykład interfejsu API Google Natural Language

Interfejs natural Language API umożliwia analizę nastawienia i analizę encji w przypadku tekstu.

Ten przykład pokazuje, jak obliczyć nastawienie dla tekstu reklamy – w tym nagłówka i tekstu reklamy. Dzięki niemu można określić, jak pozytywny jest przekaz reklamowy i jaka jest waga komunikatu: Sprzedajemy ciasta albo Sprzedajemy najlepsze torty w Warszawie. Kupić dzisiaj?

Konfigurowanie skryptu
  1. Utwórz nowy projekt w Konsoli interfejsów API.
  2. Włącz Natural Language API.
  3. Włącz płatności w projekcie.
  4. Utwórz konto usługi. Pobierz plik JSON z danymi logowania.
  5. Wklej przykładowy skrypt w nowym skrypcie w Google Ads.
  6. Dodatkowo wklej przykładową bibliotekę OAuth2 pod listą kodu.
  7. Zastąp niezbędne wartości:
    • serviceAccount: adres e-mail konta usługi, na przykład xxxxx@yyyy.iam.gserviceaccount.com.
    • key: klucz z pliku JSON pobrany podczas tworzenia konta usługi. Zaczyna się -----BEGIN PRIVATE KEY..., a kończy ...END PRIVATE KEY-----\n.

Odpowiedzi interfejsu API

Interfejsy API mogą zwracać dane w różnych formatach. Najważniejsze z nich to XML i JSON.

JSON

Format JSON jest zwykle prostszy od XML, aby można go było użyć jako formatu odpowiedzi. Nadal jednak mogą wystąpić pewne problemy.

Weryfikacja odpowiedzi

Po uzyskaniu odpowiedzi z wywołania interfejsu API typowym następnym krokiem jest użycie JSON.parse do przekonwertowania ciągu znaków JSON na obiekt JavaScript. W tym momencie można przystąpić do przetwarzania w przypadku błędów analizy:

const json = response.getContentText();
try {
  const data = JSON.parse(json);
  return data;
} catch(e) {
  // Parsing of JSON failed - handle error.
}

Jeśli nie masz kontroli nad interfejsem API, weź pod uwagę, że struktura odpowiedzi może się zmienić, a właściwości mogą już nie istnieć:

// Less good approach
// Assumes JSON was in form {"queryResponse": ...} when parsed.
const answer = data.queryResponse;

// Better approach
if (data && data.queryResponse) {
  const answer = data.queryResponse;
} else {
  // Format of API response has changed - alert developer or handle accordingly
}

XML

Weryfikacja

Format XML jest nadal popularnym formatem służącym do tworzenia interfejsów API. Odpowiedź z wywołania interfejsu API można przeanalizować za pomocą metody XmlService parse:

const responseText = response.getContentText();
try {
  const document = XmlService.parse(responseText);
} catch(e) {
  // Error in XML representation - handle accordingly.
}

Chociaż funkcja XmlService.parse wykrywa błędy w pliku XML i zgłasza wyjątki, nie daje możliwości sprawdzenia kodu XML w odniesieniu do schematu.

Element główny

Po prawidłowej analizie dokumentu XML element główny uzyskuje się za pomocą metody getRootElement():

const document = XmlService.parse(responseText);
const rootElement = document.getRootElement();

Przestrzenie nazw

W poniższym przykładzie Sportradar API służy do uzyskiwania wyników piłki nożnej dla wybranych meczów. Odpowiedź XML ma taki format:

<schedule xmlns="http://feed.elasticstats.com/schema/soccer/sr/v2/matches-schedule.xsd">
  <matches>
     ...
  </matches>
</schedule>

Zwróć uwagę na sposób określania przestrzeni nazw w elemencie głównym. Z tego powodu należy:

  • Wyodrębnij atrybut przestrzeni nazw z dokumentu.
  • Używaj tej przestrzeni nazw podczas przemierzania i uzyskiwania dostępu do elementów podrzędnych.

Z przykładu poniżej dowiesz się, jak uzyskać dostęp do elementu <matches> w powyższym fragmencie dokumentu:

const document = XmlService.parse(xmlText);
const scheduleElement = document.getRootElement();
// The namespace is required for accessing child elements in the schema.
const namespace = scheduleElement.getNamespace();
const matchesElement = scheduleElement.getChild('matches', namespace);

Uzyskiwanie wartości

Biorąc pod uwagę próbkę z harmonogramu meczów futbolowych:

<match status="..." category="..." ... >
  ...
</match>

Można pobierać atrybuty, na przykład:

const status = matchElement.getAttribute('status').getValue();

Tekst zawarty w elemencie można odczytać za pomocą metody getText(), ale zostaną one połączone w przypadku wielu tekstowych elementów podrzędnych tego elementu. W sytuacjach, gdy istnieje duże prawdopodobieństwo, że w przypadku dzieci z dużym prawdopodobieństwem może być wiele tekstu, rozważ użycie parametru getChildren() i przeprowadź iterację na każdym koncie podrzędnym.

Przykład Sportradar

Ten pełny przykład Sportradar pokazuje szczegółowe informacje o meczach piłki nożnej, a w szczególności angielskiej Premier League. Soccer API to jedna z wielu różnych kanałów sportowych oferowanych przez Sportradar.

Skonfiguruj konto Sportradar
  1. Otwórz stronę dla deweloperów Sportradar.
  2. Zarejestruj konto próbne.
  3. Po zarejestrowaniu się zaloguj się na swoje konto.
  4. Po zalogowaniu się otwórz stronę MyAccount (Moje konto).

Sportradar rozdziela poszczególne dyscypliny sportowe na różne interfejsy API. Możesz na przykład kupić dostęp do interfejsu Soccer API, ale nie Tennis API. Z każdą utworzoną aplikacją mogą być powiązane różne dyscypliny sportowe i różne klucze.

  1. W sekcji Aplikacje kliknij Utwórz nową aplikację. Nadaj aplikacji nazwę i opis. Zignoruj pole witryny.
  2. Wybierz tylko opcję Issue a new key for Soccertrial Europe v2 (Wystaw nowy klucz).
  3. Kliknij Zarejestruj aplikację.

Gdy operacja się powiedzie, powinna zostać utworzona strona z nowym kluczem interfejsu API.

  1. Wklej przykładowy skrypt do nowego skryptu w Google Ads.
  2. Zastąp w informacjach klucz interfejsu API kluczem uzyskanym powyżej i zmień pole adresu e-mail.

Rozwiązywanie problemów

Podczas korzystania z interfejsów API innych firm błędy mogą wystąpić z różnych powodów. Oto niektóre z nich:

  • Klienci wysyłający żądania do serwera w formacie nieoczekiwanym przez interfejs API.
  • Klienci oczekują innego formatu odpowiedzi niż ten, który wystąpił.
  • Klienci używający nieprawidłowych tokenów lub kluczy bądź wartości pozostawionych jako symbole zastępcze.
  • Klienty osiągające limity wykorzystania.
  • Klienci dostarczający nieprawidłowe parametry.

We wszystkich tych i innych przypadkach warto zacząć od sprawdzenia szczegółów odpowiedzi, która doprowadziła do błędu.

Analizuj odpowiedzi

Mechanizm skryptów Google Ads domyślnie zgłasza każdą odpowiedź, która zwraca błąd (kod stanu 400 lub wyższy).

Aby temu zapobiec oraz umożliwić sprawdzenie błędu i komunikatu o błędzie, ustaw właściwość muteHttpExceptions opcjonalnych parametrów na UrlFetchApp.fetch. Na przykład:

const params = {
  muteHttpExceptions: true
};
const response = UrlFetchApp.fetch(url, params);
if (response.getResponseCode() >= 400) {
  // ... inspect error details...
}

Typowe kody stanu

  • 200 OK oznacza powodzenie. Jeśli odpowiedź nie zawiera oczekiwanych danych, weź pod uwagę te kwestie:

    • Niektóre interfejsy API umożliwiają definiowanie pól lub formatu odpowiedzi, których należy używać. Więcej informacji na ten temat znajdziesz w dokumentacji interfejsu API.
    • Interfejs API może mieć wiele zasobów, które można wywołać. Zapoznaj się z dokumentacją, aby określić, czy inny zasób może być bardziej odpowiedni do użycia. Zwróci on potrzebne dane.
    • Interfejs API mógł się zmienić od czasu napisania kodu. Więcej informacji znajdziesz w dokumentacji lub od dewelopera.

  • 400 Bad Request zwykle oznacza, że coś jest nie tak w formatowaniu lub strukturze żądania wysyłanego do serwera. Sprawdź żądanie i porównaj je ze specyfikacją interfejsu API, aby upewnić się, że jest zgodne z oczekiwaniami. Szczegółowe informacje o sposobie badania żądań znajdziesz w sekcji Sprawdzanie żądań.

  • 401 Unauthorized zwykle oznacza, że interfejs API jest wywoływany bez przeprowadzenia autoryzacji.

    • Jeśli interfejs API używa podstawowej autoryzacji, upewnij się, że nagłówek Authorization jest tworzony i dostarczany w żądaniu.
    • Jeśli interfejs API korzysta z protokołu OAuth 2.0, sprawdź, czy token dostępu został uzyskany i jest podany jako token okaziciela.
    • W przypadku innych wariantów autoryzacji podaj dane uwierzytelniające wymagane do danego żądania.

  • 403 Forbidden oznacza, że użytkownik nie ma uprawnień do żądanego zasobu.

    • Sprawdź, czy użytkownik uzyskał niezbędne uprawnienia, na przykład przyznając mu dostęp do pliku w żądaniu opartym na pliku.

  • 404 Not Found oznacza, że żądany zasób nie istnieje.

    • Sprawdź, czy URL punktu końcowego interfejsu API jest prawidłowy.
    • Jeśli pobierasz zasób, sprawdź, czy dany zasób istnieje (np. czy istnieje plik w przypadku interfejsu API opartego na plikach).

Sprawdź prośby

Sprawdzanie żądań jest przydatne, gdy odpowiedzi interfejsu API wskazują, że żądanie jest nieprawidłowo sformułowane, na przykład kod stanu 400. Aby ułatwić analizowanie żądań, UrlFetchApp udostępnia metodę towarzyszącą metodzie fetch() o nazwie getRequest().

Zamiast wysyłać żądanie do serwera, ta metoda generuje żądanie, które zostało wysłane, a następnie je zwraca. Dzięki temu użytkownik może sprawdzić elementy żądania i upewnić się, że wygląda ono prawidłowo.

Jeśli na przykład dane formularza w żądaniu składają się z wielu połączonych ze sobą ciągów znaków, błąd może wiązać się z funkcją, która została utworzona w celu generowania tych danych. W najprostszy sposób:

const request = UrlFetchApp.getRequest(url, params);
console.log(request);
// Now make the fetch:
const response = UrlFetchApp.fetch(url, params);
// ...

pozwoli Ci sprawdzić elementy żądania.

Rejestruj żądania i odpowiedzi

Aby pomóc w całym procesie sprawdzania żądań i odpowiedzi wysyłanych do interfejsu API innej firmy, możesz użyć poniższej funkcji pomocniczej jako zamiennika UrlFetchApp.fetch(), aby rejestrować zarówno żądania, jak i odpowiedzi.

  1. Zastąp wszystkie wystąpienia UrlFetchApp.fetch() w kodzie ciągiem logUrlFetch().

  2. Dodaj poniższą funkcję na końcu skryptu.

    function logUrlFetch(url, opt_params) {
  const params = opt_params || {};
  params.muteHttpExceptions = true;
  const request = UrlFetchApp.getRequest(url, params);
  console.log('Request:       >>> ' + JSON.stringify(request));
  const response = UrlFetchApp.fetch(url, params);
  console.log('Response Code: <<< ' + response.getResponseCode());
  console.log('Response text: <<< ' + response.getContentText());
  if (response.getResponseCode() >= 400) {
    throw Error('Error in response: ' + response);
  }
  return response;
}

Podczas wykonywania skryptu w konsoli są rejestrowane szczegóły wszystkich żądań i odpowiedzi, co ułatwia debugowanie.