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 đề 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ề.

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 vì lược đồ uỷ quyền và API tương đối đơn giản.

Tạo yêu cầu

Tài liệu về 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 này cung cấp ví dụ đầu tiên về quy trình uỷ quyền: Tham số apikey là bắt buộc và giá trị này 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ể đư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());

Khi thực thi mã này, một chuỗi văn bản JSON dài sẽ đượ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 dữ liệu này sang định dạng có thể dùng 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. Đây là một chuỗi tuần tự hoá của các đối tượng JavaScript, sao cho các đối tượng, mảng và kiểu 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 đố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 ví dụ trước:

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 của API ở nhiều định dạng.

Xử lý lỗi

Xử lý lỗi là một yếu tố quan trọng cần cân nhắc khi làm việc với API của bên thứ ba trong tập lệnh của bạn, vì API của bên thứ ba thường xuyên thay đổi 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.

Mã trạng thái HTTP

Do có khả năng 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 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, bạn có thể không biết ngay về những thay đổi có thể ảnh hưởng đến tập lệnh của mình. 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 tra xem cấu trúc được trả về có như mong đợi 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ạ cách 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.

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 tin nhắn. Slack cung cấp một URL riêng biệt để bạn có thể gửi tin nhắn đến 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 chế độ tích hợp Webhook đến rồi làm theo hướng dẫn. Quá trình này sẽ đưa ra 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, để tạo yêu cầu POST, bạn cần sử dụng một số thuộc tính bổ sung trong tham số options được truyền đến UrlFetchApp.fetch:

  • method: Như đã đề cập, giá trị mặc định là GET, nhưng ở đây, chúng ta sẽ ghi đè 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 yêu cầu 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 việc này, phương thức [JSON.stringify][json-stringify-url] đượ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ước cho thấy mã tối thiểu cần thiết để bật tin nhắn đến vào Slack. 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 cho một nhóm, cũng như một số lựa chọn định dạng và hiển thị.

Tin nhắn đến

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 Slack.

Dữ liệu biểu mẫu

Ví dụ trước minh hoạ 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ẽ áp 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 đồ các 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 nên lưu ý đến quá trình chuyển đổi tự động này từ đối tượng JavaScript sang dữ liệu biểu mẫu.

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

Xác thực cơ bản qua 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.

Quá trình xác thực được thực hiện 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 qua 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 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 theo 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 qua HTTP:

Plivo

Plivo là một dịch vụ hỗ trợ việc gửi và nhận tin nhắn SMS bằng API của họ. Mẫu này minh hoạ cách gửi tin nhắn.

  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 bảng điều khiển quản lý.
  4. Chèn địa chỉ email của bạn như được 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ố điện thoại hoặc thêm số điện thoại vào tài khoản dùng thử. Thêm số điện thoại thử nghiệm 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 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ý. Số 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 bằng API của họ. Mẫu này minh hoạ cách gửi tin nhắn.

  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ị hiển thị 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 trên trang tổng quan – đây là số điện thoại được Twilio cho phép 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à biến thể.

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, thì 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ẽ tuỳ theo ứ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 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 cho 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ã 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 dùng trong một yêu cầu đã ký.

Đối với các dịch vụ của bên thứ ba sử dụng OAuth 1.0 mà không có sự tương tác của người dùng (ví dụ: như 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ẽ cấp mã 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 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 bảng điều khiển hoặc trang cài đặt quản trị cho dịch vụ, bạn thường cần phải:

  • Thiết lập cấu hình ứng dụng để đại diện cho tập lệnh.
  • Chỉ định những quyền được cấp 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á bí mật truy cập để sử dụng với OAuth một chân.

OAuth 2.0

OAuth 2.0 được dùng trong các API phổ biến để 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 các ứng dụng đó truy cập vào dữ liệu người dùng. Ư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à phạm vi truy cập. (Ví dụ: quyền truy cập được cấp có thể chỉ có thể đọc hoặc chỉ có thể truy cập vào một tập hợp con của 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:

Ngoài kịch bản 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, 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 của bạn.

Bạn chỉ định quyền truy cập mà ứng dụng tập lệnh Google Ads sẽ được cấp 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.0, 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 kịch bản của bạn

Uỷ quyền với máy chủ từ xa. Tuỳ thuộc vào kiểu cấp quyền mà máy chủ cho phép, bạn sẽ cần thực hiện một loạt bước khác nhau (gọi là quy trình), nhưng tất cả đều sẽ dẫn đến việc cấp mã truy cập để dùng cho phiên đó trong 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 theo mỗi yêu cầu.

Quy trình uỷ quyền

Mỗi kiểu cấp quyền và quy trình tương ứng sẽ phù hợp với các trường hợp sử dụng khác nhau. Ví dụ: một quy trình khác được sử dụng khi người dùng đang 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 kiểu cấp quyền mà họ chấp nhận, và điều này sẽ hướng dẫn người dùng cách tiến hành tích hợp API của họ.

Triển khai

Đối với tất cả các quy trình OAuth, mục tiêu là lấy mã 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 quy trình. Mỗi phương thức này 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.

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 đăng nhập của ứng dụng

[Cấp thông tin đăng nhập của ứng dụng khách][client-credentials-rfc] 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ã nhận dạng và thông tin bí mật (duy nhất 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

Cấp mã làm mới

Việc cấp mã làm mới tương tự như việc cấp thông tin xác thực ứng dụng, trong đó yêu cầu gửi đến máy chủ sẽ trả về một mã truy cập có thể 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ã làm mới là trong khi các thông tin chi tiết cần thiết để cấp thông tin xác thực ứng dụng khách đế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ã 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][authorization-code-rfc], 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 từng bước cấp mã uỷ quyền để nhận 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ố cần 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 cho ứng dụng.

    OAuth Playground

Sử dụng mã làm mới

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

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ã làm mới. Trong mẫu này, một tập lệnh tạo và trả về một báo cáo. Tham khảo Tài liệu tham khảo API Search Ads 360 để biết thông tin chi tiết đầy đủ 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 Google Cloud Console, rồi lấy mã ứng dụng khách, khoá bí mật của ứ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ề Search Ads 360, đồng thời đảm bảo rằng bạn bật Search Ads 360 API.
  2. Dán [đoạn mã mẫu][search-ads-360-example] vào một tập lệnh mới trong Google Ads.
  3. Dán [thư viện OAuth2 mẫu][oauth20-library-example] 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, khoá bí mật của ứng dụng khách và mã 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 Apps Script Execution API. Điều này cho phép bạn 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 từ 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 Google Cloud 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à Drive API và Apps Script Execution API.
  6. Tạo thông tin đăng nhập OAuth từ mục Credentials (Thông tin đăng nhập) 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ừ Xuất bản > Triển khai dưới dạng tệp thực thi API.
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][oauth20-library-example] 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, khoá bí mật của ứ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 kiểu cấp quyền là khái niệm tài khoản dịch vụ.

Tài khoản dịch vụ khác với kiểu cấp quyề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, các yêu cầu sẽ được Tài khoản dịch vụ thực hiện thay mặt cho ứng dụng, chứ không phải với tư cách là 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 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][natural-language-api-docs] cung cấp tính năng [phân tích cảm xúc][sentiment-analysis-api-docs] và [phân tích thực thể][entity-analysis-api-docs] cho văn bản.

