API tác nhân gói dữ liệu

Động lực

Như đã đề cập trong phần tổng quan, tuỳ thuộc vào các trường hợp sử dụng mà nhà mạng muốn hỗ trợ, DPA phải triển khai kết hợp Google Mobile Data Plan Sharing API và Data Plan Agent API. Tài liệu này mô tả Data Plan Agent API mà Google sẽ dùng để xác định gói dữ liệu di động của người dùng, truy xuất thông tin về các gói này và mua gói dữ liệu.

Xác thực

Trước khi GTAF có thể gọi, DPA phải xác thực GTAF. Trong quy trình tham gia của nhà mạng, chúng tôi sẽ kiểm tra tính hợp lệ của chứng chỉ SSL DPA. Hiện tại, chúng tôi YÊU CẦU bạn sử dụng OAuth2 để xác thực lẫn nhau.

Nội dung mô tả API

GTAF sử dụng khoá người dùng (khoá này xác định một người đăng ký với nhà khai thác) khi truy vấn DPA của nhà khai thác. Khi GTAF truy vấn DPA thay cho các ứng dụng có quyền truy cập vào MSISDN, GTAF CÓ THỂ sử dụng MSISDN. Ở cấp độ cao, Data Plan Agent API được đề xuất bao gồm các thành phần sau:

  1. Cơ chế truy vấn trạng thái gói dữ liệu của người dùng.
  2. Cơ chế truy vấn DPA để biết các gói dữ liệu dành cho người dùng.
  3. Cơ chế để thay đổi gói dữ liệu của người dùng (ví dụ: mua gói mới).
  4. Cơ chế xác minh xem người dùng có đủ điều kiện mua một gói dữ liệu cụ thể hay không.
  5. Cơ chế để GTAF đăng ký MSISDN với DPA.
  6. Cơ chế để GTAF xác minh xem DPA có ở trạng thái tốt hay không.

Phần còn lại của tài liệu này sẽ trình bày chi tiết về từng thành phần API này. Trừ phi có ghi chú rõ ràng, tất cả hoạt động giao tiếp PHẢI diễn ra qua HTTPS (với chứng chỉ SSL DPA hợp lệ). Tuỳ thuộc vào các tính năng thực tế được hỗ trợ, nhà mạng CÓ THỂ chọn triển khai tất cả hoặc một số thành phần API này.

Truy vấn trạng thái gói dữ liệu

Tương tác GTAF-DPA

Tương tác GTAF-DPA

Hình 4. Luồng cuộc gọi để yêu cầu và nhận thông tin gói dữ liệu của người dùng.

Hình 4 minh hoạ quy trình gọi liên quan đến một ứng dụng đang truy vấn về trạng thái gói dữ liệu của người dùng và thông tin khác về gói dữ liệu. Luồng cuộc gọi này được chia sẻ cho các lệnh gọi API do ứng dụng kích hoạt trên UE.

  1. Ứng dụng khách yêu cầu thông tin về trạng thái gói dữ liệu và/hoặc thông tin khác bằng cách gọi một API riêng tư của Google. Ứng dụng bao gồm khoá người dùng trong yêu cầu gửi đến GTAF.
  2. GTAF sử dụng khoá người dùng và giá trị nhận dạng ứng dụng để truy vấn DPA của nhà mạng. Giá trị nhận dạng ứng dụng khách được hỗ trợ là mobiledataplan và youtube. Khi nhận được một lệnh gọi có một trong các giá trị nhận dạng ứng dụng này, DPA PHẢI phản hồi bằng thông tin kế hoạch mà ứng dụng có thể sử dụng.
  3. GTAF trả về thông tin được yêu cầu cho máy khách và thông tin kế hoạch được GTAF lưu vào bộ nhớ đệm cho đến thời gian hết hạn do DPA chỉ định.

Các bước 1 và 3 trong Hình 4 là các API riêng tư của Google và do đó không được mô tả thêm. Bước 2 là một API công khai được mô tả sau đây. DPA PHẢI tuân thủ tiêu đề HTTP Cache-Control: no-cache khi phân phát các lệnh gọi API này từ GTAF.

