이 페이지는 Cloud Translation API를 통해 번역되었습니다.

타사 API

Google Ads 스크립트의 강력한 기능은 서드 파티 API의 데이터 및 서비스와 통합하는 기능입니다.

이 가이드에서는 스크립트를 작성하여 다른 서비스에 연결하는 데 도움이 되는 다음 개념을 설명합니다.

HTTP 요청 실행: UrlFetchApp를 사용하여 외부 API에 액세스하는 방법
인증: 몇 가지 일반적인 인증 시나리오를 다룹니다.
응답 파싱: 반환된 JSON 및 XML 데이터를 처리하는 방법

UrlFetchApp으로 데이터 가져오기

UrlFetchApp는 서드 파티 API와 상호작용하는 데 필요한 핵심 기능을 제공합니다.

다음 예는 OpenWeatherMap에서 날씨 데이터를 가져오는 방법을 보여줍니다. OpenWeatherMap을 선택한 이유는 승인 체계와 API가 비교적 단순하기 때문입니다.

요청하기

OpenWeatherMap 문서는 현재 날씨를 요청하기 위한 형식을 다음과 같이 지정합니다.

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

URL은 승인의 첫 번째 예를 제공합니다. apikey 매개변수는 필수이며 값은 사용자마다 고유합니다. 이 키는 가입을 통해 가져옵니다.

가입 후 다음과 같이 키를 사용하여 요청을 실행할 수 있습니다.

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

이 코드를 실행하면 Google Ads 스크립트의 로깅 창에 긴 JSON 텍스트 문자열이 작성됩니다.

다음 단계는 이를 스크립트 내에 사용할 수 있는 형식으로 변환하는 것입니다.

JSON 데이터

많은 API에서 JSON 형식으로 응답을 제공합니다. 이는 객체, 배열, 기본 유형을 문자열로 표시하고 전송할 수 있도록 자바스크립트 객체의 간단한 직렬화를 나타냅니다.

OpenWeatherMap에서 반환된 문자열과 같은 JSON 문자열을 자바스크립트 객체로 다시 변환하려면 기본 제공 JSON.parse 메서드를 사용합니다. 위의 예시를 계속 살펴보겠습니다.

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

JSON.parse 메서드는 문자열을 name 속성이 있는 객체로 변환합니다.

다양한 형식으로 API 응답을 사용하는 방법에 관한 자세한 내용은 응답 파싱 섹션을 참고하세요.

오류 처리

오류 처리는 스크립트에서 서드 파티 API로 작업할 때 중요한 고려사항입니다. 서드 파티 API는 자주 변경되며 예기치 않은 응답 값을 생성하기 때문입니다. 예를 들면 다음과 같습니다.

API의 URL 또는 매개변수는 사용자 모르게 변경될 수 있습니다.
API 키 (또는 다른 사용자 인증 정보)가 만료될 수 있습니다.
응답 형식은 예고 없이 변경될 수 있습니다.

HTTP 상태 코드

예기치 않은 응답이 발생할 가능성이 있으므로 HTTP 상태 코드를 검사해야 합니다. 기본적으로 HTTP 오류 코드가 발생하면 UrlFetchApp에서 예외가 발생합니다. 이 동작을 변경하려면 다음 예와 같이 선택적 매개변수를 전달해야 합니다.

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();
}

응답 구조

서드 파티 API가 변경될 때 개발자가 스크립트에 영향을 줄 수 있는 변경사항을 즉시 인식하지 못하는 경우가 많습니다. 예를 들어 OpenWeatherMap 예에서 반환된 name 속성이 locationName로 변경되면 이 속성을 사용하는 스크립트가 실패합니다.

따라서 반환된 구조가 예상대로인지 테스트하는 것이 좋습니다. 예를 들면 다음과 같습니다.

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

UrlFetchApp을 사용한 POST 데이터

OpenWeatherMap을 사용한 소개 예는 데이터만 가져왔습니다. 일반적으로 원격 서버에서 상태를 변경하지 않는 API 호출은 HTTP GET 메서드를 사용합니다.

GET 메서드가 UrlFetchApp의 기본값입니다. 그러나 SMS 메시지를 전송하는 서비스 호출과 같은 일부 API 호출에는 POST 또는 PUT와 같은 다른 메서드가 필요합니다.

