Interfejsy API firm zewnętrznych

Potężną funkcją skryptów Google Ads jest możliwość integracji ze źródłami danych i usługami z interfejsów API innych firm.

W tym przewodniku omawiamy te zagadnienia, które mogą Ci pomóc w pisaniu skryptów do łączenia się z innymi usługami:

  • Wysyłanie żądań HTTP: dowiedz się, jak używać interfejsu UrlFetchApp do uzyskiwania dostępu do zewnętrznych interfejsów API.
  • Uwierzytelnianie: omawiamy kilka typowych scenariuszy uwierzytelniania.
  • Parsowanie odpowiedzi: sposób przetwarzania zwróconych danych w formacie JSON i XML.

Dołączyliśmy też przykłady dla kilku popularnych interfejsów API, które ilustrują te zagadnienia.

Pobieranie danych za pomocą aplikacji UrlFetchApp

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

Ten przykład pokazuje pobieranie danych pogodowych 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:

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

Adres URL zawiera nasz pierwszy przykład autoryzacji: parametr apikey jest wymagany, a jego wartość jest unikalna dla każdego użytkownika. Ten klucz można uzyskać, rejestrując się.

Po rejestracji możesz wysłać żądanie z kluczem w ten 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());

Wykonywanie tego kodu powoduje zapisanie długiego ciągu tekstu JSON w oknie logowania w składnikach Google Ads.

Następnym krokiem jest konwersja danych na format, który można wykorzystać w skrypcie.

Dane w formacie JSON

Wiele interfejsów API zwraca odpowiedzi w formacie JSON. Jest to prosta deserializacja obiektów JavaScript, dzięki której obiekty, tablice i podstawowe typy mogą być reprezentowane i przenoszone jako ciągi znaków.

Aby przekonwertować ciąg tekstowy JSON (np. zwrócony przez OpenWeatherMap) na obiekt JavaScript, użyj wbudowanej metody JSON.parse. W dalszym ciągu przykładu powyżej:

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 obsługiwaniu odpowiedzi interfejsu API w różnych formatach znajdziesz w sekcji Parsowanie odpowiedzi.

Obsługa błędów

Obsługa błędów jest ważną kwestią podczas pracy ze skryptami korzystającymi z interfejsów API innych firm, ponieważ interfejsy API innych firm często się zmieniają i generują nieoczekiwane wartości odpowiedzi, na przykład:

  • Adres URL lub parametry interfejsu API mogą się zmienić bez Twojej wiedzy.
  • 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 możliwość uzyskania nieoczekiwanych odpowiedzi należy sprawdzić kod stanu HTTP. Domyślnie funkcja UrlFetchApp zgłasza wyjątek, jeśli napotka kod błędu HTTP. Aby zmienić to zachowanie, musisz przekazać parametr opcjonalny, 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 firm zewnętrznych ulegają zmianie, programiści często nie są od razu świadomi zmian, które mogą mieć wpływ na ich skrypty. Jeśli na przykład właściwość name zwracana w przykładzie OpenWeatherMap zostanie zmieniona na locationName, skrypty korzystające z tej właściwości nie będą działać.

Dlatego 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

Przykład wprowadzający z OpenWeatherMap pobiera tylko dane. Zazwyczaj wywołania interfejsu API, które nie zmieniają stanu na serwerze zdalnym, używają metody HTTP GET.

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

Aby zilustrować korzystanie z rozmów POST w usłudze UrlFetchApp, w następującym przykładzie pokazano integrację z aplikacją Slack, która umożliwia współpracę przy wysyłaniu wiadomości do użytkowników i grup Slack.

Konfigurowanie Slacka

W tym przewodniku przyjęto założenie, że masz już zarejestrowane konto Slack.

Podobnie jak w przypadku OpenWeatherMap w poprzednim przykładzie, do wysyłania wiadomości musisz uzyskać token. Slack udostępnia unikalny adres URL, który umożliwia wysyłanie wiadomości do zespołu. Nazywa się on Incoming Webhook (Wejściowy webhook).

Skonfiguruj webhook przychodzący, klikając Dodaj integrację z webhookami przychodzącymi i postępując zgodnie z instrukcjami. Proces powinien wygenerować adres URL do wysyłania wiadomości.

