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ừ 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 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 bao gồm mẫu cho một số của các API phổ biến minh hoạ cho 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 API của bên thứ ba.

Ví dụ sau đây cho thấy việc tìm nạp dữ liệu thời tiết từ OpenWeatherMap. Chúng tôi đã chọn OpenWeatherMap do API và giao thứ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ô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 lấy khoá này qua đăng ký.

Sau khi đăng ký, bạn có thể gửi một yêu cầu bằng khoá theo cách 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 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 quảng cáo này sang định dạng có thể được 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. Điều này thể hiện sự đơn giản chuyển đổi tuần tự các đối tượng JavaScript, chẳng hạn như đối tượng, mảng và các kiểu cơ bản có thể được biểu thị và chuyển dưới dạng chuỗi.

Để chuyển đổi chuỗi JSON, chẳng hạn như chuỗi được trả về từ OpenWeatherMap—quay lại đối tượng JavaScript, sử dụng tính năng tích hợp JSON.parse. Tiếp tục trong 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, trong đó có một thuộc tính name

Vui lòng xem phần Phân tích cú pháp câu trả lời để biết thêm thông tin về làm việc với 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 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 mình vì API của bên thứ ba thường thay đổi thường xuyên và tạo ra giá trị phản hồi không mong muốn, ví dụ:

  • URL hoặc các tham số của API có thể thay đổi mà bạn không biết.
  • Khoá API của bạn (hoặc thông tin đăng nhập người dùng khác) có thể hết hạn.
  • Định dạng của câu trả lời có thể thay đổi mà không cần thông báo.

Mã trạng thái HTTP

Do có thể xảy ra các phản hồi không mong muốn, bạn nên kiểm tra mã HTTP mã trạng thái. Theo mặc định, UrlFetchApp sẽ gửi ra một ngoại lệ nếu gặp mã lỗi HTTP. Người nhận thay đổi hành vi này, thì 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 biết ngay những thay đổi có thể ảnh hưởng đến tập lệnh của chúng. Ví dụ: nếu thuộc tính name trả về trong ví dụ OpenWeatherMap được thay đổi thành locationName, tập lệnh nhưng bạn sẽ không thể sử dụng thuộc tính này.

Vì lý do này, bạn nên kiểm tra xem cấu trúc được trả về có đúng như dự kiến, 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ề OpenWeatherMap chỉ dữ liệu được tìm nạp. Thông thường, các lệnh gọi API không thay đổi trạng thái ở điều khiển từ xa máy chủ, hãy sử dụng 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ư các cuộc 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, như POST hoặc PUT.

Để minh hoạ cách sử dụng lệnh gọi POST bằng UrlFetchApp, hãy xem ví dụ sau minh hoạ việc tích hợp với Slack, một thông điệp cộng tác để gửi thông báo trê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ý một tài khoản Slack.

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

Thiết lập Webhook đến bằng cách nhấp vào Thêm mối liên kết tích hợp WebHooks đến và làm theo hướng dẫn. Chiến lược phát hành đĩa đơn 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 thực hiện yêu cầu POST việc 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, thuộc tính này mặc định là GET, nhưng ở đây chúng ta sẽ 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 POST của bạn. Trong ví dụ này, Slack mong đợi một đối tượng được chuyển đổi tuần tự sang định dạng JSON như được mô tả trong Slack . Để làm được điều này, 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 tin nhắn đến vào Slack. Một mẫu mở rộng minh hoạ tạo và gửi Hiệu suất chiến dịch Báo cáo cho một nhóm cũng như một số tuỳ chọn định dạng và hiển thị.

Tin nhắn đến

Xem định dạng thông báo trong Slack để biết thêm thông tin chi tiết về thông báo của Slack.

Dữ liệu biểu mẫu

Ví dụ ở trên được minh hoạ bằng cách sử dụng một 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ẽ có 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ụ như 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ũng đượ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, tính năng tự động chuyển đổi từ đối tượng JavaScript sang dữ liệu biểu mẫu là một giải pháp hữu ích của chúng tôi.

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

