API của bên thứ ba

Một tính năng mạnh mẽ của tập lệnh Google Ads là khả năng tích hợp với dữ liệu và dịch vụ từ các API của bên thứ ba.

Hướng dẫn này đề cập đến các khái niệm sau có thể giúp bạn viết tập lệnh để kết nối với các dịch vụ khác:

  • Tạo yêu cầu HTTP: Cách sử dụng UrlFetchApp để truy cập vào các API bên ngoài.
  • Xác thực: Chúng tôi đề cập đến một số trường hợp xác thực phổ biến.
  • Phân tích cú pháp phản hồi: Cách xử lý dữ liệu JSON và XML được trả về.

Tìm nạp dữ liệu bằng UrlFetchApp

UrlFetchApp cung cấp chức năng cốt lõi cần thiết để tương tác với các API của bên thứ ba.

Ví dụ sau cho thấy quá trình tìm nạp dữ liệu thời tiết từ OpenWeatherMap. Chúng tôi đã chọn OpenWeatherMap do API và lược đồ uỷ quyền tương đối đơn giản.

Tạo yêu cầu

Tài liệu OpenWeatherMap chỉ định định dạng yêu cầu thời tiết hiện tại như sau:

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

URL cung cấp ví dụ đầu tiên về việc uỷ quyền: Tham số apikey là bắt buộc và giá trị là duy nhất cho mỗi người dùng. Bạn có thể lấy khoá này bằng cách đăng ký.

Sau khi đăng ký, bạn có thể gửi yêu cầu sử dụng khoá như sau:

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

Việc thực thi mã này sẽ dẫn đến một chuỗi dài của văn bản JSON được ghi vào cửa sổ ghi nhật ký trong tập lệnh Google Ads.

Bước tiếp theo là chuyển đổi sang một định dạng có thể sử dụng được trong tập lệnh của bạn.

Dữ liệu JSON

Nhiều API cung cấp phản hồi ở định dạng JSON. Điều này thể hiện một quá trình chuyển đổi tuần tự đơn giản các đối tượng JavaScript, chẳng hạn như các đối tượng, mảng và loại cơ bản có thể được biểu thị và chuyển dưới dạng chuỗi.

Để chuyển đổi chuỗi JSON (như chuỗi được trả về từ OpenWeatherMap) thành đối tượng JavaScript, hãy sử dụng phương thức JSON.parse tích hợp sẵn. Tiếp tục từ ví dụ trên:

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

Phương thức JSON.parse chuyển đổi chuỗi thành một đối tượng, có thuộc tính name.

Vui lòng xem phần Phân tích cú pháp phản hồi để biết thêm thông tin chi tiết về cách làm việc với các phản hồi API ở nhiều định dạng.

Xử lý lỗi

Bạn cần cân nhắc xử lý lỗi khi làm việc với API của bên thứ ba trong tập lệnh vì API của bên thứ ba thường thay đổi thường xuyên và tạo ra các giá trị phản hồi không mong muốn, chẳng hạn như:

  • URL hoặc thông số cho API có thể thay đổi mà bạn không biết.
  • Khoá API (hoặc thông tin xác thực khác của người dùng) có thể hết hạn.
  • Định dạng của phản hồi có thể thay đổi mà không có thông báo.

Mã trạng thái HTTP

Do có thể xảy ra phản hồi không mong muốn, bạn nên kiểm tra mã trạng thái HTTP. Theo mặc định, UrlFetchApp sẽ gửi một ngoại lệ nếu gặp mã lỗi HTTP. Để thay đổi hành vi này, bạn cần phải truyền một tham số không bắt buộc, như trong ví dụ sau:

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

Cấu trúc phản hồi

Khi API của bên thứ ba thay đổi, nhà phát triển thường không nhận biết ngay được những thay đổi có thể ảnh hưởng đến tập lệnh của họ. Ví dụ: nếu thuộc tính name được trả về trong ví dụ về OpenWeatherMap được thay đổi thành locationName, thì các tập lệnh sử dụng thuộc tính này sẽ không thành công.

Vì lý do này, bạn nên kiểm thử xem cấu trúc được trả về có đúng như dự kiến hay không, chẳng hạn như:

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

POST dữ liệu bằng UrlFetchApp

