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 trình bày các khái niệm sau đây 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 trình bày 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ề.

Chúng tôi cũng cung cấp mẫu cho một số API phổ biến minh hoạ các khái niệm này.

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 đây cho thấy cách 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 của OpenWeatherMap chỉ định định dạng để yêu cầu thông tin thời tiết hiện tại như sau:

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

URL này 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 thông qua quy trình đăng ký.

Sau khi đăng ký, bạn có thể đưa ra 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ẽ tạo ra một chuỗi văn bản JSON dài đượ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 tệp này thành một định dạng có thể sử dụng trong tập lệnh.

Dữ liệu JSON

Nhiều API cung cấp phản hồi ở định dạng JSON. Đây là một quá trình chuyển đổi tuần tự đơn giản của 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 một chuỗi JSON (chẳng hạn như chuỗi được trả về từ OpenWeatherMap) trở lại thành một đố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.

Hãy 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 xử lý phản hồi API ở nhiều định dạng.

Xử lý lỗi

Xử lý lỗi là một vấn đề quan trọng cần cân nhắc khi làm việc với các API của bên thứ ba trong tập lệnh của bạn vì các 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, ví dụ:

  • URL hoặc tham số cho API có thể thay đổi mà bạn không biết.
  • Khoá API (hoặc thông tin đăng nhập 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ần thông báo trước.

Mã trạng thái HTTP

Do có thể có các 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 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 thấy ngay 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ó như dự kiến hay không, ví dụ:

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

Dữ liệu POST bằng UrlFetchApp

Ví dụ giới thiệu với OpenWeatherMap chỉ tìm nạp dữ liệu. 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ạ cách sử dụng lệnh gọi POST với 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 đến người dùng và nhóm 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.

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

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

Tạo yêu cầu POST

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

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

  • payload: Đây là dữ liệu sẽ được gửi đến máy chủ trong yêu cầu POST. Trong ví dụ này, Slack dự kiến 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. Để thực hiện việc này, phương thức JSON.stringify đượ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 để bật tính năng gửi tin nhắn đến Slack. Một mẫu mở rộng minh hoạ cách 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

Hãy 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ề tin nhắn trên Slack.

Dữ liệu biểu mẫu

Ví dụ trên minh hoạ việc 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ẽ sử dụng các phương pháp khác nhau để 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 nội dung của yêu cầu.

  • Khi payload là một đối tượng, ví dụ: một bản đồ giá trị:

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

    Các 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 yêu cầu 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 ý đến quy trình chuyển đổi tự động từ đối tượng JavaScript sang dữ liệu biểu mẫu này.

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

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.

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

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

Tạo yêu cầu

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

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

Đoạn mã sau đây minh hoạ cách thực hiện việc 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);

Mẫu xác thực cơ bản

Phần mã mẫu chứa hai mẫu minh hoạ cách sử dụng Phương thức xác thực cơ bản HTTP:

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 của họ. Mẫu này minh hoạ việc gửi thông báo.

  1. Đăng ký với Plivo.
  2. Dán tập lệnh mẫu vào một tập lệnh mới trong Google Ads.
  3. Thay thế các giá trị PLIVO_ACCOUNT_AUTHID và PLIVO_ACCOUNT_AUTHTOKEN bằng các giá trị trong trang tổng quan về quản lý.
  4. Chèn địa chỉ email của bạn như đã chỉ định trong tập lệnh để nhận thông báo về 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ố điện thoại trong Hộp cát có thể dùng với tài khoản dùng thử.
  6. Thêm cả số điện thoại sẽ xuất hiện dưới dạng người gửi và số điện thoại của 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ố điện thoại trong hộp cát vừa đăng ký. Mã này phải bao gồm mã quốc gia quốc tế, ví dụ: 447777123456 cho số điện thoại ở 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 của họ. Mẫu này minh hoạ việc gửi thông báo.

  1. Đăng ký với Twillio.
  2. Dán tập lệnh mẫu vào một 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ố điện thoại trong trang tổng quan. Đây là số điện thoại đượ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ó một số phiên bản và phiên bản.

