Interfejsy API firm zewnętrznych

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

W tym przewodniku omawiamy zagadnienia, które pomogą Ci w pisaniu skryptów połączyć się z innymi usługami:

  • Tworzenie żądań HTTP: jak używać tych danych UrlFetchApp, aby uzyskać dostęp zewnętrznych interfejsów API.
  • Uwierzytelnianie: omówimy kilka typowych scenariuszy uwierzytelniania.
  • Analiza odpowiedzi: jak przetwarzać zwrócone dane JSON i XML.

Uwzględniamy też samples dla liczby popularnych interfejsów API, które ilustrują te koncepcje.

Pobierz dane za pomocą UrlFetchApp

UrlFetchApp udostępnia główna funkcjonalność wymagana do interakcji z interfejsami API innych firm.

Poniższy przykład pokazuje pobieranie danych pogodowych z: OpenWeatherMap. Wybraliśmy OpenWeatherMap ze względu na to, jego stosunkowo prostego schematu autoryzacji i interfejsu API.

Poproś

Dokumentacja OpenWeatherMap określa format żądania aktualnej pogody w następujący sposób:

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

Adres URL zawiera pierwszy przykład autoryzacji: parametr apikey ma postać Wartość jest unikalna dla każdego użytkownika. Ten klucz uzyskuje się przez Twoją subskrypcję.

Po rejestracji żądanie używające klucza można wysłać 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 JSON. w oknie logowania w skryptach Google Ads.

Następnym krokiem jest przekonwertowanie go na format, który można stosować skrypt.

Dane JSON

Wiele interfejsów API dostarcza odpowiedzi w formacie JSON. To proste rozwiązanie serializacji obiektów JavaScript, m.in. obiektów, tablic i typów podstawowych; mogą być przedstawiane i przekazywane jako ciągi tekstowe.

Aby przekonwertować ciąg znaków JSON, np. zwrócony z OpenWeatherMap – z powrotem do obiektu JavaScript, użyj wbudowanej Metoda JSON.parse. Nawiązując do poprzedniego 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 znajdziesz w sekcji Analizowanie odpowiedzi. pracy z odpowiedziami interfejsu API w różnych formatach.

Obsługa błędów

Obsługa błędów jest ważną kwestią przy pracy z interfejsami API innych firm. w skryptach, ponieważ interfejsy API innych firm często się zmieniają i generują nieoczekiwane wartości odpowiedzi, na przykład:

  • URL lub parametry interfejsu API mogą się zmienić bez Twojej wiedzy.
  • Twój klucz interfejsu API (lub inne dane logowania) może wygasnąć.
  • Format odpowiedzi może się zmienić bez powiadomienia.

Kody stanów HTTP

Ze względu na możliwość wystąpienia nieoczekiwanych odpowiedzi zalecamy sprawdzenie protokołu HTTP kodu stanu. Domyślnie Jeśli wystąpi kod błędu HTTP, UrlFetchApp zgłosi wyjątek. Do zmienić to zachowanie, konieczne jest przekazanie parametru opcjonalnego, np. następujący przykład:

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

W przypadku zmiany interfejsów API innych firm deweloperzy często nie są od razu świadomi, zmian, które mogą mieć wpływ na skrypty. Jeśli na przykład właściwość name zwracany w przykładowym pliku OpenWeatherMap zmieniono na locationName, skrypty za pomocą tej właściwości nie uda się.

Z tego powodu warto sprawdzić, czy zwrócona struktura jest zgodnie 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 za pomocą UrlFetchApp

Przykład wprowadzający z OpenWeatherMap tylko pobrane dane. Zwykle wywołania interfejsu API nie zmieniają stanu na pilocie serwer używa HTTP GET .

Metoda GET jest domyślną metodą w przypadku UrlFetchApp. Niektóre wywołania interfejsu API takich jak połączenia z usługą wysyłającą SMS-y będą wymagać innych metod, np. POST lub PUT.

Aby pokazać, jak korzystać z wywołań POST za pomocą funkcji UrlFetchApp, przedstawiamy przykład przedstawia integrację ze Slack – usługą umożliwiającą współpracę do wysyłania wiadomości do użytkowników i grup aplikacji Slack.

Konfigurowanie Slacka

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