Ví dụ giới thiệu với dữ liệu chỉ được tìm nạp của OpenWeatherMap. Thông thường, các lệnh gọi API không thay đổi trạng thái tại máy chủ từ xa sẽ sử dụng phương thức HTTP GET.

Phương thức GET là phương thức mặc định cho UrlFetchApp. Tuy nhiên, một số lệnh gọi API, chẳng hạn như lệnh gọi đến một dịch vụ gửi tin nhắn SMS, sẽ yêu cầu các phương thức khác, chẳng hạn như POST hoặc PUT.

Để minh hoạ việc sử dụng các lệnh gọi POST bằng UrlFetchApp, ví dụ sau đây minh hoạ việc tích hợp với Slack (một ứng dụng nhắn tin cộng tác) để gửi tin nhắn Slack cho các nhóm và người dùng Slack.

Thiết lập Slack

Hướng dẫn này giả định rằng bạn đã đăng ký tài khoản Slack.

Giống như OpenWeatherMap trong ví dụ trước, bạn cần lấy mã thông báo để cho phép gửi thông báo. Slack cung cấp một URL duy nhất cho phép bạn gửi tin nhắn cho nhóm của mình, gọi là Webhook đến.

Thiết lập Webhook đến bằng cách nhấp vào Thêm tích hợp WebHooks đến rồi làm theo hướng dẫn. Quy trình này sẽ cấp một URL để sử dụng cho thông báo.

Tạo yêu cầu POST

Sau khi thiết lập Webhook đến, việc thực hiện yêu cầu POST chỉ yêu cầu sử dụng một số thuộc tính bổ sung trong thông số options được truyền tới UrlFetchApp.fetch:

  • method: Như đã đề cập, phương thức này mặc định là GET, nhưng ở đây chúng ta đã ghi đè và đặt giá trị này thành POST.

  • payload: Đây là dữ liệu sẽ được gửi đến máy chủ theo yêu cầu POST. Trong ví dụ này, Slack dự kiến rằng một đối tượng được chuyển đổi tuần tự sang định dạng JSON như mô tả trong tài liệu về Slack. Để làm được điều này, phương thức JSON.stringify sẽ được sử dụng và Content-Type được đặt thành 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);

Ví dụ về Slack mở rộng

Ví dụ trên cho thấy mức tối thiểu để có thể gửi tin nhắn đến vào Slack. Mẫu mở rộng minh hoạ việc tạo và gửi Báo cáo hiệu suất chiến dịch đến một nhóm, cũng như một số tuỳ chọn định dạng và hiển thị.

Tin nhắn đến

Vui lòng xem phần định dạng tin nhắn trong tài liệu về Slack để biết thêm thông tin chi tiết về các thông báo trên Slack.

Dữ liệu biểu mẫu

Ví dụ trên được minh hoạ bằng cách sử dụng chuỗi JSON làm thuộc tính payload cho yêu cầu POST.

Tuỳ thuộc vào định dạng của payload, UrlFetchApp sẽ thực hiện nhiều phương pháp để tạo yêu cầu POST:

  • Khi payload là một chuỗi, đối số chuỗi sẽ được gửi dưới dạng phần nội dung của yêu cầu.

  • Khi payload là một đối tượng, chẳng hạn như bản đồ các giá trị:

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

    Cặp khoá/giá trị được chuyển đổi thành dữ liệu biểu mẫu:

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

    Ngoài ra, tiêu đề Content-Type cho yêu cầu được đặt thành application/x-www-form-urlencoded.

Một số API đòi hỏi sử dụng dữ liệu biểu mẫu khi gửi yêu cầu POST, vì vậy, bạn cần lưu ý việc chuyển đổi tự động từ các đối tượng JavaScript sang dữ liệu biểu mẫu.

Xác thực HTTP cơ bản

Xác thực cơ bản HTTP là một trong những hình thức xác thực đơn giản nhất và được nhiều API sử dụng.

Xác thực đạt được bằng cách đính kèm tên người dùng và mật khẩu được mã hoá vào tiêu đề HTTP trong mỗi yêu cầu.

Xác thực HTTP cơ bản

Xây dựng yêu cầu