다음 예시에서는 UrlFetchApp와 함께 POST 호출을 사용하는 방법을 보여주기 위해 공동작업 메시지 애플리케이션인 Slack과 통합하여 Slack 사용자 및 그룹에 Slack 메시지를 보내는 방법을 보여줍니다.

Slack 설정

이 가이드에서는 이미 Slack 계정에 가입했다고 가정합니다.

이전 예의 OpenWeatherMap과 마찬가지로 메시지 전송을 사용 설정하려면 토큰을 가져와야 합니다. Slack은 수신 웹훅이라고 하는 고유한 URL을 제공하여 팀에 메시지를 보낼 수 있도록 합니다.

수신 웹훅 통합 추가를 클릭하고 안내에 따라 수신 웹훅을 설정합니다. 이 프로세스에서는 메시지에 사용할 URL을 발행해야 합니다.

POST 요청

수신 웹훅을 설정한 후 POST 요청을 하려면 UrlFetchApp.fetch에 전달된 options 매개변수의 일부 추가 속성을 사용하기만 하면 됩니다.

method: 앞서 언급했듯이 기본값은 GET이지만 여기서는 재정의하고 POST로 설정합니다.

payload: POST 요청의 일부로 서버로 전송되는 데이터입니다. 이 예시에서 Slack은 Slack 문서의 설명대로 JSON 형식으로 직렬화된 객체를 예상합니다. 이를 위해 JSON.stringify 메서드를 사용하고 Content-Type를 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);

확장 Slack 예시

위의 예시는 Slack으로 수신되는 메시지를 사용 설정하기 위한 최소 기준을 보여줍니다. 확장된 샘플에서는 캠페인 실적 보고서를 만들어 그룹에 전송하는 방법과 몇 가지 형식 지정 및 표시 옵션을 보여줍니다.

수신 메시지

Slack 메시지에 대한 자세한 내용은 Slack 문서의 메시지 형식 지정을 참조하세요.

양식 데이터

위의 예는 JSON 문자열을 POST 요청의 payload 속성으로 사용하는 방법을 보여주었습니다.

UrlFetchApp는 payload 형식에 따라 POST 요청을 구성하는 데 다른 접근 방식을 사용합니다.

payload가 문자열이면 문자열 인수는 요청 본문으로 전송됩니다.
payload가 객체(예: 값의 맵)인 경우:
```
{to: 'mail@example.com', subject:'Test', body:'Hello, World!'}
```
키-값 쌍은 다음과 같이 양식 데이터로 변환됩니다.
```
subject=Test&to=mail@example.com&body=Hello,+World!
```
또한 요청의 Content-Type 헤더가 application/x-www-form-urlencoded으로 설정됩니다.

일부 API는 POST 요청을 제출할 때 양식 데이터를 사용해야 하므로 이 자바스크립트 객체에서 양식 데이터로 자동 변환이 유용합니다.

HTTP 기본 인증

HTTP 기본 인증은 가장 간단한 인증 형식 중 하나이며 여러 API에서 사용됩니다.

각 요청의 HTTP 헤더에 인코딩된 사용자 이름과 비밀번호를 첨부하여 인증을 수행합니다.

HTTP 기본 인증

요청 구성

인증된 요청을 생성하려면 다음 단계가 필요합니다.

사용자 이름과 비밀번호를 콜론으로 결합하여 암호를 만듭니다(예: username:password).
암호를 Base64로 인코딩합니다. 예를 들어 username:password는 dXNlcm5hbWU6cGFzc3dvcmQ=가 됩니다.
Authorization 헤더를 요청에 Authorization: Basic <encoded passphrase> 형식으로 첨부합니다.

다음 스니펫은 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는 API를 통해 SMS 메시지 송수신을 용이하게 하는 서비스입니다. 이 샘플은 메시지 전송을 보여줍니다.

Plivo에 등록합니다.
샘플 스크립트를 Google Ads의 새 스크립트에 붙여넣습니다.
PLIVO_ACCOUNT_AUTHID 및 PLIVO_ACCOUNT_AUTHTOKEN 값을 관리 대시보드의 값으로 바꿉니다.
오류 알림을 위해 스크립트에 지정된 대로 이메일 주소를 입력합니다.
Plivo를 사용하려면 번호를 구매하거나 체험판 계정에 추가해야 합니다. 무료 체험판 계정에 사용할 수 있는 샌드박스 번호를 추가합니다.
발신자로 표시될 번호와 수신자 번호를 모두 추가합니다.
스크립트의 PLIVO_SRC_PHONE_NUMBER를 방금 등록된 샌드박스 번호 중 하나로 업데이트합니다. 여기에는 국제 국가 코드가 포함되어야 합니다(예: 영국 전화번호의 경우 447777123456).

