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 informacje o tych pojęciach, które mogą Ci pomóc w pisaniu skryptów łączących się z innymi usługami:
- Wysyłanie żądań HTTP: jak używać
UrlFetchAppdo uzyskiwania dostępu do zewnętrznych interfejsów API. - Uwierzytelnianie: omawiamy kilka typowych scenariuszy uwierzytelniania.
- Analizowanie odpowiedzi: jak przetwarzać zwrócone dane JSON i XML.
Dołączamy też przykłady dla wielu popularnych interfejsów API, które ilustrują te pojęcia.
Pobieranie danych za pomocą UrlFetchApp
UrlFetchApp zapewnia główną funkcjonalność wymaganą do interakcji z interfejsami API innych firm.
Poniższy 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 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 jest wymagany, a wartość jest unikalna dla każdego użytkownika. Klucz ten można uzyskać, rejestrując się.
Po rejestracji można wysłać żądanie z użyciem klucza 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());
Wykonanie tego kodu spowoduje zapisanie długiego ciągu znaków JSON w oknie logowania w skryptach Google Ads.
Następnym krokiem jest przekonwertowanie tego na format, którego można używać w skrypcie.
Dane JSON
Wiele interfejsów API udostępnia odpowiedzi w formacie JSON. Reprezentuje serializację obiektów w JavaScripcie, dzięki czemu obiekty, tablice i typy podstawowe mogą być reprezentowane i przesyłane jako ciągi znaków.
Aby przekonwertować ciąg znaków w formacie JSON (np. zwrócony przez OpenWeatherMap) z powrotem na obiekt w JavaScripcie, użyj wbudowanej metody JSON.parse. Kontynuując poprzedni przykład:
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 Analizowanie odpowiedzi.
Obsługa błędów
Obsługa błędów jest ważnym aspektem pracy z interfejsami API innych firm w skryptach, ponieważ te interfejsy często się zmieniają i generują nieoczekiwane wartości odpowiedzi, na przykład:
- Adres URL lub parametry interfejsu API mogą ulec zmianie bez Twojej wiedzy.
- Klucz interfejsu API (lub inne dane logowania użytkownika) 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 należy sprawdzić kod stanu HTTP. Domyślnie UrlFetchApp zgłosi wyjątek, jeśli wystąpi kod błędu HTTP. Aby zmienić to zachowanie, należy 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 ulegają zmianie, możesz nie od razu dowiedzieć się o zmianach, które mogą mieć wpływ na Twoje 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ć.
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
Przykładowy kod z OpenWeatherMap tylko pobierał dane. Zwykle wywołania interfejsu API, które nie zmieniają stanu na serwerze zdalnym, używają metody HTTP
GET.
Metoda GET jest domyślna dla UrlFetchApp. Jednak niektóre wywołania interfejsu API, takie jak wywołania usługi wysyłającej SMS-y, będą wymagały innych metod, takich jak POST lub PUT.
Aby zilustrować użycie wywołań POST z UrlFetchApp, w poniższym przykładzie pokazano integrację z aplikacją do obsługi wiadomości Slack, która umożliwia wysyłanie wiadomości do użytkowników i grup Slacka.
Skonfiguruj Slacka
W tym przewodniku zakładamy, że masz już konto Slack.
Podobnie jak w przypadku OpenWeatherMap w poprzednim przykładzie, aby umożliwić wysyłanie wiadomości, musisz uzyskać token. Slack udostępnia unikalny adres URL, który umożliwia wysyłanie wiadomości do zespołu. Jest on nazywany przychodzącym webhookiem.
Skonfiguruj przychodzącego webhooka, klikając Add Incoming WebHooks Integration (Dodaj integrację przychodzących webhooków) i postępując zgodnie z instrukcjami. Proces powinien wygenerować adres URL, którego można używać do przesyłania wiadomości.
Wysyłanie żądania POST
Po skonfigurowaniu przychodzącego webhooka wysłanie żądania POST wymaga użycia dodatkowych właściwości w parametrze options przekazywanym do UrlFetchApp.fetch:
method: jak wspomniano, domyślnie jest toGET, ale tutaj zastępujemy tę wartość i ustawiamy ją naPOST.payload: są to dane, które mają zostać wysłane na serwer w ramach żądaniaPOST. W tym przykładzie Slack oczekuje obiektu zserializowanego do formatu JSON, jak opisano w dokumentacji Slacka. W tym celu używana jest metoda [JSON.stringify][json-stringify-url], a parametrContent-Typejest ustawiony naapplication/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 Slacka
Poprzedni przykład pokazuje minimalny kod potrzebny do włączenia wiadomości przychodzących do Slacka. Rozszerzony przykład ilustruje tworzenie i wysyłanie raportu skuteczności kampanii do grupy, a także niektóre opcje formatowania i wyświetlania.