Trạng thái kế hoạch

GTAF đưa ra yêu cầu HTTP sau đây để lấy trạng thái kế hoạch:

GET DPA_URL/{userKey}/planStatus?key_type={CPID,MSISDN}&client_id=CLIENT_ID

Ứng dụng thay mặt cho GTAF liên hệ với DPA được xác định bằng CLIENT_ID. Tuỳ thuộc vào thoả thuận giữa ứng dụng Google và hãng vận chuyển, DPA có thể tuỳ chỉnh phản hồi cho GTAF. Định dạng của phản hồi là một đối tượng JSON đại diện cho PlanStatus.

{
  "plans": [{
    "planName": "ACME1",
    "planId": "1",
    "planCategory": "PREPAID",
    "expirationTime": "2017-01-29T01:00:03.14159Z", // req.
    "planModules": [{
      "moduleName": "Giga Plan", // req.
      "trafficCategories": ["GENERIC"],
      "expirationTime": "2017-01-29T01:00:03.14159Z", // req.
      "overUsagePolicy": "BLOCKED",
      "maxRateKbps": "1500",
      "description": "1GB for a month", // req.
      "coarseBalanceLevel": "HIGH_QUOTA"
    }]
  }],
  "languageCode": "en-US", // req.
  "expireTime": "2018-06-14T08:41:27-07:00", // req.
  "updateTime": "2018-06-07T07:41:22-07:00", // req.
  "title": "Prepaid Plan"
  "planInfoPerClient": {
    "youtube": {
      "rateLimitedStreaming": {
        "maxMediaRateKbps": 256
      }
    }
  }
}

Yêu cầu PHẢI bao gồm một tiêu đề Accept-Language cho biết ngôn ngữ mà các chuỗi ký tự mà con người đọc được (ví dụ: nội dung mô tả gói) phải có.

Đối với gói trả sau, expirationTime PHẢI là ngày lặp lại của gói (tức là khi số dư dữ liệu được làm mới/tải lại).

Mỗi mô-đun kế hoạch có thể chứa nhiều Danh mục lưu lượng truy cập của mô-đun kế hoạch (PMTCs) để mô hình hoá trường hợp một mô-đun kế hoạch được chia sẻ giữa nhiều ứng dụng (ví dụ: 500 MB đối với trò chơi và nhạc). Các PMTC sau đây được xác định trước: GENERIC, VIDEO, VIDEO_BROWSING, VIDEO_OFFLINE, MUSIC, GAMING, SOCIAL and MESSAGING. Các nhà khai thác dự kiến sẽ liên hệ với từng nhóm tại Google để thoả thuận về bộ danh mục lưu lượng truy cập và ngữ nghĩa của các danh mục đó có liên quan đến các ứng dụng khác nhau của Google.

Truy vấn các ưu đãi trong gói

GTAF gửi yêu cầu HTTP sau đây để nhận các ưu đãi về kế hoạch của nhà điều hành:

GET DPA_URL/{userKey}/planOffer?key_type={CPID,MSISDN}&client_id=CLIENT_ID&context={purchaseContext}

Ứng dụng thay mặt cho GTAF liên hệ với DPA được xác định bằng CLIENT_ID. Tuỳ thuộc vào thoả thuận giữa ứng dụng Google và hãng vận chuyển, DPA có thể tuỳ chỉnh phản hồi cho GTAF. Tham số ngữ cảnh không bắt buộc cung cấp ngữ cảnh ứng dụng mà yêu cầu được thực hiện. Đây thường là một chuỗi mà ứng dụng truyền đến nhà mạng thông qua GTAF.

Nội dung phản hồi chứa một phiên bản của PlanOffer.