Wysyłanie żądania POST

Po skonfigurowaniu przychodzącego web hooka wystarczy przesłać żądanie POST, używając dodatkowych właściwości w parametrze options przekazywanym do UrlFetchApp.fetch:

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

  • payload: dane, które mają zostać wysłane na serwer w ramach żądania POST. W tym przykładzie Slack oczekuje obiektu zserializowanego w formacie JSON zgodnie z opisem w dokumentacji Slacka. W tym celu używana jest metoda JSON.stringify, a wartość parametru Content-Type to 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);

Rozszerzony przykład w Slacku

Przykład powyżej pokazuje minimalne ustawienia umożliwiające otrzymywanie wiadomości w Slacku. Rozszerzony przykład ilustruje tworzenie i wysyłanie raportu Skuteczność kampanii do grupy, a także niektóre opcje formatowania i wyświetlania.

Wiadomość przychodząca

Więcej informacji o wiadomościach w Slack znajdziesz w dokumentacji tej aplikacji.

Dane formularzy

W przykładzie powyżej jako parametr payload żądania POST użyto ciągu tekstowego JSON.

W zależności od formatu payload usługa UrlFetchApp stosuje różne podejścia do tworzenia żądania POST:

  • Jeśli payload to ciąg znaków, argument ciągu znaków jest wysyłany jako treść żądania.

  • Gdy payload jest obiektem, np. 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!

    Dodatkowo nagłówek Content-Type żądania ma wartość application/x-www-form-urlencoded.

Niektóre interfejsy API wymagają używania danych formularza podczas przesyłania żądań POST, dlatego warto pamiętać o automatycznym konwertowaniu obiektów JavaScriptu na dane formularza.

Podstawowe uwierzytelnianie HTTP

Podstawowe uwierzytelnianie HTTP to jedna z najprostszych form uwierzytelniania, która jest używana przez wiele interfejsów API.

Uwierzytelnianie odbywa się przez dołączenie zakodowanej nazwy użytkownika i hasła do nagłówków HTTP w każdym żądaniu.

Podstawowe uwierzytelnianie HTTP

Tworzenie żądania

Aby przesłać uwierzytelnione żądanie, wykonaj te czynności:

  1. Hasło wielowyrazowe tworzysz, łącząc nazwę użytkownika i hasło za pomocą dwukropka, np. username:password.
  2. Hasło należy zakodować w formacie Base64, np. username:password staje się dXNlcm5hbWU6cGFzc3dvcmQ=.
  3. Załącz do żądania nagłówek Authorization w formie Authorization: Basic <encoded passphrase>

Ten fragment kodu pokazuje, jak to zrobić w ramach 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);

Przykłady podstawowego uwierzytelniania

Sekcja przykłady kodu zawiera 2 przykłady, które pokazują, jak używać uwierzytelniania podstawowego HTTP:

Plivo

Plivo to usługa ułatwiająca wysyłanie i odbieranie SMS-ów za pomocą interfejsu API. Ten przykład pokazuje wysyłanie 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. Wpisz swój adres e-mail zgodnie z wytycznymi w skrypcie, aby otrzymywać powiadomienia o błędach.
  5. Aby korzystać z Plivo, musisz kupić numery lub dodać je do konta próbnego. Dodaj numery z piaskownicy, których możesz używać na koncie próbnym.
  6. Dodaj numer, który będzie widoczny jako numer nadawcy, oraz numer odbiorcy.
  7. Zmień PLIVO_SRC_PHONE_NUMBER w skrypcie na jeden z numerów w piaskownicy, który został właśnie zarejestrowany. Musi on zawierać 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 za pomocą interfejsu API. Ten przykład pokazuje wysyłanie wiadomości.

  1. Zarejestruj się w Twillio.
  2. Wklej przykładowy kod źródłowy 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 autoryzowany przez Twilio do wysyłania wiadomości.

OAuth 1.0

Wiele popularnych usług używa protokołu OAuth do uwierzytelniania. OAuth występuje w kilku odmianach i wersjach.

W przypadku podstawowego uwierzytelniania HTTP użytkownik ma tylko jedną nazwę użytkownika i hasło, natomiast OAuth umożliwia aplikacjom innych firm przyznawanie dostępu do konta i danych użytkownika za pomocą danych logowania właściwych dla danej aplikacji. Ponadto zakres dostępu będzie zależał od danej aplikacji.