Bạn cần thực hiện các bước sau để tạo yêu cầu đã xác thực:

  1. Tạo cụm mật khẩu bằng cách kết hợp tên người dùng và mật khẩu bằng dấu hai chấm, ví dụ: username:password.
  2. Mã hoá cụm mật khẩu Base64, ví dụ: username:password trở thành dXNlcm5hbWU6cGFzc3dvcmQ=.
  3. Đính kèm tiêu đề Authorization vào yêu cầu, trong biểu mẫu Authorization: Basic <encoded passphrase>

Đoạn mã sau minh hoạ cách đạt được điều này trong Tập lệnh 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 là một dịch vụ hỗ trợ việc gửi và nhận tin nhắn SMS thông qua API. Mẫu này minh hoạ cách gửi thông báo.

  1. Đăng ký với Plivo.
  2. Dán tập lệnh mẫu vào tập lệnh mới trong Google Ads.
  3. Thay thế giá trị PLIVO_ACCOUNT_AUTHID và PLIVO_ACCOUNT_AUTHTOKEN bằng các giá trị trên trang tổng quan quản lý.
  4. Chèn địa chỉ email của bạn như được chỉ định trong tập lệnh để thông báo lỗi.
  5. Để sử dụng Plivo, bạn phải mua số hoặc thêm số vào tài khoản dùng thử. Thêm số Hộp cát có thể dùng với tài khoản dùng thử.
  6. Thêm cả số sẽ hiển thị với tư cách là người gửi và số người nhận.
  7. Cập nhật PLIVO_SRC_PHONE_NUMBER trong tập lệnh thành một trong các số hộp cát vừa đăng ký. Trong đó phải bao gồm mã quốc gia quốc tế, ví dụ: 447777123456 cho một số điện thoại của Vương quốc Anh.

Twilio

Twilio là một dịch vụ khác hỗ trợ việc gửi và nhận tin nhắn SMS thông qua API. Mẫu này minh hoạ cách gửi thông báo.

  1. Đăng ký với Twillio.
  2. Dán tập lệnh mẫu vào tập lệnh mới trong Google Ads.
  3. Thay thế các giá trị TWILIO_ACCOUNT_SID và TWILIO_ACCOUNT_AUTHTOKEN bằng các giá trị xuất hiện trên trang bảng điều khiển tài khoản.
  4. Thay thế TWILIO_SRC_PHONE_NUMBER bằng số trên trang tổng quan – đây là số được Twilio uỷ quyền để gửi tin nhắn.

OAuth 1.0

Nhiều dịch vụ phổ biến sử dụng OAuth để xác thực. OAuth có nhiều phiên bản và phiên bản.

Trong khi với phương thức xác thực cơ bản HTTP, người dùng chỉ có một tên người dùng và mật khẩu, OAuth cho phép các ứng dụng bên thứ ba cấp quyền truy cập vào tài khoản và dữ liệu của người dùng bằng cách sử dụng thông tin xác thực dành riêng cho ứng dụng bên thứ ba đó. Ngoài ra, phạm vi truy cập cũng sẽ tuỳ thuộc vào ứng dụng đó.

Để biết chế độ nền trên OAuth 1.0, hãy xem Hướng dẫn về OAuth Core. Cụ thể, hãy xem 6. Xác thực bằng OAuth. Ở phiên bản 3 bên hoàn toàn, OAuth 1.0, quy trình sẽ diễn ra như sau:

  1. Ứng dụng ("Người tiêu dùng") nhận mã thông báo yêu cầu.
  2. Người dùng cho phép mã thông báo yêu cầu.
  3. Ứng dụng sẽ trao đổi mã thông báo yêu cầu để lấy mã truy cập.
  4. Đối với tất cả các yêu cầu về tài nguyên tiếp theo, mã truy cập được dùng trong yêu cầu đã ký.

Để các dịch vụ của bên thứ ba sử dụng OAuth 1.0 mà không cần sự tương tác của người dùng (ví dụ: như tập lệnh Google Ads yêu cầu) thì bạn không thể thực hiện các bước 1, 2 và 3. Do đó, một số dịch vụ cấp mã truy cập qua bảng điều khiển cấu hình, cho phép ứng dụng chuyển thẳng đến bước 4. Đây được gọi là OAuth 1.0 một chân.

OAuth1

OAuth 1.0 trong tập lệnh Google Ads