{
    "offers": [
      {
        "planName": "ACME Red", // req.
        "planId": "turbulent1", // req.
        "planDescription": "Unlimited Videos for 30 days.", // req.
        "promoMessage": "Binge watch videos.",
        "languageCode": "en_US", // req.
        "overusagePolicy": "BLOCKED",
        "cost": { // req.
          "currencyCode": "INR",
          "units": "300",
          "nanos": 0
        },
        "duration": "2592000s",
        "offerContext": "YouTube",
        "trafficCategories": ["VIDEO"],
        "quotaBytes": "9223372036850"
      }
    ],
    "expireTime": "2019-03-04T00:06:07Z" // req.
}

Thứ tự của(các) gói dữ liệu trong mảng offers CÓ THỂ xác định thứ tự mà(các) gói dữ liệu được trình bày cho người dùng. Ngoài ra, nếu ứng dụng chỉ có thể trình bày x gói do giao diện người dùng hoặc các hạn chế khác và phản hồi chỉ chứa y > x gói thì chỉ x gói đầu tiên được trình bày. GTAF chỉ chia sẻ tối đa 10 gói nếu ứng dụng truy vấn các ưu đãi là Giao diện người dùng gói dữ liệu di động (một phần của Dịch vụ Google Play). Điều này nhằm đảm bảo người dùng Dịch vụ Google Play có trải nghiệm tốt.

Các chuỗi trong offerInfo nhằm mục đích cho phép người dùng đọc thêm về ưu đãi, đồng thời cung cấp cách chọn không nhận thêm ưu đãi từ bên trong ứng dụng. Lý do cần có các trường này là vì một số nhà mạng không cần có sự đồng ý của người dùng cuối để cho phép mua hàng trong ứng dụng mà chỉ cần một cơ chế để người dùng chọn không sử dụng. Xin lưu ý rằng nhà cung cấp dịch vụ PHẢI có một cơ chế để thực hiện yêu cầu mua đối với mọi ưu đãi được cung cấp cho người dùng. Bạn có thể trao đổi với GTAF về cơ chế mà người dùng sẽ bị tính phí cho mọi giao dịch mua bằng cách sử dụng lựa chọn formOfPayment trong phản hồi.

Yêu cầu PHẢI bao gồm một tiêu đề Accept-Language cho biết ngôn ngữ mà các chuỗi ký tự mà con người đọc được (ví dụ: nội dung mô tả gói) phải có.

Mua dữ liệu

API kế hoạch mua hàng xác định cách GTAF có thể mua các kế hoạch thông qua DPA. GTAF bắt đầu giao dịch mua một gói dữ liệu cho DPA. Yêu cầu PHẢI bao gồm một giá trị nhận dạng giao dịch riêng biệt (transactionId) để theo dõi các yêu cầu và tránh thực hiện giao dịch trùng lặp. DPA PHẢI phản hồi bằng một phản hồi thành công/thất bại.

Yêu cầu giao dịch

Sau khi nhận được yêu cầu từ một khách hàng, GTAF sẽ gửi một yêu cầu POST đến DPA. URL của yêu cầu là:

POST DPA_URL/{userKey}/purchasePlan?key_type={CPID,MSISDN}&client_id=CLIENT_ID

trong đó userKey là CPID hoặc MSISDN. Nội dung yêu cầu là một phiên bản của TransactionRequest, bao gồm các trường sau:

{
  "planId": string,         // Id of plan to be purchased. Copied from
                            // offers.planId field returned from a
                            // Upsell Offer request,
                            // if available. (req.).
  "transactionId": string,  // Unique request identifier (req.)
  "offerContext": string,   // Copied from from the
                            // offers.offerContext, if available.
                            // (opt.)
  "callbackUrl": string     // URL that the DPA can call back with response once
                            // it has handled the request.
}

Phản hồi giao dịch