Twilio

Twilio는 자체 API를 통해 SMS 메시지를 보내고 받을 수 있게 해주는 또 다른 서비스입니다. 이 샘플은 메시지 전송을 보여줍니다.

Twillio에 등록합니다.
샘플 스크립트를 Google Ads의 새 스크립트에 붙여넣습니다.
TWILIO_ACCOUNT_SID 및 TWILIO_ACCOUNT_AUTHTOKEN 값을 계정 콘솔 페이지에 표시된 값으로 바꿉니다.
TWILIO_SRC_PHONE_NUMBER을 대시보드의 번호로 바꿉니다. 이 번호는 Twilio에서 메시지를 보내도록 승인한 번호입니다.

OAuth 1.0

널리 사용되는 다수의 서비스에서 인증에 OAuth를 사용합니다. OAuth는 다양한 버전과 버전으로 제공됩니다.

HTTP 기본 인증에서 사용자는 사용자 이름과 비밀번호를 하나만 갖는 반면, OAuth를 사용하면 타사 애플리케이션에 특화된 사용자 인증 정보를 사용하여 해당 사용자의 계정과 데이터에 대한 액세스 권한을 타사 애플리케이션에 부여할 수 있습니다. 또한 액세스 범위는 해당 애플리케이션에 따라 다릅니다.

OAuth 1.0에 관한 배경 정보는 OAuth 핵심 가이드를 참고하세요. 특히 6. OAuth를 사용하여 인증을 참조하세요. 전체 three-legged OAuth 1.0에서 이 프로세스는 다음과 같습니다.

애플리케이션 ('소비자')이 요청 토큰을 얻습니다.
사용자가 요청 토큰을 승인합니다.
애플리케이션은 요청 토큰을 액세스 토큰으로 교환합니다.
모든 후속 리소스 요청의 경우 서명된 요청에 액세스 토큰이 사용됩니다.

서드 파티 서비스에서 사용자 상호작용 없이 (예: Google Ads 스크립트에서 요구하는 경우) OAuth 1.0을 사용하려면 1,2, 3단계가 불가능합니다. 따라서 일부 서비스는 구성 콘솔에서 액세스 토큰을 발행하여 애플리케이션이 4단계로 바로 이동할 수 있게 합니다. 이를 one-legged OAuth 1.0이라고 합니다.

OAuth1

Google Ads 스크립트의 OAuth 1.0

Google Ads 스크립트에서 각 스크립트는 일반적으로 애플리케이션으로 해석됩니다. 서비스의 콘솔/관리 설정 페이지에서 일반적으로 다음 작업을 수행해야 합니다.

스크립트를 나타내도록 애플리케이션 구성을 설정합니다.
스크립트로 확장되는 권한을 지정합니다.
one-legged OAuth와 함께 사용할 고객 키, 고객 비밀번호, 액세스 토큰, 액세스 비밀번호를 가져옵니다.

OAuth 2.0

OAuth 2.0은 널리 사용되는 API에서 사용자 데이터에 대한 액세스를 제공하는 데 사용됩니다. 특정 서드 파티 서비스의 계정 소유자는 특정 애플리케이션이 사용자 데이터에 액세스할 수 있도록 권한을 부여합니다. 장점은 다음과 같습니다.

계정 사용자 인증 정보를 애플리케이션과 공유할 필요가 없습니다.
데이터에 개별적으로 액세스할 수 있는 애플리케이션과 그 범위를 제어할 수 있습니다. 예를 들어 부여된 액세스 권한은 읽기 전용이거나 데이터의 하위 집합에만 적용될 수 있습니다.

Google Ads 스크립트에서 OAuth 2.0 지원 서비스를 사용하려면 다음 단계를 따르세요.

스크립트 외부

Google Ads 스크립트에서 서드 파티 API를 통해 사용자 데이터에 액세스할 수 있도록 권한을 부여합니다. 대부분의 경우 서드 파티 서비스의 콘솔에서 애플리케이션을 설정해야 합니다. 이 애플리케이션은 Google Ads 스크립트를 나타냅니다.