Więcej informacji o OAuth 1.0 znajdziesz w przewodniku OAuth Core. Szczególnie 6. uwierzytelnianie za pomocą OAuth. W przypadku pełnego trójnoga OAuth 1.0 proces wygląda tak:

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

W przypadku usług innych firm,które korzystają z protokołu OAuth 1.0 bez interakcji z użytkownikiem (np. skryptów Google Ads), kroki 1–3 są niemożliwe do wykonania. Dlatego niektóre usługi generują token dostępu w konsoli konfiguracyjnej, co pozwala aplikacji przejść bezpośrednio do kroku 4. Nazywamy to 1-etapową autoryzacją 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 lub administracji usługi zazwyczaj trzeba:

  • Skonfiguruj konfigurację aplikacji, która będzie reprezentować skrypt.
  • Określ, jakie uprawnienia są przyznawane skryptowi.
  • Uzyskaj klucz klienta, tajny klucz klienta, token dostępu i tajny token dostępu do użycia z jednoetapową autoryzacją OAuth.

OAuth 2.0

OAuth 2.0 jest używany w popularnych interfejsach API do udostępniania danych użytkownika. Właściciel konta danej usługi innej firmy przyznaje uprawnienia określonym aplikacjom, aby umożliwić im dostęp do danych użytkownika. Zalety:

  • nie musi udostępniać aplikacji danych logowania do konta;
  • Możesz kontrolować, które aplikacje mają dostęp do danych i w jakim zakresie. (na przykład dostęp może być tylko do odczytu lub tylko do podzbioru danych).

Aby używać w skryptach Google Ads usług obsługujących OAuth 2.0, wykonaj te czynności:

Poza skryptem

Przyznaj skryptom Google Ads uprawnienia do uzyskiwania dostępu do danych użytkownika za pomocą interfejsu API innej firmy. W większości przypadków będzie to wymagało skonfigurowania aplikacji w konsoli usługi zewnętrznej. Ta aplikacja reprezentuje Twój skrypt Google Ads.

Określasz, jakie uprawnienia dostępu ma mieć aplikacja skryptu Google Ads, i zwykle przypisujesz jej identyfikator klienta. Dzięki temu możesz za pomocą OAuth 2 kontrolować, które aplikacje mają dostęp do Twoich danych w usłudze innej firmy, a także które aspekty tych danych mogą one wyświetlać lub modyfikować.

W skrypcie

Autoryzuj na serwerze zdalnym. W zależności od typu przyznanego dostępu serwera należy wykonać inny zestaw czynności, czyli przepływ, ale ostatecznie w każdym przypadku zostanie wygenerowany token dostępu, który będzie używany w tej sesji we wszystkich kolejnych żądaniach.

Wysyłać żądania do interfejsu API. Przesyłaj token dostępu z każdym żądaniem.

Przepływy autoryzacji

Każdy typ uprawnień i odpowiadający mu proces są przeznaczone do różnych scenariuszy użycia. Na przykład inny proces jest używany, gdy użytkownik bierze udział w interaktywnej sesji, a inny, gdy aplikacja musi działać w tle bez obecności użytkownika.

Dostawcy interfejsów API będą decydować, które typy grantów akceptują, a to z kolei będzie determinować, jak użytkownik będzie integrować interfejs API.

Implementacja

Celem wszystkich różnych przepływów OAuth jest uzyskanie tokena dostępu, który może być używany do uwierzytelniania żądań przez resztę sesji.

Przykładowa biblioteka, która pokazuje, jak uwierzytelniać się w ramach poszczególnych typów przepływów. Każda z tych metod zwraca obiekt, który pobiera i przechowuje token dostępu oraz umożliwia wysyłanie uwierzytelnionych żądań.

Ogólny wzorzec użytkowania:

// 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);

Przyznawanie danych logowania klienta

Przesłanie danych uwierzytelniających klienta to jedna z prostszych form protokołu OAuth2, w której aplikacja wymienia identyfikator i tajny klucz, unikalne dla aplikacji, w zamian za wydanie tokena dostępu o ograniczonym czasie ważności.