DPA PHẢI trả về các nguyên nhân thường gặp gây ra lỗi trong trường hợp xảy ra lỗi. Ngoài ra, các mã lỗi sau đây biểu thị kết quả giao dịch không thành công:

  • DPA trả về mã lỗi 400 BAD REQUEST (YÊU CẦU KHÔNG HỢP LỆ) cho GTAF biết rằng mã gói đã mua không hợp lệ.
  • DPA trả về mã lỗi 402 PAYMENT REQUIRED (YÊU CẦU THANH TOÁN) cho GTAF biết rằng người dùng không có đủ số dư để hoàn tất giao dịch mua.
  • DPA trả về mã lỗi 409 CONFLICT (XUNG ĐỘT) cho GTAF, cho biết rằng gói cần mua không tương thích với tổ hợp sản phẩm hiện tại của người dùng. Ví dụ: nếu chính sách về gói dữ liệu của nhà mạng không cho phép kết hợp gói trả sau và gói trả trước, thì việc cố gắng mua gói trả trước cho người dùng trả sau sẽ dẫn đến lỗi 409 CONFLICT.
  • DPA trả về mã lỗi 403 BỊ CẤM, cho biết cho GTAF rằng giao dịch hiện tại là bản sao của một giao dịch đã phát hành trước đó. DPA PHẢI trả về các nguyên nhân gây ra lỗi sau đây để phản hồi:
    • Nếu giao dịch trước đó không thành công, nguyên nhân gây ra lỗi sẽ cho biết lý do khiến giao dịch không thành công.
    • Nếu giao dịch trước đó thành công, DUPLICATE_TRANSACTION.
    • Nếu giao dịch trước đó vẫn đang trong hàng đợi, REQUEST_QUEUED.

DPA CHỈ ĐƯỢC tạo phản hồi 200-OK cho giao dịch được thực hiện thành công hoặc giao dịch được xếp hàng. Trong trường hợp giao dịch được xếp hàng, DPA chỉ điền trạng thái giao dịch và để trống các trường khác trong phản hồi. DPA PHẢI gọi lại GTAF bằng một phản hồi sau khi giao dịch trong hàng đợi được xử lý. Nội dung phản hồi là một phiên bản của TransactionResponse, bao gồm những thông tin chi tiết sau:

{
  "transactionStatus": "SUCCESS",

  "purchase": {
    "planId": string,               // copied from request. (req.)
    "transactionId": string,        // copied from request. (req.)
    "transactionMessage": string,   // status message. (opt.)
    "confirmationCode": string,     // DPA-generated confirmation code
                                    // for successful transaction. (opt.)
    "planActivationTime" : string,  // Time when plan will be activated,
                                    // in timestamp format. (opt.)
  },

  // walletInfo is populated with the balance left in the user's account.
  "walletBalance": {
    "currencyCode": string,       // 3-letter currency code defined in ISO 4217.
    "units": string,              // Whole units of the currency amount.
    "nanos": number               // Number of nano units of the amount.
  }
}

Nếu thiếu planActivationTime, GTAF PHẢI giả định rằng gói đã được kích hoạt.

GTAF CÓ THỂ đưa ra yêu cầu sau để chuyển lựa chọn ưu tiên về sự đồng ý của người dùng cho hãng vận chuyển.

POST DPA_URL/{userKey}/consent?key_type={CPID,MSISDN}&client_id=CLIENT_ID

trong đó userKey là CPID hoặc MSISDN. Nội dung yêu cầu là một phiên bản của SetConsentStatusRequest.

Nếu thành công, nội dung phản hồi sẽ trống.

Điều kiện sử dụng

GTAF CÓ THỂ đưa ra yêu cầu sau đây về điều kiện để kiểm tra xem người dùng có đủ điều kiện mua gói hay không.

GET DPA/{userKey}/Eligibility/{planId}?key_type={CPID,MSISDN}

Xin lưu ý rằng planId là giá trị nhận dạng duy nhất của gói mà bạn có thể dùng để mua gói thay cho người dùng (Xem phần Mua dữ liệu). Nếu bạn không chỉ định planId, thì DPA PHẢI trả về tất cả các gói mà người dùng đó có thể mua.