Google Ads 스크립트 애플리케이션에 부여해야 하는 액세스 권한을 지정하면 일반적으로 클라이언트 ID가 할당됩니다. 이렇게 하면 OAuth 2를 통해 서드 파티 서비스의 데이터에 액세스할 수 있는 애플리케이션과 해당 데이터가 보거나 수정할 수 있는 부분을 제어할 수 있습니다.

스크립트 내

원격 서버로 승인합니다. 서버에서 허용한 권한 유형에 따라 흐름이라고 하는 다른 단계 집합을 따라야 하지만 궁극적으로 모든 후속 요청에서 해당 세션에 사용되는 액세스 토큰이 발급됩니다.

API 요청하기 각 요청과 함께 액세스 토큰을 전달합니다.

승인 흐름

각 지원금 유형과 상응하는 흐름은 다양한 사용 시나리오에 맞게 조정됩니다. 예를 들어 사용자가 상호작용하지 않은 상태에서 애플리케이션을 백그라운드로 실행해야 하는 시나리오와 달리 사용자가 대화형 세션에 참여할 때는 다른 흐름이 사용됩니다.

API 제공업체에서 허용하는 권한 유형을 결정하며, 이 내용에 따라 사용자가 API 통합을 진행하는 방법이 안내됩니다.

구현

서로 다른 모든 OAuth 흐름의 목표는 액세스 토큰을 얻은 다음 세션의 나머지 부분에서 요청을 인증하는 데 사용할 수 있는 것입니다.

샘플 라이브러리는 서로 다른 흐름 유형마다 인증하는 방법을 보여줍니다. 이러한 각 메서드는 액세스 토큰을 가져와서 저장하고 인증된 요청을 처리하는 객체를 반환합니다.

일반적인 사용 패턴은 다음과 같습니다.

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

클라이언트 사용자 인증 정보 부여

클라이언트 사용자 인증 정보 부여는 OAuth2 흐름의 간단한 형식 중 하나로, 애플리케이션에서 시간 제한이 있는 액세스 토큰을 발급하는 대가로 애플리케이션 고유의 ID와 보안 비밀을 교환합니다.

클라이언트 사용자 인증 정보

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

갱신 토큰 부여

갱신 토큰 부여는 서버에 대한 간단한 요청이 세션에서 사용할 수 있는 액세스 토큰을 반환한다는 점에서 클라이언트 사용자 인증 정보 부여와 유사합니다.

갱신 토큰

갱신 토큰 가져오기

갱신 토큰 부여와의 차이점은 클라이언트 사용자 인증 정보 부여에 필요한 세부정보는 애플리케이션 구성(예: 서비스의 제어판)에서 가져오는 반면 갱신 토큰은 사용자 상호작용이 필요한 승인 코드 부여와 같은 더 복잡한 흐름의 일부로 부여된다는 점입니다.

승인 코드

OAuth 플레이그라운드를 사용하여 갱신 토큰 가져오기

OAuth2 플레이그라운드는 사용자가 승인 코드 부여를 단계별로 진행하여 갱신 토큰을 얻을 수 있는 UI를 제공합니다.

오른쪽 상단의 설정 버튼을 사용하면 다음을 비롯하여 OAuth 흐름에 사용할 모든 매개변수를 정의할 수 있습니다.

승인 엔드포인트: 승인 흐름의 시작으로 사용됩니다.
토큰 엔드포인트: 액세스 토큰을 가져오기 위해 갱신 토큰과 함께 사용됩니다.
client ID andsecret: 애플리케이션의 사용자 인증 정보입니다.

OAuth 플레이그라운드

스크립트를 사용하여 갱신 토큰 가져오기

흐름을 완료하기 위한 스크립트 기반의 대안은 갱신 토큰 생성 샘플에서 사용할 수 있습니다.

갱신 토큰 사용량

초기 승인이 수행되면 서비스에서 갱신 토큰을 발행하여 클라이언트 사용자 인증 정보 흐름과 비슷한 방식으로 사용할 수 있습니다. 아래에 두 가지 예가 나와 있습니다.

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

Search Ads 360 예