Đối với tập lệnh Google Ads, mỗi tập lệnh thường được hiểu là một ứng dụng. Thông qua trang cài đặt bảng điều khiển/quản trị cho dịch vụ, thông thường, bạn cần:

  • Thiết lập cấu hình ứng dụng để biểu thị tập lệnh.
  • Chỉ định những quyền nào đang được mở rộng đối với tập lệnh.
  • Lấy Khoá người dùng, Thông tin bí mật của người dùng, mã truy cập và thông tin bí mật truy cập để sử dụng với OAuth một bên.

OAuth 2.0

OAuth 2.0 được dùng trong các API phổ biến để cung cấp quyền truy cập vào dữ liệu người dùng. Chủ sở hữu tài khoản của một dịch vụ bên thứ ba cụ thể sẽ cấp quyền truy cập vào dữ liệu người dùng cho các ứng dụng cụ thể. Nhược điểm là chủ sở hữu:

  • Không cần phải chia sẻ thông tin đăng nhập tài khoản của họ với ứng dụng.
  • Có thể kiểm soát các ứng dụng có quyền truy cập vào từng dữ liệu và mức độ phù hợp. (Ví dụ: quyền truy cập được cấp có thể là quyền chỉ đọc hoặc chỉ cho một tập hợp con của dữ liệu.)

Để sử dụng các dịch vụ có hỗ trợ OAuth 2.0 trong tập lệnh Google Ads, bạn cần thực hiện một số bước sau:

Bên ngoài tập lệnh của bạn

Cấp quyền cho Tập lệnh Google Ads truy cập vào dữ liệu người dùng của bạn thông qua API bên thứ ba. Trong hầu hết các trường hợp, bạn sẽ phải thiết lập một ứng dụng trong bảng điều khiển của dịch vụ bên thứ ba. Ứng dụng này đại diện cho Tập lệnh Google Ads của bạn.

Bạn chỉ định quyền truy cập nào mà ứng dụng Google Ads Script sẽ được cấp và thường sẽ được gán một mã ứng dụng khách. Điều này cho phép bạn thông qua OAuth 2 để kiểm soát các ứng dụng nào có quyền truy cập vào dữ liệu của bạn trong dịch vụ bên thứ ba, cũng như các khía cạnh của dữ liệu mà họ có thể xem hoặc sửa đổi.

Trong tập lệnh của bạn

Uỷ quyền bằng máy chủ từ xa. Tuỳ thuộc vào loại cấp mà máy chủ cho phép, bạn sẽ cần thực hiện một loạt các bước khác nhau, còn gọi là luồng, nhưng cuối cùng tất cả sẽ dẫn đến việc một mã truy cập được cấp và dùng cho phiên đó cho tất cả các yêu cầu tiếp theo.

Tạo yêu cầu API. Truyền mã truy cập với mỗi yêu cầu.

Quy trình uỷ quyền

Mỗi loại tài trợ và quy trình tương ứng phục vụ cho các trường hợp sử dụng khác nhau. Ví dụ: một luồng khác được sử dụng khi người dùng đang tham gia vào một phiên tương tác, trái ngược với trường hợp ứng dụng phải chạy ở chế độ nền mà không có người dùng ở đó.

Nhà cung cấp API sẽ quyết định loại cấp quyền mà họ chấp nhận và điều này sẽ hướng dẫn người dùng tiến hành tích hợp API của họ như thế nào.

Triển khai

Đối với tất cả các luồng OAuth khác nhau, mục đích là lấy mã truy cập mà sau đó có thể dùng cho phần còn lại của phiên để xác thực yêu cầu.

Thư viện mẫu minh hoạ cách xác thực cho từng loại luồng. Mỗi phương thức này sẽ trả về một đối tượng lấy và lưu trữ mã truy cập, đồng thời hỗ trợ các yêu cầu đã xác thực.

Cách sử dụng chung là:

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

Cấp thông tin đăng nhập của ứng dụng

Cấp thông tin đăng nhập của ứng dụng là một trong những hình thức đơn giản hơn của quy trình OAuth2, trong đó ứng dụng trao đổi một mã nhận dạng và mã thông tin bí mật dành riêng cho ứng dụng để đổi lấy việc cấp mã truy cập có giới hạn thời gian.

Thông tin xác thực ứng dụng

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

Làm mới mã thông báo