DPA PHẢI trả về các nguyên nhân thường gặp gây ra lỗi trong trường hợp xảy ra lỗi. Ngoài ra, DPA PHẢI trả về lỗi trong các trường hợp lỗi sau:

  • DPA trả về mã lỗi 400 YÊU CẦU KHÔNG HỢP LỆ, cho biết với GTAF rằng planId không hợp lệ.
  • DPA trả về mã lỗi 409 CONFLICT (XUNG ĐỘT) cho biết planId không tương thích với gói dữ liệu của người dùng.

Nếu không, DPA PHẢI trả về phản hồi 200-OK. Định dạng của một EligibilityResponse thành công là:

{
  "eligiblePlans":
  [
   {
    "planId": string,   // Plan identifier. Can be used to
                        // refer to the plan during
                        // offers, etc. (req.)
   }
  ]
}

Khi yêu cầu có một planId, phản hồi sẽ chỉ bao gồm kế hoạch đó. Nếu không, danh sách này sẽ bao gồm tất cả các gói mà người dùng đủ điều kiện mua. Trong trường hợp planId trống và DPA không hỗ trợ trả về danh sách các gói đủ điều kiện, thì DPA PHẢI trả về lỗi 400 YÊU CẦU KHÔNG HỢP LỆ.

Điểm cuối đăng ký MSISDN

Để phân phát các ứng dụng có quyền truy cập vào MSISDN, GTAF sẽ đăng ký MSISDN với DPA. GTAF chỉ đăng ký MSISDN khi có các ứng dụng do Google Mobile Data Plan Sharing API cung cấp, trong đó DPA gửi thông tin đến GTAF bằng Google API. Để đăng ký MSISDN, GTAF sẽ gửi yêu cầu POST đến DPA:

POST DPA_URL/register

Nội dung yêu cầu sẽ là một phiên bản của RegistrationRequest.

{
  "msisdn": "<msisdn_string>"
}

Nếu đăng ký MSISDN thành công, thì DPA PHẢI trả về phản hồi 200 OK, bao gồm RegistrationResponse. Định dạng của JSON là:

{
  // msisdn that was registered.
  "msisdn": "<msisdn_string>",
  // time after which DPA will not send updates to GTAF.
  "expirationTime": string
}

Sau đó, DPA PHẢI gửi thông tin cập nhật về gói dữ liệu của người dùng cho GTAF cho đến khi expirationTime hết hạn.

Nếu xảy ra lỗi, bạn nên trả về một ErrorResponse:

{
    "error": "<error message>",
    "cause": enum(ErrorCause)
}

Bạn có thể xem danh sách đầy đủ các giá trị nguyên nhân và mã trạng thái HTTP có thể có cho các điều kiện lỗi khác nhau tại đây. Cụ thể, nếu nhận được yêu cầu đăng ký MSISDN cho một người dùng đang chuyển vùng hoặc chưa chọn chia sẻ thông tin gói dữ liệu với Google, thì DPA PHẢI trả về mã trạng thái HTTP 403.

Monitoring API

Một số trường hợp sử dụng yêu cầu GTAF giám sát DPA và phát hiện các lỗi DPA. Đối với những trường hợp sử dụng đó, chúng tôi đã xác định một API giám sát.

Định nghĩa API

API giám sát phải có sẵn thông qua yêu cầu HTTP GET tại URL sau:

DPA_URL/dpaStatus

Nếu DPA và tất cả các phần phụ trợ của DPA đang hoạt động bình thường, thì DPA sẽ phản hồi truy vấn này bằng mã trạng thái HTTP 200 và một nội dung phản hồi có một phiên bản của DpaStatus.

{
    "status": enum(DpaStatusEnum),
    "message": "<optional human-readable status description>"
}

Nếu DPA hoặc bất kỳ phần phụ trợ nào của DPA không hoạt động đúng cách, thì DPA sẽ phản hồi bằng mã trạng thái HTTP 500 và một phần nội dung phản hồi có một phiên bản DpaStatus.

Hành vi của DPA