Search Ads 360은 갱신 토큰과 함께 사용할 수 있는 API의 예입니다. 이 샘플에서는 스크립트가 보고서를 생성하고 반환합니다. 수행 가능한 다른 작업에 대한 자세한 내용은 Search Ads 360 API 참조를 확인하세요.

스크립트 만들기

API 콘솔에서 새 프로젝트를 만든 후 DoubleClick 가이드의 절차에 따라 DoubleClick Search API를 사용 설정하여 클라이언트 ID, 클라이언트 보안 비밀번호, 갱신 토큰을 가져옵니다.
Google Ads의 새 스크립트에 샘플 스크립트를 붙여넣습니다.
코드 목록 아래에 샘플 OAuth2 라이브러리를 붙여넣습니다.
클라이언트 ID, 클라이언트 보안 비밀번호, 갱신 토큰의 올바른 값을 포함하도록 스크립트를 수정합니다.

Apps Script Execution API 예

이 예에서는 Apps Script Execution API를 사용하여 Apps Script에서 함수를 실행하는 방법을 보여줍니다. 이렇게 하면 Google Ads 스크립트에서 Apps Script를 호출할 수 있습니다.

Apps Script 스크립트 만들기

새 스크립트를 만듭니다. 다음 샘플에는 Drive에 있는 파일 10개가 나열됩니다.

function listFiles() {
  const limit = 10;
  const files = [];
  const fileIterator = DriveApp.getFiles();
  while (fileIterator.hasNext() && limit) {
    files.push(fileIterator.next().getName());
    limit--;
  }
  return files;
}

실행을 위해 Apps Script 구성

스크립트를 저장합니다.
리소스 > Cloud Platform 프로젝트를 클릭합니다.
프로젝트 이름을 클릭하여 API 콘솔로 이동합니다.
API 및 서비스로 이동합니다.
적절한 API를 사용 설정합니다. 이 경우 Drive API 및 Apps Script Execution API를 사용 설정합니다.
메뉴의 사용자 인증 정보 항목에서 OAuth 사용자 인증 정보를 만듭니다.
스크립트로 다시 게시 > API 실행 파일로 배포에서 실행할 스크립트를 게시합니다.

Google Ads 스크립트 만들기

Google Ads의 새 스크립트에 샘플 스크립트를 붙여넣습니다.
또한 코드 목록 아래에 샘플 OAuth2 라이브러리를 붙여넣습니다.
클라이언트 ID, 클라이언트 보안 비밀번호, 갱신 토큰의 올바른 값을 포함하도록 스크립트를 수정합니다.

서비스 계정

위의 권한 부여 유형 대신 서비스 계정 개념을 사용할 수 있습니다.

서비스 계정은 사용자 데이터에 액세스하는 데 사용되지 않는다는 점에서 위와 다릅니다. 인증 후에는 프로젝트를 소유할 수 있는 사용자가 아니라 애플리케이션을 대신하여 서비스 계정에서 요청을 수행합니다. 예를 들어 서비스 계정이 Drive API를 사용하여 파일을 만드는 경우 이 계정은 서비스 계정에 속하며 기본적으로 프로젝트 소유자는 액세스할 수 없습니다.

Google Natural Language API 예시

Natural Language API는 텍스트의 감정 분석 및 항목 분석을 제공합니다.

이 예는 광고 제목 또는 설명을 비롯한 광고문안의 감정을 계산하는 방법을 보여줍니다. 이를 통해 메시지의 긍정적인 정도와 메시지의 규모를 측정할 수 있습니다. 저희는 케이크를 판매합니다. 또는 런던에서 제일 좋은 케이크를 판매합니다. 지금 구매

스크립트 설정

API 콘솔에서 새 프로젝트 만들기
Natural Language API를 사용 설정합니다.
프로젝트에 결제를 사용 설정합니다.
서비스 계정을 만듭니다. 사용자 인증 정보 JSON 파일을 다운로드합니다.
Google Ads의 새 스크립트에 샘플 스크립트를 붙여넣습니다.
또한 코드 목록 아래에 샘플 OAuth2 라이브러리를 붙여넣습니다.
다음과 같이 필요한 값을 바꿉니다.
- serviceAccount: 서비스 계정의 이메일 주소입니다(예: xxxxx@yyyy.iam.gserviceaccount.com).
- key: 서비스 계정을 만들 때 다운로드한 JSON 파일의 키입니다. -----BEGIN PRIVATE KEY...에 시작되어 ...END PRIVATE KEY-----\n에 종료됩니다.