Identyfikator 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

Zezwolenie na odświeżanie tokena

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

Token odświeżania

Uzyskiwanie tokena odświeżania

Różnica polega na tym, że podczas gdy szczegóły wymagane do przyznania uprawnień do poświadczeń klienta pochodzą z konfiguracji aplikacji (np. z panelu sterowania usługi), token odświeżania jest przyznawany w ramach bardziej złożonego procesu, takiego jak przyznanie kodu autoryzacji, który wymaga interakcji użytkownika:

Kod autoryzacji

Uzyskiwanie tokena odświeżania za pomocą Playgrounda OAuth

Narzędzie OAuth2 playground udostępnia interfejs użytkownika, który umożliwia przejście przez proces udzielania uprawnień na podstawie kodu autoryzacji w celu uzyskania tokena odświeżania.

Za pomocą przycisku ustawień w prawym górnym rogu możesz zdefiniować wszystkie parametry, które mają być używane w procedurze OAuth, w tym:

  • Punkt końcowy autoryzacji: służy do rozpoczęcia procesu autoryzacji.
  • Punkt końcowy tokena: służy do uzyskiwania tokenów dostępu za pomocą tokena odświeżania.
  • Identyfikator i klucz klienta: dane logowania do aplikacji.

Playground OAuth

Uzyskiwanie tokena odświeżania za pomocą skryptu

Alternatywa dla wykonania tego procesu za pomocą skryptu jest dostępna w pliku generowania tokenu odświeżania.

Używanie tokena odświeżania

Po początkowym autoryzowaniu usługa może wydać token odświeżania, który można następnie wykorzystać w sposób podobny do przepływu danych logowania klienta. Poniżej znajdziesz 2 przykłady:

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

Przykład Search Ads 360

Search Ads 360 to przykład interfejsu API, którego można używać z tokenem odświeżania. W tym przykładzie skrypt generuje i zwraca raport. Pełną listę dostępnych działań znajdziesz w przewodniku po interfejsie Search Ads 360 API.

Tworzenie skryptu
  1. Utwórz nowy projekt w Konsoli interfejsów API i uzyskaj identyfikator klienta, klucz tajny klienta i token odświeżania, wykonując procedurę opisaną w instrukcji DoubleClick. Pamiętaj, aby włączyć 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, 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 ilustruje wykonywanie funkcji w Apps Script za pomocą interfejsu Apps Script Execution API. Dzięki temu można wywoływać Apps Script ze skryptów Google Ads.

Tworzenie skryptu Apps Script

Utwórz nowy skrypt. W tym przykładzie lista zawiera 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 Apps Script na potrzeby wykonania
  1. Zapisz skrypt.
  2. Kliknij Zasoby > Projekt Cloud Platform.
  3. Kliknij nazwę projektu, aby przejść do Konsoli API.
  4. Otwórz sekcję Interfejsy API i usługi.
  5. Włącz odpowiednie interfejsy API, w tym przypadku Drive API i interfejs Apps Script Execution API.
  6. Utwórz dane logowania OAuth z poziomu menu Dane logowania.
  7. Wróć do skryptu i opublikuj go do wykonania, klikając Opublikuj > Wdróż jako plik wykonywalny interfejsu 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, aby zawierał prawidłowe wartości identyfikatora klienta, tajnego klucza klienta i tokena odświeżania.

Konta usługi

Alternatywą dla wymienionych wyżej typów uprawnień jest koncepcja kont usługi.

Różnią się one od powyższych tym, że nie służą 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żytkownika, który może być właścicielem projektu. Jeśli na przykład konto usługi użyje interfejsu Drive API do utworzenia pliku, będzie ono należeć do tego konta i domyślnie nie będzie dostępne dla właściciela projektu.

Przykład interfejsu Google Natural Language API

Interfejs Natural Language API umożliwia analizę nastawienia i encji w tekście.

To przykład obliczenia nastroju w tekście reklamy, w tym w nagłówku lub tekście reklamy. Pozwala to określić, jak pozytywny jest przekaz i jakie ma znaczenie: czy lepiej powiedzieć Sprzedajemy ciasta czy Sprzedajemy najlepsze ciasta w Londynie? Kup już dziś!