HTTP cơ bản xác thực 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

Tạo yêu cầu

Bạn phải làm theo các bước sau đây để 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 với 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 một tiêu đề Authorization vào yêu cầu, ở dạng 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);

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

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

Plivo

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

  1. Đăng ký qua 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 trên trang tổng quan về việc 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 về .
  5. Để sử dụng Plivo, bạn phải mua số hoặc thêm số điện thoại vào gói dùng thử tài khoản. Thêm số Hộp cát có thể sẽ được sử dụng với tài khoản dùng thử.
  6. Thêm cả số điện thoại sẽ hiển thị dưới dạng người gửi và người nhận số.
  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ý. Thông tin này phải bao gồm mã quốc gia quốc tế, đối với ví dụ 447777123456 cho số ở Vương quốc Anh.

Twilio

Twilio là một dịch vụ khác hỗ trợ gửi và nhận tin nhắn SMS qua API của họ. Mẫu này minh hoạ quá trình gửi tin nhắn.

  1. Đăng ký bằng 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ố 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 dùng OAuth để xác thực. OAuth có một số phiên bản và phiên bản.

Trái lại 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 của 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 thông tin đăng nhập dành riêng cho tài khoản đó ứng dụng của 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 phần 6. Xác thực bằng OAuth. Ở chế độ ba chân đầy đủ OAuth 1.0, quy trình như sau:

  1. Ứng dụng ("Consumer") sẽ 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ã 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 sử dụng trong của bạn.

Đối với 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ụ: vì tập lệnh Google Ads sẽ yêu cầu), nên 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 cấu hình của chúng Play Console, cho phép ứng dụng chuyển trực tiếp đến bước 4. Tài khoản nà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ị cho dịch vụ, thông thường cần thiết để:

  • 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 cho tập lệnh.
  • Lấy Khoá truy cập, Khoá bí mật của người tiêu dùng, mã truy cập và khoá bí mật truy cập để sử dụng thông qua OAuth một bên.

OAuth 2.0