Trong khi với 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 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ẽ dành riêng cho ứng dụng đó.

Để biết thông tin cơ bản về 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. Trong OAuth 1.0 ba bên đầy đủ, quy trình diễn ra như sau:

  1. Ứng dụng ("Người dùng") nhận được mã thông báo yêu cầu.
  2. Người dùng uỷ quyền mã thông báo yêu cầu.
  3. Ứng dụng trao đổi mã thông báo yêu cầu để lấy mã thông báo truy cập.
  4. Đối với tất cả các yêu cầu tài nguyên tiếp theo, mã truy cập được sử dụng trong một 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 tương tác với người dùng (ví dụ: như các tập lệnh Google Ads yêu cầu), bạn không thể thực hiện các bước 1, 2 và 3. Do đó, một số dịch vụ sẽ phát hành mã thông báo truy cập từ 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 bê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 diễn giải là một ứng dụng. Thông qua trang cài đặt bảng điều khiển/quản trị của dịch vụ, bạn thường 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 đang được mở rộng cho tập lệnh.
  • Lấy khoá của người dùng, khoá bí mật của người dùng, mã truy cập và khoá truy cập để sử dụng với OAuth một chiều.

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 nhất định cấp quyền cho các ứng dụng cụ thể để cho phép truy cập vào dữ liệu người dùng. Các ưu điểm là chủ sở hữu:

  • Không 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 từng ứng dụng có quyền truy cập vào dữ liệu và mức độ truy cập. (Ví dụ: quyền truy cập được cấp có thể là chỉ có thể đọc hoặc chỉ truy cập vào một tập hợp con dữ liệu.)

Để sử dụng các dịch vụ 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ấ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, việc này sẽ liên quan đến việc 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.

Bạn chỉ định quyền truy cập nào sẽ được cấp cho ứng dụng của Tập lệnh Google Ads và ứng dụng này thường sẽ được chỉ định một mã ứng dụng khách. Thông qua OAuth 2, bạn có thể kiểm soát những ứ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ư những khía cạnh nào của dữ liệu đó mà các ứng dụng đó có thể xem hoặc sửa đổi.

Trong tập lệnh

Uỷ quyền với máy chủ từ xa. Tuỳ thuộc vào loại cấp quyền mà máy chủ cho phép, bạn sẽ cần làm theo một bộ bước khác nhau, được gọi là luồng, nhưng tất cả đều sẽ dẫn đến việc phát hành mã thông báo truy cập sẽ được 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 quyền cấp 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 tham gia một phiên tương tác, trái ngược với trường hợp ứng dụng bắt buộc 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 quyền cấp phép mà họ chấp nhận và điều này sẽ hướng dẫn cách người dùng tiến hành tích hợp API của họ.

Triển khai

Đối với tất cả các luồng OAuth, mục tiêu là lấy mã thông báo truy cập, sau đó có thể dùng mã này cho phần còn lại của phiên để xác thực cá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 trong số này trả về một đối tượng lấy và lưu trữ mã thông báo truy cập, đồng thời hỗ trợ các yêu cầu đã xác thực.

Mẫu 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 xác thực ứng dụng

Cấp thông tin xác thực ứng dụng là một trong những hình thức đơn giản hơn của luồng OAuth2, trong đó ứng dụng trao đổi một mã nhận dạng và mật khẩu riêng biệt với ứng dụng, để đổi lấy việc phát hành một 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

Cấp mã thông báo làm mới

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

Mã làm mới

Lấy mã làm mới