Więcej informacji o wiadomościach na Slacku znajdziesz w artykule o formatowaniu wiadomości w dokumentacji Slacka.
Dane formularzy
W poprzednim przykładzie pokazaliśmy, jak użyć ciągu JSON jako właściwości payload w żądaniu POST.
W zależności od formatu payload UrlFetchApp stosuje różne podejścia do tworzenia żądania POST:
- Gdy
payloadjest ciągiem znaków, argument ciągu znaków jest wysyłany jako treść żądania. Gdy
payloadjest 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!Nagłówek
Content-Typeżądania jest ustawiony naapplication/x-www-form-urlencoded.
Niektóre interfejsy API wymagają użycia danych formularza podczas przesyłania żądań POST, dlatego warto pamiętać o tej automatycznej konwersji obiektów w JavaScripcie na dane formularza.
Podstawowe uwierzytelnianie HTTP
Uwierzytelnianie podstawowe HTTP jest jedną z najprostszych form uwierzytelniania i jest używane 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.

Tworzenie żądania
Aby utworzyć uwierzytelnione żądanie, musisz wykonać te czynności:
- Utwórz hasło, łącząc nazwę użytkownika i hasło dwukropkiem, na przykład
username:password. - Zakoduj hasło w formacie Base64, na przykład
username:passwordzmieni się wdXNlcm5hbWU6cGFzc3dvcmQ=. - Dołącz do żądania nagłówek
Authorizationw formacieAuthorization: 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 podstawowego uwierzytelniania
Sekcja Przykładowy kod zawiera 2 przykłady ilustrujące użycie uwierzytelniania podstawowego HTTP:
Plivo
Plivo to usługa, która ułatwia wysyłanie i odbieranie SMS-ów za pomocą interfejsu API. Ten przykład ilustruje wysyłanie wiadomości.
- Zarejestruj się w Plivo.
- Wklej przykładowy skrypt do nowego skryptu w Google Ads.
- Zastąp wartości
PLIVO_ACCOUNT_AUTHIDiPLIVO_ACCOUNT_AUTHTOKENwartościami z panelu zarządzania. - Wpisz swój adres e-mail, jak określono w skrypcie, aby otrzymywać powiadomienia o błędach.
- Aby korzystać z Plivo, musisz kupić numery lub dodać je do konta próbnego. Dodaj numery piaskownicy, których można używać na koncie próbnym.
- Dodaj numer, który będzie wyświetlany jako nadawca, oraz numer odbiorcy.
- Zaktualizuj
PLIVO_SRC_PHONE_NUMBERw skrypcie do jednego z właśnie zarejestrowanych numerów piaskownicy. Powinien on zawierać międzynarodowy kod kraju, np.447777123456w 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 ilustruje wysyłanie wiadomości.
- Zarejestruj się w Twillio.
- Wklej przykładowy skrypt do nowego skryptu w Google Ads.
- Zastąp wartości
TWILIO_ACCOUNT_SIDiTWILIO_ACCOUNT_AUTHTOKENwartościami wyświetlanymi na stronie konsoli konta. - Zastąp
TWILIO_SRC_PHONE_NUMBERnumerem 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 różnych wersjach.
W przypadku uwierzytelniania podstawowego HTTP użytkownik ma tylko jedną nazwę użytkownika i jedno hasło, natomiast protokół OAuth umożliwia aplikacjom innych firm dostęp do konta i danych użytkownika przy użyciu danych logowania właściwych dla danej aplikacji. Zakres dostępu będzie też zależeć od aplikacji.
Więcej informacji o OAuth 1.0 znajdziesz w przewodniku po OAuth Core. W szczególności zapoznaj się z sekcją 6. Uwierzytelnianie za pomocą protokołu OAuth. W przypadku pełnego trzyskładnikowego uwierzytelniania OAuth 1.0 proces wygląda tak:
- Aplikacja („klient”) uzyskuje token żądania.
- Użytkownik autoryzuje token żądania.
- Aplikacja wymienia token żądania na token dostępu.
- W przypadku wszystkich kolejnych żądań zasobów token dostępu jest używany w podpisanym żądaniu.
Aby usługi innych firm mogły korzystać z protokołu OAuth 1.0 bez interakcji z użytkownikiem (jak w przypadku skryptów Google Ads), kroki 1, 2 i 3 nie są możliwe. Dlatego niektóre usługi wydają token dostępu z konsoli konfiguracji, co pozwala aplikacji przejść bezpośrednio do kroku 4. Jest to tzw. jednokierunkowy protokół OAuth 1.0.