OAuth 2.0 được sử 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 cấp quyền sử dụng dịch vụ bên thứ ba cụ thể quyền truy cập vào các ứng dụng cụ thể để cho phép chúng truy cập dữ liệu người dùng. Chiến lược phát hành đĩa đơn có lợi thế là chủ sở hữu:

  • Họ 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 ứng dụng nào có quyền truy cập vào dữ liệu riêng lẻ và mức độ tác động. (Ví dụ: quyền truy cập được cấp có thể là quyền chỉ đọc hoặc chỉ cho tậ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, có một số các bước:

Ngoài tập lệnh của bạn

Cấp quyền cho các 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 của bên thứ ba. Trong hầu hết các trường hợp, việc này sẽ bao gồm thiết lập ứ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 các quyền truy cập cho ứng dụng Google Ads Script và thường sẽ được chỉ định một ID ứng dụng khách. Điều này cho phép bạn, thông qua OAuth 2 để kiểm soát ứ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áy chủ đã cho phép, nên một nhóm các bước khác (còn gọi là luồng) sẽ cần nhưng tất cả sẽ dẫn đến việc mã truy cập bị phát hành sẽ được sử dụng cho phiên đó cho tất cả các yêu cầu tiếp theo.

Đưa ra yêu cầu API. Truyền mã truy cập cho mỗi yêu cầu.

Quy trình uỷ quyền

Mỗi loại 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. Cho ví dụ: một luồng khác được sử dụng khi người dùng tham gia vào một tương tác khác với trường hợp ứng dụng yêu cầu phải chạy trong trong nền khi không có người dùng.

Nhà cung cấp API sẽ quyết định xem họ chấp nhận loại quyền nào và đây sẽ là 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 quy trình OAuth khác nhau, mục đích là lấy mã truy cập sau đó có thể được sử 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 flow khác nhau. Mỗi phương án trong số này phương thức trả về một đối tượng thu thập và lưu trữ mã truy cập, và hỗ trợ các yêu cầu được xác thực.

Mô hình 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 khách

Thông tin đăng nhập của ứng dụng khách đã được cấp một trong những dạng luồng OAuth2 đơn giản hơn, trong đó ứng dụng trao đổi Mã nhận dạng và khoá bí mật, duy nhất cho ứng dụng, để bù lại cho việc phát hành mã truy cập có giới hạn thời gian.

Thông tin đăng nhập của ứ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 trạng thái cấp 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 xác thực ứ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

Sự khác biệt với việc cấp mã làm mới là trong khi thông tin chi tiết cần thiết để cấp thông tin đăng nhập ứng dụng 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 như một phần của quy trình phức tạp hơn, chẳng hạn như mã uỷ quyền Cấp quyền truy cập 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

Sân chơi OAuth2 cung cấp 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ả các thông 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: Dùng với mã làm mới để lấy mã truy cập.
  • client ID and secret: Thông tin đăng nhập của ứng dụng.

Sân chơi OAuth

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

Một phương án thay thế dựa trên tập lệnh cho việc hoàn tất luồng có sẵn trong mã làm mới tạo mẫu.

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

Sau khi thực hiện yêu cầu uỷ quyền ban đầu, các dịch vụ có thể tiến hành làm mới mã sau đó có thể được dùng theo cách tương tự như quy trình xác thực ứng dụng khách. Dưới đâ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ề một 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 giá trị báo cáo. Hãy tham khảo bài viết Quảng cáo Tìm kiếm Tài liệu tham khảo API 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 được.

Tạo tập lệnh
  1. Tạo dự án mới trong Bảng điều khiển API, và lấy ID ứng dụng khách, mật khẩu ứng dụng khách và mã làm mới bằng cách thực hiện theo trong hướng dẫn DoubleClick, đảm bảo rằng bạn đã bật API DoubleClick Search.
  2. Dán mẫu thành một tập lệnh mới trong Google Ads.
  3. Dán OAuth2 mẫu thư viện bên dưới danh sách mã của mình.
  4. Sửa đổi tập lệnh để chứa các giá trị chính xác cho ID ứ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ạ cách thực thi một hàm trong Apps Script bằng thành phần Ứng dụng API thực thi tập lệnh. Thao tác này cho phép Apps Script được gọi 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 để điều hướng đế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à Drive API và Ứng dụng Thực thi tập lệnh .
  6. Tạo thông tin xác thực OAuth trong mục Credentials (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ừ Xuất bản > Triển khai dưới dạng API có thể thực thi.
Tạo tập lệnh Google Ads
  1. Dán mẫu tập lệnh thành một tập lệnh mới trong Google Ads.
  2. Ngoài ra, hãy dán OAuth2 mẫu thư viện bên dưới danh sách mã của mình.
  3. Sửa đổi tập lệnh để chứa các giá trị chính xác cho ID ứ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 lựa chọn thay thế cho các loại tài trợ ở trên là khái niệm dịch vụ tài khoản.

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

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

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

Ví dụ này minh hoạ cách tính bày tỏ 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ả. Điều này cung cấp một thước đo cho mức độ tích cực của thông điệp và tầm quan trọng của thông điệp: Điều nào tốt hơn, Chúng tôi bán bánh hoặc Chúng tôi bán các loại bánh ngon nhất ở London. Mua ngay hôm nay!?

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

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

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 là sử dụng JSON.parse để chuyển đổi chuỗi JSON thành JavaScript . Tại thời điểm này, bạn có thể xử lý trường hợp phân tích cú pháp thất bại:

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 xem xét 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 thực

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

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ệ do đó, nó không cung cấp khả năng xác thực XML dựa vào giản đồ.

Phần tử gốc

Sau khi phân tích cú pháp tài liệu XML thành công, phần tử gốc sẽ nhận được 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 những trận đấu đã chọn. Phản hồi XML nhận dưới đị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 đó, cần thiết để:

  • 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 truyền tải và truy cập các phần tử con.

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

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

Thu thập 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 nằm trong một phần tử bằng getText(), nhưng các thuộc tính này sẽ được nối khi có nhiều văn bản con của một phần tử. Cân nhắc bằng cách sử dụng getChildren() và lặp lại qua từng thành phần con trong trường hợp có nhiều thành phần con rất có thể trẻ em nhắn tin.

Ví dụ về Sportradar

Bản Sportradar đầy đủ này minh hoạ truy xuất thông tin chi tiết về các trận đấu bóng đá, cụ thể là giải Ngoại hạng Anh kết quả phù hợp. API bóng đá 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ý xong, 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 tách riêng các môn thể thao thành nhiều API. Ví dụ: bạn có thể mua quyền truy cập vào Soccer API nhưng không phải là API Tennis. Một Ứng dụng bạn tạo có thể liên quan đến nhiều môn thể thao khác nhau và các khoá khác nhau.

  1. Trong mục Ứng dụng, hãy nhấp vào Tạo ứng dụng mới. Gửi đơn đăng ký tên và nội dung mô tả, đồng thời bỏ qua trường trang web.
  2. Chỉ chọn mục Phát hành khoá mới cho Thử nghiệm bóng đá ở Châu Âu v2.
  3. Nhấp vào Đăng ký ứng dụng.

Sau khi thành công, thao tác này sẽ dẫn đến một trang có khoá API mới của bạn.

  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á nhận được ở trên, sau đó chỉnh sửa đị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 như ví dụ:

  • Các ứng dụng gửi yêu cầu đến máy chủ ở định dạng mà API không mong đợi.
  • Khách hàng mong muốn định dạng phản hồi khác với định dạng đã nhận được.
  • Khách hà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 tham số không hợp lệ.

Trong tất cả các trường hợp này cũng như các trường hợp khác, bước đầu tiên tốt để 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 (trạng thái mã từ 400 trở lên) sẽ mà công cụ tập lệnh Google Ads gửi.

Để ngăn chặn hành vi này và cho phép thông báo lỗi và thông báo lỗi đã kiểm tra, 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 phổ biến

  • 200 OK biểu thị thành công. Nếu phản hồi không chứa hãy lưu ý rằng:

    • Một số API cho phép chỉ định trường và/hoặc định dạng phản hồi 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 để xác định xem một tài nguyên khác có thể thích hợp để sử dụ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 hoặc nhà phát triển để biết rõ.

  • 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 và so sánh với quy cách của API để đảm bảo tuân thủ kỳ vọng của họ. 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 uỷ quyền thành công.

    • Nếu API sử dụng phương thức uỷ quyền cơ bản, hãy đảm bảo rằng tiêu đề Authorization đang được xây dựng 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 được cung cấp dưới dạng mã thông báo mang.
    • Đối với bất kỳ biến thể nào khác về việc uỷ quyền, hãy đảm bảo các thông tin cần thiết thông tin đăng nhập cho yêu cầu đang được cung cấp.

  • 403 Forbidden cho biết người dùng không có quyền đối với tài nguyên này đ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 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 rằng 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 đang được tham chiếu 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 các yêu cầu sẽ hữu ích khi phản hồi của API cho thấy yêu cầu không hiệu quả được tạo, ví dụ: mã trạng thái 400. Để giúp kiểm tra yêu cầu, hãy 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 đáng lẽ nên được gửi rồi trả lại. Đ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 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 được nối với nhau lỗi có thể nằm trong hàm bạn đã tạo để tạo 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 phần tử 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 cho API bên thứ ba, bạn có thể dùng hàm trợ giúp sau đây làm trình đơn thả xuống thay thế cho UrlFetchApp.fetch() để ghi nhật ký 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 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 của tất cả yêu cầu và phản hồi sẽ được ghi lại vào bảng điều khiển, cho phép gỡ lỗi dễ dàng hơn.