Konfigurowanie skryptu
  1. Utwórz nowy projekt w Konsoli interfejsów API.
  2. Włącz interfejs 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 kod źródłowy w nowym kodzie 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 pobranego podczas tworzenia konta usługi. Rozpoczyna się -----BEGIN PRIVATE KEY... i kończy ...END PRIVATE KEY-----\n.

Odpowiedzi interfejsu API

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

JSON

Format JSON jest zwykle prostszy niż XML, jeśli chodzi o obsługę w ramach formatu odpowiedzi. Nadal jednak mogą wystąpić pewne problemy.

Weryfikacja odpowiedzi

Po otrzymaniu odpowiedzi na wywołanie interfejsu API należy użyć funkcji JSON.parse, aby przekonwertować ciąg znaków JSON na obiekt JavaScript. W tym miejscu warto obsłużyć przypadek, gdy wczytywanie nie powiedzie się:

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

Pamiętaj też, że jeśli nie masz kontroli nad interfejsem API, struktura odpowiedzi może się zmienić, a właściwości mogą przestać 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

XML jest nadal popularnym formatem do tworzenia interfejsów API. Odpowiedź na wywołanie 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.
}

Funkcja XmlService.parse wykrywa błędy w pliku XML i odpowiednio zgłasza wyjątki, ale nie umożliwia walidacji pliku XML na podstawie schematu.

Element główny

Po pomyślnym przeanalizowaniu dokumentu XML uzyskuje się element główny za pomocą metody getRootElement():

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

Przestrzenie nazw

W tym przykładzie interfejs Sportradar API służy do uzyskiwania wyników meczów piłki nożnej. Odpowiedź XML ma ten format:

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

Zwróć uwagę, że przestrzeń nazw jest określona w elemencie głównym. Z tego powodu konieczne jest:

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

Poniższy przykład pokazuje, 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);

Pobieranie wartości

Na podstawie przykładowego harmonogramu rozgrywek futbolowych:

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

Atrybuty można pobrać na przykład:

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

Tekst zawarty w elemencie można odczytać za pomocą getText(), ale jeśli element ma wiele elementów podrzędnych typu tekst, zostaną one złączone. W przypadku dużej liczby elementów podrzędnych zalecamy użycie funkcji getChildren() i przeszukanie każdego elementu podrzędnego.

Przykład dotyczący Sportradar

Ten pełny przykład dotyczący usługi Sportradar pokazuje, jak pobierać informacje o meczach piłki nożnej, w tym o meczch angielskiej Premier League. Interfejs Soccer API to jeden z wielu kanałów sportowych oferowanych przez Sportradar.

Konfigurowanie konta Sportradar
  1. Otwórz witrynę dla deweloperów Sportradar.
  2. Zarejestruj konto próbne.
  3. Po zarejestrowaniu się zaloguj się na swoje konto.
  4. Po zalogowaniu przejdź do sekcji MyAccount.

Sportradar rozdziela różne sporty na różne interfejsy API. Możesz na przykład kupić dostęp do interfejsu Soccer API, ale nie do interfejsu Tennis API. Każda utworzona aplikacja może mieć powiązane różne dyscypliny i różne klucze.

  1. W sekcji Aplikacje kliknij Utwórz nową aplikację. Podaj nazwę i opis aplikacji, a ignoruj pole witryny.
  2. Wybierz tylko Wydanie nowego klucza dla Soccer Trial Europe v2.
  3. Kliknij Zarejestruj aplikację.

Po pomyślnym wykonaniu tej czynności powinna się wyświetlić strona z nowym kluczem interfejsu API.

  1. Wklej przykładowy kod źródłowy do nowego skryptu w Google Ads.
  2. Zastąp klucz interfejsu API w karcie kluczem uzyskanym powyżej i edytuj pole adresu e-mail.

Rozwiązywanie problemów

Podczas pracy z interfejsami API innych firm mogą występować błędy z różnych powodów, na przykład:

  • Klienci wysyłający żądania do serwera w formacie innym niż oczekiwany przez interfejs API.
  • Klienci oczekują formatu odpowiedzi innego niż ten, który został użyty.
  • Klienci używający nieprawidłowych tokenów lub kluczy albo wartości pozostawionych jako zastępcze.
  • Klienci osiągający limity wykorzystania.
  • Klienci podający nieprawidłowe parametry.