OAuth 1.0 w skryptach Google Ads
W przypadku skryptów Google Ads każdy skrypt jest zwykle interpretowany jako aplikacja. W konsoli lub na stronie ustawień administracyjnych usługi zwykle trzeba:
- Skonfiguruj aplikację, która będzie reprezentować skrypt.
- Określ, jakie uprawnienia są przyznawane skryptowi.
- Uzyskaj klucz klienta, klucz tajny klienta, token dostępu i klucz tajny dostępu do użycia z jednoetapową autoryzacją OAuth.
OAuth 2.0
OAuth 2.0 jest używany w popularnych interfejsach API do zapewniania dostępu do danych użytkownika. Właściciel konta w danej usłudze innej firmy przyznaje określonym aplikacjom uprawnienia dostępu do danych użytkownika. Zalety tego rozwiązania:
- nie musi udostępniać aplikacji swoich danych logowania.
- Możesz określić, które aplikacje mają dostęp do danych i w jakim zakresie. (Może to być na przykład dostęp tylko do odczytu lub tylko do podzbioru danych).
Aby używać usług obsługujących protokół OAuth 2.0 w skryptach Google Ads, wykonaj te czynności:
- Poza skryptem
Zezwól skryptom Google Ads na dostęp do Twoich danych użytkownika za pomocą interfejsu API innej firmy. W większości przypadków wymaga to skonfigurowania aplikacji w konsoli usługi zewnętrznej. Ta aplikacja reprezentuje Twój skrypt.
Określasz, jakie uprawnienia dostępu powinna mieć aplikacja skryptów Google Ads, i zwykle przypisujesz jej identyfikator klienta. Dzięki temu możesz za pomocą protokołu OAuth 2.0 kontrolować, które aplikacje mają dostęp do Twoich danych w usłudze innej firmy, a także które aspekty tych danych mogą wyświetlać lub modyfikować.
- W skrypcie
Autoryzacja na serwerze zdalnym W zależności od typu uwierzytelnienia dozwolonego przez serwer należy wykonać inny zestaw kroków, zwany przepływem, ale wszystkie ostatecznie doprowadzą do wydania tokena dostępu, który będzie używany w tej sesji we wszystkich kolejnych żądaniach.
Wysyłanie żądań do interfejsu API. Przekaż token dostępu z każdym żądaniem.
Procesy autoryzacji
Każdy typ uwierzytelnienia i odpowiadający mu przepływ jest przeznaczony do różnych scenariuszy użycia. Na przykład inny proces jest używany, gdy użytkownik bierze udział w sesji interaktywnej, a inny, gdy aplikacja musi działać w tle bez obecności użytkownika.
Dostawcy interfejsów API decydują, które typy uwierzytelnienia akceptują, i to określa, jak użytkownik postępuje podczas integracji interfejsu API.
Implementacja
W przypadku wszystkich różnych procesów OAuth celem jest uzyskanie tokena dostępu, którego można następnie używać przez resztę sesji do uwierzytelniania żądań.
Przykładowa biblioteka pokazuje, jak przeprowadzić uwierzytelnianie w przypadku każdego typu przepływu. Każda z tych metod zwraca obiekt, który uzyskuje i przechowuje token dostępu oraz ułatwia uwierzytelnione żądania.
Ogólny wzorzec użycia:
// 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 uprawnień klienta
[Przyznanie danych uwierzytelniających klienta][client-credentials-rfc] to jedna z prostszych form przepływu OAuth2, w której aplikacja wymienia unikalny identyfikator i tajny klucz na ograniczony czasowo token dostępu.