API 응답

API는 다양한 형식의 데이터를 반환할 수 있습니다. 가장 주목할 만한 것은 XML과 JSON입니다.

JSON

JSON은 일반적으로 XML보다 더 간단하게 응답 형식으로 사용할 수 있습니다. 하지만 발생할 수 있는 몇 가지 문제가 있습니다.

응답 확인

API 호출에서 성공적인 응답을 얻은 다음 일반적인 단계는 JSON.parse을 사용하여 JSON 문자열을 자바스크립트 객체로 변환하는 것입니다. 이 시점에서는 파싱이 실패한 경우를 처리하는 것이 좋습니다.

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

또한 API를 제어할 수 없는 경우 응답의 구조가 변경될 수 있으며 속성이 더 이상 존재하지 않을 수 있습니다.

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

유효성 검사

XML은 여전히 API 빌드에 널리 사용되는 형식입니다. API 호출의 응답은 XmlService parse 메서드를 사용하여 파싱할 수 있습니다.

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

XmlService.parse는 XML의 오류를 감지하고 그에 따라 예외를 발생시키지만 스키마를 기준으로 XML의 유효성을 검사하는 기능은 제공하지 않습니다.

루트 요소

XML 문서가 성공적으로 파싱되면 getRootElement() 메서드를 사용하여 루트 요소를 가져옵니다.

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

네임스페이스

다음 예에서는 선택한 경기의 축구 결과를 얻기 위해 Sportradar API가 사용됩니다. XML 응답의 형식은 다음과 같습니다.

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

루트 요소에 네임스페이스가 어떻게 지정되는지 확인하세요. 따라서 다음과 같은 작업이 필요합니다.

문서에서 네임스페이스 속성을 추출합니다.
하위 요소를 순회하고 액세스할 때 이 네임스페이스를 사용합니다.

다음 샘플은 위 문서 스니펫에서 <matches> 요소에 액세스하는 방법을 보여줍니다.

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

값 가져오기

축구 일정 샘플을 사용할 경우:

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

다음과 같은 속성을 가져올 수 있습니다.

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

요소 내에 포함된 텍스트는 getText()를 사용하여 읽을 수 있지만 요소의 텍스트 하위 요소가 여러 개 있는 경우 연결됩니다. 텍스트 하위 요소가 여러 개 있을 가능성이 있는 경우 getChildren()를 사용하고 각 하위 요소를 반복하는 것이 좋습니다.

Sportradar 예

전체 Sportradar 예제는 축구 경기, 특히 영국 프리미어 리그 경기의 세부정보를 가져오는 방법을 보여줍니다. Soccer API는 Sportradar에서 제공하는 광범위한 스포츠 피드 중 하나입니다.

Sportradar 계정 설정

Sportradar 개발자 사이트로 이동합니다.
체험판 계정을 등록합니다.
등록이 완료되면 계정에 로그인합니다.
로그인한 후 MyAccount으로 이동합니다.

Sportradar는 여러 스포츠를 여러 API로 분리합니다. 예를 들어 Soccer API에 대한 액세스 권한은 구매하지만 Tennis API에 대한 액세스 권한은 구매할 수 없습니다. 만드는 각 애플리케이션에는 다양한 스포츠와 연결된 키가 있을 수 있습니다.

애플리케이션에서 새 애플리케이션 만들기를 클릭합니다. 애플리케이션에 이름과 설명을 지정하고 웹사이트 필드는 무시합니다.
Sccer Trial Europe v2의 새 키 발급만 선택합니다.
애플리케이션 등록을 클릭합니다.

성공하면 새 API 키가 포함된 페이지가 표시됩니다.

샘플 스크립트를 Google Ads의 새 스크립트에 붙여넣습니다.
등록정보의 API 키를 위에서 가져온 키로 바꾸고 이메일 주소 필드를 수정합니다.

문제 해결

서드 파티 API를 사용하면 다음과 같은 여러 가지 이유로 오류가 발생할 수 있습니다.

클라이언트가 API에서 예상하지 않는 형식으로 서버에 요청을 발행합니다.
클라이언트가 표시된 것과 다른 응답 형식을 기대합니다.
클라이언트가 잘못된 토큰이나 키 또는 자리표시자로 남겨진 값을 사용함
클라이언트가 사용량 한도에 도달합니다.
클라이언트가 잘못된 매개변수를 제공합니다.