Việc cấp mã thông báo làm mới tương tự như việc cấp thông tin đăng nhập ứng dụng, vì một yêu cầu đơn giản đến máy chủ sẽ trả về một mã truy cập có thể dùng được trong phiên.

Làm mới mã thông báo

Nhận mã làm mới

Điểm khác biệt với việc cấp mã làm mới là mặc dù thông tin chi tiết cần thiết cho việc cấp thông tin đăng nhập ứng dụng đến từ cấu hình ứng dụng (ví dụ: trong bảng điều khiển của dịch vụ), mã làm mới được cấp trong một quy trình phức tạp hơn, chẳng hạn như cấp mã uỷ quyền để yêu cầu người dùng tương tác:

Mã uỷ quyền

Sử dụng OAuth Playground để lấy mã làm mới

OAuth2 Playground cung cấp một giao diện người dùng cho phép người dùng thực hiện bước cấp mã uỷ quyền để lấy mã làm mới.

Nút cài đặt ở trên cùng bên phải cho phép bạn xác định tất cả tham số sẽ sử dụng trong quy trình OAuth, bao gồm:

  • Điểm cuối uỷ quyền: Được dùng làm điểm bắt đầu của quy trình uỷ quyền.
  • Điểm cuối mã thông báo: Được dùng với mã làm mới để lấy mã truy cập.
  • mã ứng dụng khách và khoá bí mật: Thông tin xác thực của ứng dụng.

OAuth Playground

Sử dụng tập lệnh để lấy mã làm mới

Bạn có thể xem mẫu tạo mã thông báo làm mới theo cách thay thế dựa trên tập lệnh để hoàn tất quy trình.

Làm mới việc sử dụng mã thông báo

Sau khi thực hiện lần uỷ quyền ban đầu, các dịch vụ có thể cấp một mã làm mới. Sau đó, mã này có thể được dùng theo cách tương tự như quy trình xác thực ứng dụng. Sau đây là hai ví dụ:

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

Ví dụ về Search Ads 360

Search Ads 360 là một ví dụ về API có thể sử dụng với mã làm mới. Trong mẫu này, một tập lệnh sẽ tạo và trả về một báo cáo. Hãy tham khảo Tài liệu tham khảo API Search Ads 360 để biết toàn bộ thông tin chi tiết về các hành động khác có thể thực hiện.

Tạo tập lệnh
  1. Tạo một dự án mới trong Bảng điều khiển API và lấy mã ứng dụng khách, mật khẩu ứng dụng khách và mã làm mới bằng cách làm theo quy trình trong hướng dẫn về DoubleClick, đảm bảo rằng bạn bật API DoubleClick Search.
  2. Dán tập lệnh mẫu vào tập lệnh mới trong Google Ads.
  3. Dán thư viện OAuth2 mẫu vào bên dưới danh sách mã.
  4. Sửa đổi tập lệnh để chứa các giá trị chính xác cho mã ứng dụng khách, mật khẩu ứng dụng khách và mã làm mới.

Ví dụ về API thực thi tập lệnh ứng dụng

Ví dụ này minh hoạ việc thực thi một hàm trong Apps Script bằng Apps Script Execution API. Thao tác này cho phép gọi Apps Script từ tập lệnh Google Ads.

Tạo tập lệnh Apps Script

Tạo tập lệnh mới. Mẫu sau đây sẽ liệt kê 10 tệp trong Drive:

function listFiles() {
  const limit = 10;
  const files = [];
  const fileIterator = DriveApp.getFiles();
  while (fileIterator.hasNext() && limit) {
    files.push(fileIterator.next().getName());
    limit--;
  }
  return files;
}
Định cấu hình Apps Script để thực thi
  1. Lưu tập lệnh.
  2. Nhấp vào Tài nguyên > Dự án Cloud Platform.
  3. Nhấp vào tên dự án để chuyển đến Bảng điều khiển API.
  4. Chuyển đến phần API và dịch vụ.
  5. Bật các API thích hợp, trong trường hợp này là API Drive và API thực thi tập lệnh ứng dụng.
  6. Tạo thông tin xác thực OAuth từ mục Thông tin xác thực trong trình đơn.
  7. Quay lại tập lệnh của bạn, xuất bản tập lệnh để thực thi từ Publish > Deploy as API Executable (Xuất bản > Triển khai dưới dạng có thể thực thi API).