Ví dụ này minh hoạ cách tính [mức độ cảm xúc][sentiment-api-docs] cho văn bản quảng cáo, bao gồm cả dòng tiêu đề hoặc nội dung mô tả. Điều này giúp đo lường mức độ tích cực và tầm quan trọng của thông điệp: Thông điệp nào hay hơn, Chúng tôi bán bánh hay Chúng tôi bán những chiếc 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 Google Cloud Console.
  2. Bật [Natural Language API][natural-language-api].
  3. Bật tính năng thanh toán cho dự án.
  4. [Tạo tài khoản dịch vụ][create-service-account]. 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][natural-language-example] 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][oauth20-library-example] 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á từ tệp JSON được tải xuống khi tạo Tài khoản dịch vụ. Bắt đầu từ -----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

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

Xác thực câu trả lờ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 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 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:

// 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 cho phép tập lệnh của bạn phân tích cú pháp và trích xuất dữ liệu từ nội dung phản hồi XML.

Xác thực

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 các 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 dựa trên 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, 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 như sau:

<schedule_schedules xmlns="http://schemas.sportradar.com/sportsapi/soccer/v4">
  <schedule>
     ...
  </schedule>
</schedule_schedules>

Lưu ý cách chỉ định không gian tên trong phần tử gốc. Vì vậy, 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 duyệt qua và truy cập vào các phần tử con.

Mẫu sau đây cho thấy cách truy cập vào phần tử <schedule> và tìm các phần tử con <sport_event> của phần tử đó trong đoạn mã tài liệu trước:

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

Lấy giá trị

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

<sport_event_status status="..." ... />

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

const statusElement = sportEventElement.getChild('sport_event_status', namespace);
const status = statusElement.getAttribute('status').getValue();

Bạn có thể đọc văn bản có 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 dạng văn bản của một phần tử. Hãy cân nhắc sử dụng getChildren() và lặp lại trên từng phần tử con trong trường hợp có thể có nhiều phần tử con văn bản.

Ví dụ về Sportradar

Ví dụ đầy đủ về Sportradar này minh hoạ cách truy xuất thông tin chi tiết về các trận bóng đá, cụ thể là các trận đấu trong 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 của 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 mục 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 mua quyền truy cập vào API Quần vợt. Mỗi Ứng dụng bạn tạo có thể có các môn thể thao và khoá khác nhau liên kết với ứng dụng đó.

  1. Trong phần Ứng dụng, hãy nhấp vào Tạo ứng dụng mới. Đặt tên và mô tả cho ứng dụng, đồng thời bỏ qua trường trang web.
  2. Chỉ chọn Cấp khoá mới cho Soccer Trial Europe v2.
  3. Nhấp vào Register Application (Đă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á mới được cấp và 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, ví dụ:

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

Phân tích cú pháp câu trả lờ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 đi.

Để ngăn chặn hành vi này và cho phép kiểm tra lỗi cũng như 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, định dạng phản hồi hoặc cả hai. 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ể gọi được. Hãy tham khảo tài liệu để xác định xem có tài nguyên nào khác phù hợp hơn để sử dụng và sẽ trả về dữ liệu bạn cần hay không.
    • 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õ.
  • 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 thông số kỹ thuật của API để đảm bảo yêu cầu đó tuân thủ các yêu cầu. 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 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 quy trình uỷ quyền.

    • Nếu API sử dụng phương thức 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 được mã truy cập và đang cung cấp mã đó 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 có tồn tại (ví dụ: nếu tệp tồn tại cho một 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 của API cho biết yêu cầu có định dạng không hợp lệ, 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(url, params)

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 đáng lẽ đã đượ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 mà bạn đã tạo để tạo dữ liệu biểu mẫu đó. Nói một 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ý 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 đối với API của bên thứ ba, bạn có thể sử dụng hàm trợ giúp sau đây làm hàm thay thế cho UrlFetchApp.fetch() để ghi lại cả yêu cầu và phản hồi.

  1. Thay thế tất cả các 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.

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

[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