이러한 모든 사례 및 기타 상황에서 문제 원인을 파악하기 위한 좋은 첫 단계는 오류를 일으킨 응답의 세부정보를 검토하는 것입니다.

응답 파싱

기본적으로 오류 (상태 코드 400 이상)를 반환하는 모든 응답은 Google Ads 스크립트 엔진에서 발생합니다.

이러한 동작을 방지하고 오류 및 오류 메시지를 검사하려면 선택적 매개변수의 muteHttpExceptions 속성을 UrlFetchApp.fetch로 설정합니다. 예를 들면 다음과 같습니다.

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

일반 상태 코드

200 OK은 성공을 나타냅니다. 응답에 예상 데이터가 포함되지 않은 경우 다음을 고려하세요.
- 일부 API에서는 사용할 필드 또는 응답 형식을 지정할 수 있습니다. 자세한 내용은 API 문서를 확인하세요.
- API에는 호출할 수 있는 리소스가 여러 개 있을 수 있습니다. 문서를 참조하여 다른 리소스를 사용하는 것이 더 적합한지 확인하고 필요한 데이터를 반환합니다.
- 코드가 작성된 이후 API가 변경되었을 수 있습니다. 자세한 내용은 문서 또는 개발자에게 문의하세요.
400 Bad Request는 일반적으로 서버에 전송되는 요청의 형식이나 구조가 잘못된 것을 의미합니다. 요청을 검사하고 API 사양과 비교하여 기대치를 충족하는지 확인합니다. 요청을 검토하는 방법에 관한 자세한 내용은 요청 검사를 참고하세요.
401 Unauthorized는 일반적으로 승인 제공이나 성공 없이 API가 호출됨을 의미합니다.
- API에서 기본 승인을 사용하는 경우 Authorization 헤더가 구성되어 요청에 제공되는지 확인합니다.
- API가 OAuth 2.0을 사용하는 경우 액세스 토큰을 가져와 Bearer 토큰으로 제공하고 있는지 확인합니다.
- 다른 승인 변형의 경우 요청에 필요한 사용자 인증 정보가 제공되었는지 확인합니다.
403 Forbidden은 요청된 리소스에 대한 권한이 사용자에게 없음을 나타냅니다.
- 사용자에게 필요한 권한을 부여했는지 확인합니다(예: 파일 기반 요청으로 파일에 대한 액세스 권한 부여).
404 Not Found는 요청된 리소스가 없음을 의미합니다.
- API 엔드포인트에 사용된 URL이 올바른지 확인하세요.
- 리소스를 가져오는 경우 참조되는 리소스가 있는지 확인합니다(예: 파일 기반 API에 파일이 있는 경우).

검사 요청

요청 검사는 API 응답이 요청 형식이 잘못되었음을 나타낼 때 유용합니다(예: 400 상태 코드). 요청을 검토하는 데 도움이 되도록 UrlFetchApp에는 getRequest()이라는 fetch() 메서드의 컴패니언 메서드가 있습니다.

이 메서드는 서버에 요청을 전송하는 대신 전송되었을 요청을 생성하고 반환합니다. 이를 통해 사용자는 요청의 요소를 검사하여 요청이 올바르게 표시되는지 확인할 수 있습니다.

예를 들어 요청의 양식 데이터가 서로 연결된 여러 문자열로 구성된 경우, 해당 양식 데이터를 생성하기 위해 만든 함수에 오류가 있을 수 있습니다. 가장 간단한 방법은 다음과 같습니다.

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

요청의 요소를 검사할 수 있습니다.

요청 및 응답 로깅

서드 파티 API에 대한 요청 및 응답을 검사하는 전체 프로세스를 지원하기 위해 다음 도우미 함수를 UrlFetchApp.fetch()의 드롭인 대체로 사용하여 요청과 응답을 모두 로깅할 수 있습니다.

코드의 모든 UrlFetchApp.fetch() 인스턴스를 logUrlFetch()로 바꿉니다.

스크립트 끝에 다음 함수를 추가합니다.

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;
}

스크립트를 실행할 때 모든 요청과 응답의 세부정보가 콘솔에 로깅되므로 더 쉽게 디버깅할 수 있습니다.