Tạo tập lệnh Google Ads
  1. Dán tập lệnh mẫu vào tập lệnh mới trong Google Ads.
  2. Ngoài ra, hãy dán thư viện OAuth2 mẫu vào bên dưới danh sách mã.
  3. Sửa đổi tập lệnh để chứa các giá trị chính xác cho mã ứng dụng khách, mật khẩu ứng dụng khách và mã làm mới.

Tài khoản dịch vụ

Một giải pháp thay thế cho các loại tài trợ ở trên là khái niệm về tài khoản dịch vụ.

Tài khoản dịch vụ khác với nêu trên ở chỗ không dùng để truy cập vào dữ liệu người dùng: Sau khi xác thực, các yêu cầu sẽ do Tài khoản dịch vụ thực hiện thay mặt cho ứng dụng, chứ không phải người dùng có thể sở hữu dự án. Ví dụ: nếu tài khoản dịch vụ sử dụng API Drive để tạo tệp, thì tài khoản này sẽ thuộc về tài khoản dịch vụ và theo mặc định, chủ sở hữu dự án không thể truy cập vào tệp này.

Ví dụ về API ngôn ngữ tự nhiên của Google

API ngôn ngữ tự nhiên cung cấp phân tích ý kiến và phân tích thực thể cho văn bản.

Ví dụ này minh hoạ việc tính toán ý kiến đối với văn bản quảng cáo (bao gồm cả dòng tiêu đề hoặc nội dung mô tả). Chỉ số này giúp đo lường mức độ tích cực của thông điệp và độ lớn của thông điệp đó: Chúng tôi bán bánh hay Chúng tôi bán bánh ngon nhất ở London. Mua ngay hôm nay!?

Thiết lập tập lệnh
  1. Tạo một dự án mới trong Bảng điều khiển API
  2. Bật API Ngôn ngữ tự nhiên
  3. Bật tính năng thanh toán cho dự án.
  4. Tạo Tài khoản dịch vụ. Tải tệp JSON chứa thông tin đăng nhập xuống.
  5. Dán tập lệnh mẫu vào một tập lệnh mới trong Google Ads.
  6. Ngoài ra, hãy dán thư viện OAuth2 mẫu vào bên dưới danh sách mã.
  7. Thay thế các giá trị cần thiết:
    • serviceAccount: Địa chỉ email của Tài khoản dịch vụ, ví dụ như xxxxx@yyyy.iam.gserviceaccount.com.
    • key: Khoá từ tệp JSON được tải xuống khi tạo Tài khoản dịch vụ. Bắt đầu vào -----BEGIN PRIVATE KEY... và kết thúc vào ...END PRIVATE KEY-----\n.

Phản hồi của API

API có thể trả về dữ liệu ở nhiều định dạng. Đáng chú ý nhất trong số này là XML và JSON.

JSON

Khi sử dụng định dạng phản hồi, JSON thường đơn giản hơn XML. Tuy nhiên, vẫn có một số vấn đề có thể phát sinh.

Xác thực phản hồi

Khi nhận được phản hồi thành công từ lệnh gọi đến API, bước tiếp theo thông thường là sử dụng JSON.parse để chuyển đổi chuỗi JSON thành đối tượng JavaScript. Tại thời điểm này, bạn có thể xử lý trường hợp thất bại trong quá trình phân tích cú pháp:

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

Ngoài ra, nếu API không thuộc quyền kiểm soát của bạn, hãy cân nhắc rằng cấu trúc của phản hồi có thể thay đổi và các thuộc tính có thể không còn tồn tại nữa:

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

Xác nhận kết quả

XML vẫn là một định dạng phổ biến để xây dựng API. Bạn có thể phân tích cú pháp phản hồi từ lệnh gọi API bằng phương thức XmlService parse:

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

Mặc dù XmlService.parse phát hiện lỗi trong XML và gửi ngoại lệ theo đúng cách, nhưng mã này không cung cấp khả năng xác thực XML dựa trên một giản đồ.

Phần tử gốc

Sau khi phân tích cú pháp thành công tài liệu XML, phần tử gốc sẽ được lấy bằng phương thức getRootElement():

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

Không gian tên