Tak jak w przypadku OpenWeatherMap w poprzednim przykładzie, konieczne jest uzyskanie , aby umożliwić wysyłanie wiadomości. Slack udostępnia unikalny adres URL, aby umożliwić Ci: wysyłania wiadomości do swojego zespołu – tzw. przychodzącego webhooka.

Skonfiguruj przychodzącego webhooka, klikając Dodaj integrację przychodzącą WebHooks i postępuj zgodnie z instrukcjami. powinien wysłać adres URL, który będzie używany do przesyłania wiadomości.

Utwórz żądanie POST

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

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

  • payload: to dane, które zostaną wysłane na serwer w ramach POST użytkownika. W tym przykładzie Slack oczekuje obiektu zserializowanego w formacie JSON zgodnie z opisem w narzędziu Slack dokumentacji. Do tego celu JSON.stringify jest używana, a Content-Type ma wartość 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 Extended Slack

Przykład powyżej pokazuje minimalną kwotę, która musi być stworzona, aby włączyć wiadomości przychodzące na Slacku. An rozszerzony sample ilustruje tworzenia i wysyłania raportu Skuteczność kampanii, Zgłoś do grupę oraz niektóre opcje formatowania i wyświetlania.

Wiadomość przychodząca

Zobacz formatowanie wiadomości w Slacku dokumentacji ze szczegółowymi informacjami o wiadomościach na Slacku.

Dane formularzy

W powyższym przykładzie pokazano użycie ciągu znaków JSON jako właściwości payload. dla żądania POST.

W zależności od formatu danych payload UrlFetchApp stosuje różne podejścia do utworzenia żądania POST:

  • Gdy payload jest ciągiem znaków, argument ten jest wysyłany jako treści żą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!

    Dodatkowo 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, dlatego to automatyczna konwersja obiektów JavaScript na dane jest przydatna, pod uwagę.

Podstawowe uwierzytelnianie HTTP

Podstawowe HTTP uwierzytelnianie jest jednym z tych to najprostsza metoda uwierzytelniania, która jest używana w wielu interfejsach API.

Uwierzytelnianie polega na dołączeniu zakodowanej nazwy użytkownika i hasła do Nagłówki HTTP w każdym żądaniu.

Podstawowe uwierzytelnianie HTTP

Utwórz żądanie

Do wygenerowania uwierzytelnionego żądania wymagane są te czynności:

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

Poniższy fragment kodu pokazuje, jak to zrobić w Skryptach 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 uwierzytelniania podstawowego

Przykładowy kod zawiera dwie przykłady korzystania z podstawowego uwierzytelniania HTTP:

Plivo

Plivo to usługa, która umożliwia odbieranie wiadomości SMS za pomocą interfejsu API. Ten przykład pokazuje wysyłanie wiadomości.

  1. Zarejestruj się w Plivo.
  2. Wklej przykładowy skrypt w: 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 do powiadomień z .
  5. Aby korzystać z Plivo, musisz kupić numery lub dodać numery do okresu próbnego koncie. Dodaj numery piaskownicy, które mogą na koncie próbnym.
  6. Dodaj numer, który wyświetli się jako nadawca, i adres odbiorcy numer.
  7. Zaktualizuj PLIVO_SRC_PHONE_NUMBER w skrypcie do jednego z numerów piaskownicy właśnie się zarejestrowano. Powinien on zawierać międzynarodowy numer kierunkowy kraju, przykład 447777123456 dla numeru w Wielkiej Brytanii.

Twilio

Twilio to kolejna usługa, która ułatwia wysyłanie i odbieranie wiadomości SMS za pomocą interfejsu API. Ten przykład pokazuje wysyłanie 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 widoczne na stronie konsoli konta.
  4. Zastąp TWILIO_SRC_PHONE_NUMBER numerem z panel – to Numer autoryzowany przez Twilio do wysyłania wiadomości.

OAuth 1.0

Wiele popularnych usług korzysta z protokołu OAuth. Protokół OAuth jest dostępny w różnych smaków i wersji.

Z kolei podstawowe uwierzytelnianie HTTP ma tylko jedną nazwę użytkownika i hasło, protokół OAuth pozwala aplikacjom innych firm dostępu do konta i danych użytkownika za pomocą specyficznych dla tego konta danych logowania, aplikacji zewnętrznej. Ponadto zakres dostępu będzie do danej aplikacji.