Điểm khác biệt với việc cấp mã thông báo làm mới là trong khi thông tin chi tiết cần thiết để cấp thông tin xác thực ứ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ụ), thì mã thông báo 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, sẽ 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 quy trình 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ả các tham số để sử dụng trong luồng OAuth, bao gồm:

  • Điểm cuối uỷ quyền: Dùng làm điểm bắt đầu của luồng uỷ quyền.
  • Điểm cuối mã thông báo: 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 cho ứng dụng.

OAuth Playground

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

Bạn có thể sử dụng phương án thay thế dựa trên tập lệnh để hoàn tất luồng trong mẫu tạo mã thông báo làm mới.

Sử dụng mã thông báo làm mới

Sau khi thực hiện quá trình uỷ quyền ban đầu, các dịch vụ có thể phát hành mã thông báo làm mới. Sau đó, mã thông báo này có thể được sử dụng theo cách tương tự như luồng thông tin xác thực của ứ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ể dùng với mã thông báo làm mới. Trong mẫu này, tập lệnh 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 thao tác khác có thể thực hiện.

Tạo tập lệnh
  1. Tạo một dự án mới trong API Console và lấy mã ứng dụng, khoá ứng dụng và mã thông báo 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 Tìm kiếm DoubleClick.
  2. Dán tập lệnh mẫu vào một tập lệnh mới trong Google Ads.
  3. Dán thư viện OAuth2 mẫu 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, mật khẩu ứng dụng và mã thông báo làm mới.

Ví dụ về API thực thi Apps Script

Ví dụ này minh hoạ cách thực thi một hàm trong Apps Script bằng API Thực thi tập lệnh Apps. Điều này cho phép gọi Apps Script từ các 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 trên 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 API Console.
  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 Credentials (Thông tin xác thực) trong trình đơn.
  7. Quay lại tập lệnh, hãy phát hành tập lệnh để thực thi từ Publish (Xuất bản) > Deploy as API Executable (Triển khai dưới dạng API thực thi).
Tạo tập lệnh Google Ads
  1. Dán tập lệnh mẫu vào một tập lệnh mới trong Google Ads.
  2. Ngoài ra, hãy dán thư viện OAuth2 mẫu 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, mật khẩu ứng dụng và mã thông báo làm mới.

Tài khoản dịch vụ

Một giải pháp thay thế cho các loại quyền cấp 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 các tài khoản ở trên ở chỗ chúng không được dùng để truy cập vào dữ liệu người dùng: Sau khi xác thực, Tài khoản dịch vụ sẽ thay mặt ứng dụng thực hiện các yêu cầu, 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ệp này sẽ thuộc về tài khoản dịch vụ và theo mặc định, chủ sở hữu dự án sẽ không truy cập được.

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

API ngôn ngữ tự nhiên cung cấp tính năng phân tích cảm xúc và phân tích thực thể cho văn bản.

Ví dụ này minh hoạ cách tính toán cảm xúc cho 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 cho biết mức độ tích cực và cường độ của thông điệp: Thông điệp nào tốt hơn, Chúng tôi bán bánh hay Chúng tôi bán bánh ngon nhất ở London. Mua ngay!?