Trong ví dụ sau, API Sportradar được dùng để lấy kết quả bóng đá cho các trận đấu đã chọn. Phản hồi XML có định dạng sau:

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

Xin lưu ý cách không gian tên được chỉ định trong thành phần gốc. Do đó, bạn cần phải:

  • Trích xuất thuộc tính không gian tên từ tài liệu.
  • Hãy sử dụng vùng chứa tên này khi truyền tải và truy cập các phần tử con.

Mẫu sau đây cho biết cách truy cập vào phần tử <matches> trong đoạn mã tài liệu ở trên:

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

Lấy giá trị

Cho mẫu từ lịch thi đấu bóng đá:

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

Bạn có thể truy xuất các thuộc tính, ví dụ:

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

Bạn có thể đọc văn bản chứa trong một phần tử bằng cách sử dụng getText(), nhưng các văn bản này sẽ được nối với nhau khi có nhiều văn bản con của phần tử đó. Hãy cân nhắc sử dụng getChildren() và lặp lại qua từng thành phần con trong trường hợp có thể có nhiều văn bản con.

Ví dụ về Sportradar

Ví dụ về Sportradar đầy đủ này minh hoạ thông tin truy xuất thông tin chi tiết về các trận đấu bóng đá, cụ thể là các trận đấu thuộc giải Ngoại hạng Anh. Bóng đá API là một trong số nhiều nguồn cấp dữ liệu thể thao do Sportradar cung cấp.

Thiết lập tài khoản Sportradar
  1. Chuyển đến trang web dành cho nhà phát triển Sportradar
  2. Đăng ký tài khoản dùng thử.
  3. Sau khi đăng ký, hãy đăng nhập vào tài khoản của bạn.
  4. Sau khi đăng nhập, hãy chuyển đến phần MyAccount (Tài khoản của tôi).

Sportradar phân tách các môn thể thao khác nhau thành các API khác nhau. Ví dụ: bạn có thể mua quyền truy cập vào API bóng đá nhưng không thể mua quyền truy cập vào API quần vợt. Mỗi ứng dụng bạn tạo có thể liên kết với nhiều môn thể thao với các khoá khác nhau.

  1. Trong phần Ứng dụng, hãy nhấp vào Tạo ứng dụng mới. Đặt tên và nội dung mô tả cho ứng dụng rồi bỏ qua trường trang web.
  2. Chỉ chọn Cấp khoá mới cho Football Trial Europe phiên bản 2.
  3. Nhấp vào Đăng ký ứng dụng.

Sau khi thực hiện thành công, thao tác này sẽ tạo ra một trang có khoá API mới của bạn.

  1. Dán tập lệnh mẫu vào tập lệnh mới trong Google Ads.
  2. Thay thế khoá API trong trang thông tin bằng khoá đã nhận được ở trên và chỉnh sửa trường địa chỉ email.

Khắc phục sự cố

Khi dùng API của bên thứ ba, lỗi có thể xảy ra vì một số lý do, chẳng hạn như:

  • Các ứng dụng gửi yêu cầu đến máy chủ ở định dạng mà API không mong đợi.
  • Ứng dụng muốn nhận được một định dạng phản hồi khác với định dạng mà họ gặp phải.
  • Ứng dụng sử dụng mã thông báo hoặc khoá không hợp lệ hoặc các giá trị được để lại làm phần giữ chỗ.
  • Khách hàng đạt đến hạn mức sử dụng.
  • Ứng dụng cung cấp các tham số không hợp lệ.

Trong tất cả các trường hợp này và các trường hợp khác, bước đầu tiên phù hợp để xác định nguyên nhân của vấn đề là kiểm tra chi tiết của phản hồi gây ra lỗi.

Phân tích cú pháp phản hồi

Theo mặc định, mọi phản hồi trả về lỗi (mã trạng thái từ 400 trở lên) sẽ do công cụ tập lệnh Google Ads gửi.

Để ngăn hành vi này cũng như cho phép kiểm tra lỗi và thông báo lỗi, hãy đặt thuộc tính muteHttpExceptions của các tham số không bắt buộc thành UrlFetchApp.fetch. Ví dụ:

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