// 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 przyznania danych logowania klienta, ponieważ żądanie wysłane do serwera zwraca token dostępu, którego można użyć w sesji.

Uzyskiwanie tokena odświeżania
Różnica w porównaniu z przyznaniem tokena odświeżania polega na tym, że szczegóły wymagane do przyznania danych uwierzytelniających klienta pochodzą z konfiguracji aplikacji (np. w panelu sterowania usługi), natomiast token odświeżania jest przyznawany w ramach bardziej złożonego przepływu, takiego jak [przyznanie kodu autoryzacji][authorization-code-rfc], który wymaga interakcji użytkownika:

- Uzyskiwanie tokena odświeżania za pomocą OAuth Playground
OAuth2 Playground udostępnia interfejs, który umożliwia użytkownikowi przejście przez proces przyznawania kodu autoryzacji w celu uzyskania tokena odświeżania.
Przycisk ustawień w prawym górnym rogu umożliwia zdefiniowanie wszystkich parametrów do użycia w procesie OAuth, w tym:
- Punkt końcowy autoryzacji: używany jako początek procesu autoryzacji.
- Punkt końcowy tokena: używany z tokenem odświeżania do uzyskania tokena dostępu.
Identyfikator klienta i obiekt tajny: dane logowania do aplikacji.

Wykorzystanie tokenów odświeżania
Po przeprowadzeniu początkowej autoryzacji usługi mogą wydać token odświeżania, którego można używać w podobny sposób jak w przypadku przepływu danych logowania klienta:
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łne informacje o innych działaniach, które można wykonywać, znajdziesz w dokumentacji interfejsu Search Ads 360 API.
Tworzenie skryptu
- Utwórz nowy projekt w konsoli Google Cloud i uzyskaj identyfikator klienta, klucz tajny klienta oraz token odświeżania, wykonując procedurę opisaną w przewodniku po Search Ads 360. Pamiętaj, aby włączyć interfejs Search Ads 360 API.
- Wklej [przykładowy skrypt][search-ads-360-example] do nowego skryptu w Google Ads.
- Wklej [przykładową bibliotekę OAuth2][oauth20-library-example] pod listą kodów.
- 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 pokazuje, jak wykonać funkcję w Apps Script za pomocą interfejsu Apps Script Execution API. Dzięki temu możesz wywoływać Apps Script ze skryptów Google Ads.
Tworzenie skryptu Apps Script
Utwórz nowy skrypt. Poniższy przykład wyświetli 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 Apps Script do wykonywania
- Zapisz skrypt.
- Kliknij Zasoby > Projekt Cloud Platform.
- Kliknij nazwę projektu, aby przejść do konsoli Google Cloud.
- Otwórz Interfejsy API i usługi.
- Włącz odpowiednie interfejsy API, w tym przypadku Drive API i Apps Script Execution API.
- Utwórz dane logowania OAuth, wybierając Dane logowania w menu.
- Wróć do skryptu i opublikuj go do wykonania, klikając Opublikuj > Wdróż jako plik wykonywalny interfejsu API.
Tworzenie skryptu Google Ads
- Wklej przykładowy skrypt do nowego skryptu w Google Ads.
- Dodatkowo wklej [przykładową bibliotekę OAuth2][oauth20-library-example] pod listą kodów.
- Zmień skrypt, aby zawierał prawidłowe wartości identyfikatora klienta, tajnego klucza klienta i tokena odświeżania.
Konta usługi
Alternatywą dla typów uwierzytelnienia jest koncepcja kont usługi.
Konta usługi różnią się od typów uwierzytelnienia 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 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 on należał do konta usługi i domyślnie nie będzie dostępny dla właściciela projektu.
Przykład interfejsu Google Natural Language API
Interfejs [Natural Language API][natural-language-api-docs] umożliwia [analizę nastawienia][sentiment-analysis-api-docs] i [analizę encji][entity-analysis-api-docs] tekstu.
Ten przykład ilustruje obliczanie [nastawienia][sentiment-api-docs] w tekście reklamy, w tym w nagłówku lub opisie. Dzięki temu można określić, jak pozytywny jest przekaz i jaki jest jego wydźwięk. Co jest lepsze: Sprzedajemy ciasta czy Sprzedajemy najlepsze ciasta w Warszawie? Kup dziś!?
Konfigurowanie skryptu
- Utwórz nowy projekt w konsoli Google Cloud.
- Włącz [Natural Language API][natural-language-api].
- Włącz płatności w projekcie.
- [Utwórz konto usługi][create-service-account]. Pobierz plik JSON z danymi logowania.
- Wklej [przykładowy skrypt][natural-language-example] do nowego skryptu w Google Ads.
- Dodatkowo wklej [przykładową bibliotekę OAuth2][oauth20-library-example] pod listą kodów.
- Zastąp niezbędne wartości:
serviceAccount: adres e-mail konta usługi, na przykładxxxxx@yyyy.iam.gserviceaccount.com.key: klucz z pliku JSON pobranego 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
JSON jest zwykle prostszy niż XML jako format odpowiedzi. Nadal jednak mogą wystąpić pewne problemy.
Weryfikacja odpowiedzi
Po otrzymaniu prawidłowej odpowiedzi z wywołania interfejsu API typowym kolejnym krokiem jest użycie funkcji JSON.parse do przekonwertowania ciągu JSON na obiekt w JavaScripcie.
W tym momencie warto obsłużyć przypadek, w którym analiza nie powiedzie się:
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, pamiętaj, że 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
XmlService umożliwia skryptom analizowanie i wyodrębnianie danych z treści odpowiedzi XML.
Walidacja
XML jest nadal popularnym formatem 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.
}
XmlService.parse wykrywa błędy w pliku XML i odpowiednio zgłasza wyjątki, ale nie umożliwia sprawdzania poprawności pliku XML względem schematu.
Element główny
Po pomyślnym przeanalizowaniu dokumentu XML element główny jest uzyskiwany za pomocą metody getRootElement():
const document = XmlService.parse(responseText);
const rootElement = document.getRootElement();
Przestrzenie nazw
W przykładzie poniżej interfejs Sportradar API służy do uzyskiwania wyników wybranych meczów piłki nożnej. Odpowiedź XML ma taki format:
<schedule_schedules xmlns="http://schemas.sportradar.com/sportsapi/soccer/v4">
<schedule>
...
</schedule>
</schedule_schedules>
Zwróć uwagę, jak przestrzeń nazw jest określona w elemencie głównym. Z tego powodu musisz:
- Wyodrębnij atrybut przestrzeni nazw z dokumentu.
- Używaj tej przestrzeni nazw podczas przeglądania elementów podrzędnych i uzyskiwania do nich dostępu.
Poniższy przykład pokazuje, jak uzyskać dostęp do elementu <schedule> i wyszukać jego elementy podrzędne <sport_event> w poprzednim fragmencie dokumentu:
const document = XmlService.parse(xmlText);
const rootElement = document.getRootElement();
// The namespace is required for accessing child elements in the schema.
const namespace = rootElement.getNamespace();
const scheduleElement = rootElement.getChild('schedule', namespace);
const sportEvents = scheduleElement.getChildren('sport_event', namespace);
Uzyskiwanie wartości
W przypadku próbki z harmonogramu meczów piłki nożnej:
<sport_event_status status="..." ... />
Atrybuty można pobrać, na przykład:
const statusElement = sportEventElement.getChild('sport_event_status', namespace);
const status = statusElement.getAttribute('status').getValue();
Tekst zawarty w elemencie można odczytać za pomocą getText(), ale jeśli element ma wiele podrzędnych elementów tekstowych, zostaną one połączone. Jeśli prawdopodobne jest wystąpienie wielu elementów podrzędnych, rozważ użycie getChildren() i iterowanie po każdym elemencie podrzędnym.
Przykład Sportradar
Ten pełny przykład Sportradar ilustruje pobieranie szczegółów meczów piłki nożnej, a konkretnie meczów angielskiej Premier League. Soccer API to jeden z wielu kanałów sportowych oferowanych przez Sportradar.
Konfigurowanie konta Sportradar
- Wejdź na stronę dla deweloperów Sportradar.
- Zarejestruj się, aby utworzyć konto próbne.
- Po zarejestrowaniu się zaloguj się na swoje konto.
- Po zalogowaniu się otwórz Moje konto.
Sportradar rozdziela różne dyscypliny sportowe na różne interfejsy API. Możesz na przykład kupić dostęp do interfejsu Soccer API, ale nie do Tennis API. Każda utworzona aplikacja może mieć powiązane różne dyscypliny sportowe i różne klucze.
- W sekcji Applications (Aplikacje) kliknij Create a new Application (Utwórz nową aplikację). Podaj nazwę i opis aplikacji, a pole witryny zignoruj.
- Wybierz tylko Issue a new key for Soccer Trial Europe v2 (Wydaj nowy klucz dla Soccer Trial Europe v2).
- Kliknij Register Application (Zarejestruj aplikację).
Jeśli wszystko się powiedzie, powinna wyświetlić się strona z nowym kluczem interfejsu API.
- Wklej przykładowy skrypt do nowego skryptu w Google Ads.
- Zastąp klucz interfejsu API na liście nowo wydanym kluczem i edytuj pole adresu e-mail.
Rozwiązywanie problemów
Podczas pracy z interfejsami API innych firm błędy mogą wystąpić z wielu powodów, na przykład:
- Klienty wysyłają żądania do serwera w formacie, którego interfejs API nie oczekuje.
- Klient oczekuje innego formatu odpowiedzi niż ten, który został napotkany.
- Klienci używają nieprawidłowych tokenów lub kluczy albo wartości pozostawionych jako obiekty zastępcze.
- Klienci osiągają limity wykorzystania.
- Klienci podający nieprawidłowe parametry.
We wszystkich tych i innych przypadkach dobrym pierwszym krokiem do ustalenia przyczyny problemu jest sprawdzenie szczegółów odpowiedzi, która powoduje błąd.
Analizowanie odpowiedzi
Domyślnie każda odpowiedź, która zwraca błąd (kod stanu 400 lub wyższy), zostanie zgłoszona przez mechanizm skryptów Google Ads.
Aby temu zapobiec i umożliwić sprawdzenie błędu i komunikatu 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 OKoznacza powodzenie. Jeśli odpowiedź nie zawiera oczekiwanych danych, weź pod uwagę, że:- Niektóre interfejsy API umożliwiają określenie, których pól lub formatu odpowiedzi (albo obu tych elementów) należy użyć. 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 dowiedzieć się, czy nie lepiej użyć innego zasobu, który zwróci wymagane dane.
- Od czasu napisania kodu interfejs API mógł się zmienić. Aby uzyskać wyjaśnienia, zapoznaj się z dokumentacją lub skontaktuj się z deweloperem.
400 Bad Requestzwykle oznacza, że coś jest nie tak z formatowaniem lub strukturą żądania wysłanego do serwera. Sprawdź żądanie i porównaj je ze specyfikacjami interfejsu API, aby upewnić się, że jest zgodne z oczekiwaniami. Szczegółowe informacje o tym, jak sprawdzać żądania, znajdziesz w artykule Sprawdzanie żądań.401 Unauthorizedzwykle oznacza, że interfejs API jest wywoływany bez podania lub pomyślnego przeprowadzenia autoryzacji.- Jeśli interfejs API używa autoryzacji podstawowej, upewnij się, że nagłówek
Authorizationjest tworzony i dostarczany w żądaniu. - Jeśli interfejs API używa protokołu OAuth 2.0, upewnij się, że token dostępu został uzyskany i jest dostarczany jako token okaziciela.
- W przypadku innych odmian autoryzacji upewnij się, że podano niezbędne dane logowania.
- Jeśli interfejs API używa autoryzacji podstawowej, upewnij się, że nagłówek
403 Forbiddenoznacza, że użytkownik nie ma uprawnień do żądanego zasobu.- Sprawdź, czy użytkownik ma niezbędne uprawnienia, na przykład dostęp do pliku w żądaniu opartym na pliku.
404 Not Foundoznacza, że żądany zasób nie istnieje.- Sprawdź, czy adres URL używany w przypadku punktu końcowego interfejsu API jest prawidłowy.
- Jeśli pobierasz zasób, sprawdź, czy zasób, do którego się odwołujesz, istnieje (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 nieprawidłowo sformułowane, np. gdy zwracany jest kod stanu 400. Aby ułatwić sprawdzanie żądań, UrlFetchApp ma metodę towarzyszącą metodzie fetch() o nazwie getRequest(url,
params).
Zamiast wysyłać żądanie do serwera, ta metoda tworzy żądanie, które zostałoby wysłane, a następnie je zwraca. Dzięki temu użytkownik może sprawdzić 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 ze sobą ciągów znaków, błąd może znajdować się w funkcji utworzonej do generowania tych danych. W najprostszym ujęciu:
const request = UrlFetchApp.getRequest(url, params);
console.log(request);
// Now make the fetch:
const response = UrlFetchApp.fetch(url, params);
// ...
umożliwi Ci sprawdzenie elementów żądania.
Loguj żądania i odpowiedzi
Aby ułatwić cały proces sprawdzania żądań i odpowiedzi do interfejsu API innej firmy, możesz użyć tej funkcji pomocniczej jako zamiennika UrlFetchApp.fetch(), aby rejestrować zarówno żądania, jak i odpowiedzi.
Zastąp wszystkie wystąpienia
UrlFetchApp.fetch()w kodzie ciągiemlogUrlFetch().Dodaj na końcu skryptu tę funkcję:
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.
[json-stringify-url]: //developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify [client-credentials-rfc]: //datatracker.ietf.org/doc/html/rfc6749#section-4.4 [authorization-code-rfc]: //datatracker.ietf.org/doc/html/rfc6749#section-1.3.1 [oauth20-library-example]: /google-ads/scripts/docs/examples/oauth20-library [search-ads-360-example]: /google-ads/scripts/docs/examples/search-ads-360 [natural-language-api]: //console.developers.google.com/apis/api/language.googleapis.com/overview [create-service-account]: //console.developers.google.com/apis/credentials/serviceaccountkey [natural-language-example]: /google-ads/scripts/docs/examples/natural-language [natural-language-api-docs]: //cloud.google.com/natural-language/docs/ [sentiment-api-docs]: //cloud.google.com/natural-language/docs/reference/rest/v1beta2/Sentiment [sentiment-analysis-api-docs]: //cloud.google.com/natural-language/docs/analyzing-sentiment [entity-analysis-api-docs]: //cloud.google.com/natural-language/docs/analyzing-entities