Thiết lập tập lệnh
  1. Tạo dự án mới trong API Console
  2. Bật Natural Language API (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 xác thực 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 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ụ: xxxxx@yyyy.iam.gserviceaccount.com.
    • key: Khoá trong tệp JSON được tải xuống khi tạo Tài khoản dịch vụ. Bắt đầu -----BEGIN PRIVATE KEY... và kết thúc ...END PRIVATE KEY-----\n.

Phản hồi của API

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

JSON

JSON thường đơn giản hơn XML để làm việc dưới dạng định dạng phản hồi. Tuy nhiên, vẫn có thể xảy ra một số vấn đề.

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

Sau 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 nên xử lý trường hợp phân tích cú pháp không thành công:

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 bạn không kiểm soát được API, 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:

// 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 thực

XML vẫn là một định dạng phổ biến để tạo 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 các trường hợp ngoại lệ tương ứng, nhưng lớp này không cung cấp khả năng xác thực XML theo một lược đồ.

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, Sportradar API đượ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>

Lưu ý cách không gian tên được chỉ định trong phần tử gốc. Do đó, bạn cần:

  • Trích xuất thuộc tính không gian tên từ tài liệu.
  • Sử dụng không gian tên này khi di chuyển và truy cập vào các phần tử con.

Mẫu sau đây cho biết cách truy cập phần tử <matches> trong đoạn 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 trước 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 getText(), nhưng các văn bản này sẽ được nối với nhau khi có nhiều phần tử con văn bản của một phần tử. Hãy cân nhắc việc sử dụng getChildren() và lặp lại trên mỗi phần tử con trong trường hợp có nhiều phần tử con văn bản.

Ví dụ về Sportradar

Ví dụ đầy đủ về Sportradar này minh hoạ việc 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. Soccer API là một trong 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.

Sportradar phân tách các môn thể thao 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 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à nhiều khoá.

  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, đồng thời bỏ qua trường trang web.
  2. Chỉ chọn Issue a new key for Soccer Trial Europe v2 (Cấp khoá mới cho Soccer Trial Europe v2).
  3. Nhấp vào Đăng ký ứng dụng.

Sau khi thành công, bạn sẽ thấy một trang có khoá API mới.

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

Khắc phục sự cố

Khi làm việc với 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ư:

  • Ứng dụng khách đưa ra yêu cầu cho máy chủ ở định dạng không theo dự kiến của API.
  • Ứng dụng dự kiến định dạng phản hồi khác với định dạng đã gặp.
  • Ứng dụng sử dụng mã thông báo hoặc khoá không hợp lệ hoặc giá trị được để trống làm phần giữ chỗ.
  • Ứng dụng đạt đến hạn mức sử dụng.
  • Ứng dụng khách cung cấp 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 tốt nhất để xác định nguyên nhân gây ra vấn đề là kiểm tra thông tin chi tiết về 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ẽ được công cụ tập lệnh Google Ads gửi.

Để ngăn hành vi này và 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...
}

Mã trạng thái phổ biến

  • 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 cân nhắc những điều sau:

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

  • 400 Bad Request thường có nghĩa là có 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 với thông số kỹ thuật của API để đảm bảo yêu cầu đó tuân thủ các 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 việc uỷ quyền.

    • Nếu API sử dụng quyền 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 bạn đã lấy được mã truy cập và đang cung cấp mã này 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 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, ví dụ: cấp cho người dùng quyền truy cập vào một tệp trong 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.
    • Nếu tìm nạp tài nguyên, hãy kiểm tra để đảm bảo tài nguyên được tham chiếu tồn tại (ví dụ: nếu tệp tồn tại cho 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 tạo không đúng định dạng, ví dụ: mã trạng thái 400. Để giúp kiểm tra các yêu cầu, UrlFetchApp có một phương thức đồng hành với phương thức fetch(), được gọi 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ề yêu cầu đó. Điều này cho phép người dùng kiểm tra các phần tử của yêu cầu để đảm bảo yêu cầu đó có vẻ 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 được nối với nhau, thì lỗi có thể nằm trong hàm bạn đã tạo để tạo dữ liệu biểu mẫu đó. Nói một cách đơn giản:

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 phần tử của yêu cầu.

Ghi lại các yêu cầu và phản hồi

Để hỗ trợ toàn bộ quá 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 hàm trợ giúp sau đây để thay thế UrlFetchApp.fetch(), nhằm ghi lại cả yêu cầu và phản hồi.

  1. Thay thế tất cả các thực thể của UrlFetchApp.fetch() trong mã bằng logUrlFetch().

  2. Thêm hàm sau vào cuối tập lệnh.

    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, thông tin chi tiết về tất cả các yêu cầu và phản hồi sẽ được ghi vào bảng điều khiển, giúp gỡ lỗi dễ dàng hơn.