Các mã trạng thái thường gặp

  • 200 OK cho biết đã thành công. Nếu phản hồi không chứa dữ liệu dự kiến, hãy xem xét điều đó:

    • Một số API cho phép chỉ định rõ những trường và/hoặc định dạng phản hồi sẽ sử dụng. Hãy xem tài liệu API để biết thông tin chi tiết về việc này.
    • Một API có thể có nhiều tài nguyên có thể gọi được. Hãy tham khảo tài liệu này để xác định xem một tài nguyên khác có thể phù hợp hơn để sử dụng hay không và sẽ trả về dữ liệu bạn yêu cầu.
    • API có thể đã thay đổi kể từ khi mã được viết. Hãy tham khảo tài liệu này hoặc nhà phát triển để biết rõ.

  • 400 Bad Request thường có nghĩa là có điều gì đó không chính xác trong định dạng hoặc cấu trúc của yêu cầu được gửi đến máy chủ. Kiểm tra yêu cầu và so sánh yêu cầu đó với các thông số kỹ thuật của API để đảm bảo yêu cầu đúng với kỳ vọng. Hãy xem phần Kiểm tra yêu cầu để biết thông tin chi tiết về cách kiểm tra các yêu cầu.

  • 401 Unauthorized thường có nghĩa là API đang được gọi mà không cung cấp hoặc thực hiện thành công yêu cầu uỷ quyền.

    • Nếu API sử dụng quy trình uỷ quyền cơ bản, hãy đảm bảo tiêu đề Authorization đang được tạo và cung cấp trong yêu cầu.
    • Nếu API sử dụng OAuth 2.0, hãy đảm bảo rằng bạn đã lấy mã truy cập và đang được cung cấp dưới dạng Mã thông báo truy cập.
    • Đối với mọi biến thể khác về việc uỷ quyền, hãy đảm bảo bạn đang cung cấp thông tin xác thực cần thiết cho yêu cầu.

  • 403 Forbidden cho biết người dùng không có quyền đối với tài nguyên đang được yêu cầu.

    • Đảm bảo người dùng đã được cấp các quyền cần thiết, chẳng hạn như cấp cho người dùng quyền truy cập vào một tệp trong một yêu cầu dựa trên tệp.

  • 404 Not Found có nghĩa là tài nguyên được yêu cầu không tồn tại.

    • Kiểm tra để đảm bảo URL dùng cho điểm cuối API là chính xác.
    • Khi tìm nạp tài nguyên, hãy kiểm tra xem tài nguyên đang được tham chiếu có tồn tại hay không (ví dụ: nếu tệp tồn tại đối với API dựa trên tệp).

Kiểm tra yêu cầu

Việc kiểm tra yêu cầu sẽ hữu ích khi phản hồi API cho biết yêu cầu được định dạng không đúng, ví dụ: mã trạng thái 400. Để giúp kiểm tra yêu cầu, UrlFetchApp có một phương thức đồng hành với phương thức fetch(), có tên là getRequest()

Thay vì gửi yêu cầu đến máy chủ, phương thức này sẽ tạo yêu cầu sẽ được gửi rồi trả về. Điều này cho phép người dùng kiểm tra các thành phần của yêu cầu để đảm bảo yêu cầu là chính xác.

Ví dụ: nếu dữ liệu biểu mẫu trong yêu cầu của bạn bao gồm nhiều chuỗi nối với nhau, thì lỗi có thể nằm ở hàm mà bạn đã tạo để tạo dữ liệu biểu mẫu đó. Cách đơn giản nhất:

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

sẽ cho phép bạn kiểm tra các thành phần của yêu cầu.

Ghi nhật ký các yêu cầu và phản hồi

Để hỗ trợ toàn bộ quy trình kiểm tra các yêu cầu và phản hồi cho API của bên thứ ba, bạn có thể sử dụng chức năng trợ giúp sau đây làm giải pháp thay thế cho UrlFetchApp.fetch(), để ghi lại cả yêu cầu và phản hồi.

  1. Thay thế mọi bản sao của UrlFetchApp.fetch() trong mã bằng logUrlFetch().

  2. Thêm hàm sau vào cuối tập lệnh của bạn.

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

Khi thực thi tập lệnh của bạn, thông tin chi tiết về tất cả yêu cầu và phản hồi sẽ được ghi vào bảng điều khiển, cho phép gỡ lỗi dễ dàng hơn.