Khi phát hiện thấy lỗi, DPA phải trả về trạng thái "UNAVAILABLE" (KHÔNG CÓ SẴN) cho tất cả các truy vấn dpaStatus. Ngoài ra, ứng dụng phải ngừng gửi thông tin về gói dữ liệu có thời gian lưu vào bộ nhớ đệm dài. Máy chủ có thể ngừng gửi phản hồi có thời gian lưu vào bộ nhớ đệm dài theo một trong hai cách:

  1. Bắt đầu đặt thời gian hết hạn bộ nhớ đệm ngắn.
  2. Ngừng hoàn toàn việc gửi thông tin về gói dữ liệu.

Hành vi của GTAF

GTAF sẽ định kỳ kiểm tra dpaStatus. Khi phát hiện thấy lỗi DPA (dựa trên phản hồi "UNAVAILABLE"), nó sẽ xoá bộ nhớ đệm cho toán tử.

Các trường hợp lỗi

Trong trường hợp xảy ra lỗi, DPA dự kiến sẽ trả về một mã trạng thái HTTP tương ứng với một trong những mã sau:

  • Người dùng hiện đang chuyển vùng và truy vấn DPA bị vô hiệu hoá đối với người dùng này. DPA trả về lỗi 403.
  • DPA trả về mã lỗi 404 NOT_FOUND, cho biết với GTAF rằng userkey không hợp lệ (tức là userkey không tồn tại).
  • DPA trả về mã lỗi 410 GONE, cho biết cho GTAF rằng ứng dụng khách sẽ nhận được một khoá người dùng mới nếu key_type = CPID và CPID đã hết hạn.
  • DPA trả về mã lỗi 501 NOT_IMPLEMENTED cho biết rằng DPA không hỗ trợ lệnh gọi này.
  • Dịch vụ tạm thời không hoạt động. DPA trả về thông báo 503 SERVICE UNAVAILABLE (DỊCH VỤ KHÔNG HOẠT ĐỘNG) kèm theo tiêu đề Retry-After (Thử lại sau) cho biết thời điểm có thể thử một yêu cầu mới.
  • DPA trả về mã lỗi 500 INTERNAL SERVER ERROR cho tất cả các lỗi không xác định khác.
  • DPA trả về lỗi 429 TOO_MANY_REQUESTS (QUÁ NHIỀU YÊU CẦU) kèm theo tiêu đề Retry-After (Thử lại sau) cho biết GTAF đang gửi quá nhiều yêu cầu đến DPA.
  • DPA trả về lỗi 409 CONFLICT (XUNG ĐỘT), cho biết không thể hoàn tất yêu cầu do xung đột với trạng thái hiện tại của DPA.

Trong tất cả các trường hợp lỗi, nội dung của phản hồi HTTP PHẢI bao gồm một đối tượng JSON có thêm thông tin về lỗi. Nội dung phản hồi lỗi PHẢI chứa một phiên bản của ErrorResponse.

{
  "error": string,
  "cause": enum(ErrorCause)
}

Các giá trị cause hiện được xác định được liệt kê trong phần tham chiếu API ErrorCause.

Nếu không, DPA sẽ trả về trạng thái 200 OK. Xin lưu ý rằng các giá trị cause này được dùng cho tất cả các phản hồi.

Quốc tế hoá

Các yêu cầu GTAF gửi đến DPA bao gồm một tiêu đề Accept-Language cho biết ngôn ngữ mà các chuỗi dễ đọc (ví dụ: nội dung mô tả kế hoạch) phải có. Ngoài ra, các phản hồi DPA (PlanStatus, PlanOffers) bao gồm một trường languageCode bắt buộc có giá trị là mã ngôn ngữ BCP-47 (ví dụ: "en-US") của phản hồi.

Nếu DPA không hỗ trợ ngôn ngữ mà người dùng yêu cầu, thì DPA có thể sử dụng ngôn ngữ mặc định và sử dụng trường languageCode để cho biết lựa chọn của mình.