Informacje o protokole OAuth 1.0 znajdziesz w Podstawowym przewodniku dotyczącym protokołu OAuth. W szczególności zobacz 6. Uwierzytelnianie przy użyciu OAuth. W całości trzyetapowym OAuth 1.0, proces przebiega w następujący sposób:

  1. Aplikacja („Konsument”) uzyskuje 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 użytkownika.

Aby usługi innych firm mogły korzystać z protokołu OAuth 1.0 bez interakcji użytkownika (na przykład (co wymagałyby skrypty Google Ads) kroki 1, 2 i 3 są niemożliwe. Dlatego niektóre usługi wystawiają token dostępu ze swojej konfiguracji co pozwoli aplikacji przejść bezpośrednio do kroku 4. Jest to tzw. jednoetapowej autoryzacji 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ń administracyjnych dla danej usługi w konsoli jest to zwykle niezbędne do:

  • Ustaw konfigurację aplikacji reprezentującą skrypt.
  • Określ, które uprawnienia mają być rozszerzane do skryptu.
  • Uzyskiwanie do użycia klucza klienta, tajnego klucza klienta, tokena dostępu i obiektu tajnego dostępu za pomocą jednoetapowej autoryzacji OAuth.

OAuth 2.0

Protokół OAuth 2.0 jest używany w popularnych interfejsach API do zapewniania dostępu do danych użytkownika. Przyznane przez właściciela konta danej usługi innej firmy uprawnienia dostępu do określonych aplikacji, aby umożliwić im dostęp do danych użytkownika. Zaletą jest to, że właściciel:

  • Nie musi udostępniać aplikacji danych logowania do konta.
  • Może kontrolować, które aplikacje mają mieć dostęp do danych, oraz jak w jakim stopniu. (Przyznany dostęp może być na przykład tylko do odczytu lub tylko podzbiór danych).

Aby korzystać w skryptach Google Ads z usług obsługujących OAuth 2.0, kroki:

Poza skryptem

Przyznaj skryptom Google Ads autoryzację dostępu do danych użytkownika za pomocą API innej firmy. W większości przypadków będzie to wymagało skonfigurowania application (aplikacja) w konsoli usługi innej firmy. Ta aplikacja jest skryptem Google Ads.

Określasz uprawnienia dostępu aplikacji do Skryptu Google Ads i zazwyczaj otrzymuje identyfikator klienta. Dzięki temu możesz: OAuth 2, aby kontrolować, które aplikacje mają dostęp do Twoich danych w usłudze innej firmy oraz informacje o tym, jakie aspekty tych danych może ona zobaczyć modyfikować.

W skrypcie

Autoryzuj na serwerze zdalnym. W zależności od typu uwierzytelnienia z serwera, będzie trzeba wykonać inny zestaw kroków, nazywany przepływem ale tak naprawdę wszystko będzie działało tak, że token dostępu to i które będą używane w tej sesji w przypadku wszystkich kolejnych żądań.

wysyłanie żądań do interfejsu API, Przekazuj token dostępu z każdym żądaniem.

Przepływy autoryzacji

Każdy typ uwierzytelnienia i odpowiadający mu przepływ pasuje do różnych scenariuszy użycia. Dla: Inny proces ma zastosowanie, gdy użytkownik bierze udział w interaktywnej interakcji, w przeciwieństwie do sytuacji, w której aplikacja musi działać w tle bez obecności użytkownika.

Dostawcy interfejsów API zdecydują, które typy uwierzytelniania są akceptowane, co pomoże jak użytkownik postępuje w ramach integracji interfejsu API.

Implementacja

W przypadku wszystkich różnych przepływów OAuth celem jest uzyskanie tokena dostępu, może być używany do uwierzytelniania żądań przez pozostałą część sesji.

przykładową bibliotekę, pokazuje, jak uwierzytelniać się w przypadku różnych typów przepływu. Każda z tych opcji zwraca obiekt, który pobiera i przechowuje token dostępu, obsługuje uwierzytelnione żądania.

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

Przyznanie danych logowania klienta

Przyznanie danych logowania klienta to jednej z prostszych form przepływu OAuth2, w których aplikacja wymienia identyfikator i obiekt tajny, unikalne dla aplikacji, w zamian za wydanie ograniczony czasowo token dostępu.

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

Odśwież przyznane tokeny

Przyznawanie tokena odświeżania jest podobne do przyznawania danych logowania klienta, o ile proste żądanie do serwera zwróci token dostępu, którego można użyć; podczas sesji.

Token odświeżania

Uzyskiwanie tokena odświeżania

Różnica w przypadku przyznania tokena odświeżania jest taka, że szczegóły wymagane w przypadku przyznania danych logowania klienta pochodzących z konfiguracji aplikacji (na przykład w panelu sterowania usługi) token odświeżania zostanie przyznany. mogą być częścią bardziej złożonego procesu, takiego jak kod autoryzacji grant, która wymaga użytkownika interakcja:

Kod autoryzacji

Uzyskiwanie tokena odświeżania przy użyciu protokołu OAuth Playground

place zabaw OAuth2 udostępnia interfejs użytkownika, przez proces przyznawania kodu autoryzacji w celu uzyskania tokena odświeżania.

Za pomocą przycisku ustawień w prawym górnym rogu możesz zdefiniować wszystkie parametry w procesie OAuth, takich jak:

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

Środowisko do testowania protokołu OAuth

Uzyskiwanie tokena odświeżania za pomocą skryptu

Oparta na skryptach alternatywa dla ukończenia procesu jest dostępna w token odświeżania generacja przykład.

Odśwież wykorzystanie tokenów

Po przeprowadzeniu wstępnej autoryzacji usługi mogą odświeżyć stronę , którego można następnie używać w sposób podobny do przepływu danych logowania klienta. Poniżej podajemy 2 przykłady:

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

Przykład w Search Ads 360

Przykładem interfejsu API jest Search Ads 360, którego można użyć z tokenem odświeżania. W tym przykładzie skrypt generuje i zwraca . Dowiedz się więcej o reklamach w wyszukiwarce Dokumentacja interfejsu API Analytics 360 zawiera szczegółowe informacje o innych działaniach. jakie można osiągnąć.

Tworzenie skryptu
  1. Utwórz nowy projekt w konsoli interfejsów API. i uzyskać identyfikator klienta, tajny klucz klienta oraz token odświeżania, postępując zgodnie z w przewodniku DoubleClick, Upewnij się, że włączony jest interfejs DoubleClick Search API.
  2. Wklej przykład. skrypt na nowego skryptu w Google Ads.
  3. Wklej przykładowy protokół OAuth2 biblioteki w sekcji .
  4. Zmodyfikuj skrypt tak, aby zawierał prawidłowe wartości identyfikatora klienta, tajnego klucza klienta i odśwież token.

Przykład interfejsu Apps Script Execution API

Ten przykład pokazuje wykonywanie funkcji w Apps Script za pomocą interfejsu Apps Script Script Execution API. Dzięki temu Apps Script być wywoływane przez skrypty Google Ads.

Tworzenie skryptu Apps Script

Utwórz nowy skrypt. Poniższy przykładowy fragment 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 wykonywania Apps Script
  1. Zapisz skrypt.
  2. Kliknij Zasoby > Projekt Cloud Platform.
  3. Kliknij nazwę projektu, aby otworzyć konsolę interfejsu API.
  4. Otwórz Interfejsy API & Usługi.
  5. Włącz odpowiednie interfejsy API, w tym przypadku Dysk API oraz Google Apps Wykonywanie skryptu API.
  6. W menu kliknij Credentials (Dane logowania), aby utworzyć dane logowania OAuth.
  7. Wróć do skryptu i opublikuj go do wykonania po kliknięciu Opublikuj > Wdróż jako plik wykonywalny interfejsu API.
Tworzenie skryptu Google Ads
  1. Wklej przykład. skrypt na nowego skryptu w Google Ads.
  2. Dodatkowo wklej przykładowy OAuth2 biblioteki w sekcji .
  3. Zmodyfikuj skrypt tak, aby zawierał prawidłowe wartości identyfikatora klienta, tajnego klucza klienta i odśwież token.

Konta usługi

Alternatywą dla powyższych typów uwierzytelnień jest koncepcja usługi kont.

Konta usługi różnią się od tych powyżej tym, że nie służą do uzyskiwania dostępu do użytkowników dane: po uwierzytelnieniu żądania są wysyłane przez konto usługi w imieniu użytkownika jako użytkownik aplikacji, a nie użytkownik mogący być właścicielem projektu. Na przykład, jeśli konto usługi miało użyć interfejsu Drive API do utworzenia pliku, należą do konta usługi i domyślnie nie są dostępne właściciel projektu.

Przykład interfejsu Google Natural Language API

Interfejs natural Language API udostępnia nastawienie analiza oraz jednostka analizy tekstu.

Ten przykład pokazuje, jak obliczać nastawienie pod kątem tekstu reklamy, w tym nagłówka lub tekstu reklamy. Zapewnia to wskaźnik dla: i pozytywny jest przekaz: co jest lepsze, Sprzedajemy ciasta lub sprzedajemy najlepsze ciasta w Warszawie. Kup już dziś?

Konfigurowanie skryptu
  1. Utwórz nowy projekt w konsoli interfejsów API.
  2. Włącz język naturalny Interfejs API
  3. Włącz płatności w projekcie.
  4. Utwórz usługę Konto. Pobierz plik JSON z danymi logowania.
  5. Wklej przykład. skrypt w nowym formacie skrypt w Google Ads.
  6. Dodatkowo wklej przykładowy OAuth2 biblioteki w sekcji .
  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 usługi. Konto. Rozpoczyna się -----BEGIN PRIVATE KEY... i kończy ...END PRIVATE KEY-----\n.

Odpowiedzi interfejsu API

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

JSON

Format JSON jest zwykle prostszy niż format XML. . Nadal jednak mogą wystąpić pewne problemy.

Weryfikacja odpowiedzi

Po uzyskaniu prawidłowej odpowiedzi z wywołania interfejsu API typowa następnym krokiem jest użycie ciągu JSON.parse do skonwertowania ciągu JSON na kod JavaScript. obiektu. Na tym etapie rozsądnie jest odnieść się do sytuacji, w której błędy:

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

Ponadto jeśli nie masz kontroli nad interfejsem API, weź pod uwagę, że struktura odpowiedź może ulec zmianie i usługi 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

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

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

Z kolei XmlService.parse wykrywa błędy w pliku XML i zgłasza wyjątki dlatego nie umożliwia sprawdzenia poprawności kodu XML w schemat.

Element główny

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

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

Przestrzenie nazw

W poniższym przykładzie interfejs API Sportradar służy do uzyskania wyników dotyczących wybranych meczów piłkarskich. Odpowiedź XML trwa w tym formacie:

<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 niezbędne do:

  • Wyodrębnij z dokumentu atrybut przestrzeni nazw.
  • 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 przykładzie. fragment 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ę przykład z harmonogramu futbolu:

<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ą getText(), ale zostaną one być połączony w miejscach, w których element zawiera wiele elementów podrzędnych. Rozważ za pomocą metody getChildren() i powtarzając to zadanie dla każdego dziecka w przypadkach, gdy w przypadku dzieci.

Przykład Sportradar

Pełne Sportradar przykład ilustruje pobieranie szczegółów meczów piłki nożnej, w szczególności angielskiej Premier League; dopasowania. Soccer API to jeden z szerokiej gamy kanałów sportowych oferowanych przez Sportradar.

Załóż konto 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 się otwórz stronę MyAccount (Moje konto).

Sportradar rozdziela różne dyscypliny sportowe na różne interfejsy API. Na przykład: użytkownik może kupić dostęp do interfejsu Soccer API, ale nie Tennis API. Każdy Z Twoją aplikacją mogą być powiązane różne dyscypliny sportu, różne klawisze.

  1. W sekcji Applications (Aplikacje) kliknij Create a new Application (Utwórz nową aplikację). Wysyłanie aplikacji podaj nazwę i opis witryny, a potem zignoruj pole witryny.
  2. Wybierz tylko opcję Issue a new key for Soccer trial Europe v2 (Wystaw nowy klucz dla Soccer okresu próbnego Europa v2).
  3. Kliknij Register Application (Zarejestruj aplikację).

Jeśli proces się powiedzie, powinna wyświetlić się strona z nowym kluczem interfejsu API.

  1. Wklej przykładowy skrypt. do nowego skryptu w Google Ads.
  2. Zastąp klucz interfejsu API na stronie kluczem uzyskanym powyżej i zmodyfikuj wartość adres e-mail.

Rozwiązywanie problemów

W przypadku korzystania z interfejsów API innych firm błędy mogą występować z różnych powodów, przykład:

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

We wszystkich tych i innych przypadkach dobrym pierwszym krokiem do zidentyfikowania przyczyny jest sprawdzenie szczegółów odpowiedzi, która powoduje błąd.

Analizuj odpowiedzi

Domyślnie każda odpowiedź zwracająca błąd (stan co najmniej 400) generowane przez mechanizm skryptów Google Ads.

Aby temu zapobiec i umożliwić wyświetlanie komunikatu o błędzie należy ustawić 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 powodzenie. Jeśli odpowiedź nie zawiera oczekiwanego pamiętaj, że:

    • Niektóre interfejsy API umożliwiają określenie pól lub formatu odpowiedzi i ich używanie. Szczegółowe informacje na ten temat znajdziesz w dokumentacji interfejsu API.
    • Interfejs API może mieć wiele zasobów, które można wywoływać. Skonsultuj się z dokumentacji pozwalającej określić, czy inny zasób może być bardziej odpowiednie do zastosowania oraz zwróci Ci potrzebne dane.
    • Interfejs API mógł się zmienić od czasu napisania kodu. Skonsultuj się z lub programisty, aby uzyskać wyjaśnienia.

  • 400 Bad Request zwykle oznacza, że coś jest nie tak w atrybucie formatowanie lub strukturę żądania wysłanego do serwera. Sprawdź żądania i porównać je ze specyfikacjami interfejsu API, aby upewnić się, że spełnia ono z oczekiwaniami. Więcej informacji znajdziesz w sekcji Sprawdzanie żądań. jak je analizować.

  • 401 Unauthorized zwykle oznacza, że interfejs API jest wywoływany bez podania lub przeprowadzić autoryzację.

    • Jeśli interfejs API używa podstawowej autoryzacji, upewnij się, że nagłówek Authorization jest tworzona i dostarczana w żądaniu.
    • Jeśli interfejs API korzysta z protokołu OAuth 2.0, upewnij się, że został uzyskany token dostępu i są udostępniane jako token okaziciela.
    • W przypadku wszelkich innych odmian autoryzacji upewnij się, że atrybuty dane logowania dla żądania są podawane.

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

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

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

    • Sprawdź, czy adres URL punktu końcowego API jest prawidłowy.
    • Jeśli pobierasz zasób, sprawdź, czy zasób, którego dotyczy odwołanie, istnieje (na przykład jeśli plik istnieje w przypadku interfejsu API opartego na plikach).

Sprawdź żądania

Sprawdzanie żądań jest przydatne, gdy odpowiedzi interfejsu API wskazują na nieprawidłowe żądania np. kod stanu 400. Aby ułatwić rozpatrywanie próśb, UrlFetchApp ma metodę towarzyszącą metodzie fetch() o nazwie getRequest().

Ta metoda nie wysyła żądania do serwera, tylko je tworzy który zostałby wysłany, a następnie go zwraca. Dzięki temu użytkownik może: sprawdzać elementy żądania, aby upewnić się, że wygląda ono prawidłowo.

Jeśli na przykład dane formularza w żądaniu składają się z wielu połączonych ciągów znaków błąd może wynikać z funkcji utworzonej do wygenerowania tego formularza i skalowalnych danych. Najprościej:

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

pozwala na przeanalizowanie elementów żądania.

Rejestruj żądania i odpowiedzi

Aby pomóc w całym procesie sprawdzania próśb i odpowiedzi zewnętrznego interfejsu API, można użyć poniższej funkcji pomocniczej zamienniku UrlFetchApp.fetch(), aby rejestrować zarówno żądania, jak i odpowiedzi.

  1. Zastąp wszystkie wystąpienia ciągu UrlFetchApp.fetch() w kodzie kodem 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 szczegóły wszystkich żądań i odpowiedzi są logowane w konsoli, co ułatwia debugowanie.