We wszystkich tych i innych przypadkach dobrym pierwszym krokiem w identyfikacji przyczyny problemu jest zbadanie szczegółów odpowiedzi, która spowodowała błąd.

Analizowanie odpowiedzi

Domyślnie każda odpowiedź z błędem (kod stanu 400 lub wyższy) zostanie wyrzucona przez mechanizm skryptów Google Ads.

Aby zapobiec temu zachowaniu i umożliwić sprawdzenie błędu i komunikat o błędzie, ustaw właściwość muteHttpExceptions parametrów opcjonalnych 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 sukces. Jeśli odpowiedź nie zawiera oczekiwanych danych, weź pod uwagę te kwestie:

    • Niektóre interfejsy API umożliwiają określenie, które pola lub format odpowiedzi mają być używane. Szczegółowe informacje znajdziesz w dokumentacji interfejsu API.
    • Interfejs API może mieć wiele zasobów, które można wywołać. Zapoznaj się z dokumentacją, aby ustalić, czy inny zasób może być bardziej odpowiedni do użycia i czy zwróci wymagane dane.
    • Od czasu napisania kodu interfejs API mógł się zmienić. Aby uzyskać więcej informacji, zapoznaj się z dokumentacją lub skontaktuj się z deweloperem.

  • 400 Bad Request oznacza zwykle, że coś jest nie tak z formatowaniem lub strukturą żądania wysłanego do serwera. Sprawdź żądanie i porównaj je ze specyfikacją interfejsu API, aby mieć pewność, że jest zgodne z oczekiwaniami. Więcej informacji o sprawdzaniu żądań znajdziesz w artykule Sprawdzanie żądań.

  • 401 Unauthorized zwykle oznacza, że interfejs API jest wywoływany bez podania danych autoryzujących lub bez autoryzacji.

    • Jeśli interfejs API używa autoryzacji podstawowej, sprawdź, czy nagłówek Authorization jest tworzony i podawany w żądaniu.
    • Jeśli interfejs API korzysta z protokołu OAuth 2.0, upewnij się, że token dostępu został uzyskany i podany jako token okaziciela.
    • W przypadku innych rodzajów autoryzacji upewnij się, że zostały podane wymagane dane logowania.

  • 403 Forbidden oznacza, że użytkownik nie ma uprawnień do zasobu, którego dotyczy żądanie.

    • Upewnij się, że użytkownik ma niezbędne uprawnienia, na przykład dostęp do pliku w żądaniu opartym na pliku.

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

    • Sprawdź, czy adres URL używany do punktu końcowego interfejsu API jest prawidłowy.
    • Jeśli pobierasz zasób, sprawdź, czy istnieje zasób, do którego się odwołujesz (np. czy plik istnieje w przypadku interfejsu API opartego na plikach).

Sprawdzanie żądań

Sprawdzanie żądań jest przydatne, gdy odpowiedzi interfejsu API wskazują, że żądanie jest źle sformułowane, np. gdy zawiera kod stanu 400. Aby ułatwić sprawdzanie żądań, usługa UrlFetchApp ma metodę towarzyszącą do metody fetch() o nazwie getRequest().

Zamiast wysyłać żądanie do serwera, ta metoda tworzy żądanie, które zostałoby wysłane, a potem zwraca je. Dzięki temu użytkownik może sprawdzić elementy żądania, aby upewnić się, że jest ono prawidłowe.

Jeśli na przykład dane formularza w Twoim żądaniu składają się z wielu połączonych ze sobą ciągów znaków, błąd może występować w funkcji utworzonej do generowania tych danych. Najprościej:

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

umożliwia sprawdzenie elementów żądania.

Rejestrowanie żądań i odpowiedzi

Aby ułatwić cały proces sprawdzania żądań i odpowiedzi interfejsu API firmy zewnętrznej, możesz użyć tej funkcji pomocniczej jako zamiennika funkcji UrlFetchApp.fetch(), aby rejestrować żądania i ich odpowiedzi.

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

  2. Dodaj tę 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 szczegóły wszystkich żądań i odpowiedzi są rejestrowane w konsoli, co ułatwia debugowanie.