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 trường hợp sử dụng mà toán tử muốn hỗ trợ, DPA phải triển khai kết hợp API Chia sẻ gói dữ liệu di động của Google và API Tác nhân gói dữ liệu. Tài liệu này mô tả API Tác nhân gói dữ liệu mà Google sẽ 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à gói dữ liệu mua.

Xác thực

Trước khi GTAF có thể gọi, DPA phải xác thực GTAF. Trong quá trình giới thiệu nhà cung cấp dịch vụ, 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 sử dụng OAuth2 để xác thực lẫn nhau.

Nội dung mô tả về API

GTAF sử dụng khoá người dùng để xác định thuê bao của toán tử khi truy vấn DPA của toán tử đó. Khi GTAF đang truy vấn DPA thay mặt 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, API Tác nhân gói dữ liệu đượ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 người dùng.
  2. Cơ chế truy vấn DPA cho các ưu đãi gói dữ liệu cho người dùng.
  3. Cơ chế thực hiện thay đổi đối với gói dữ liệu của người dùng (ví dụ: mua một 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ý các SSDSDN với DPA.
  6. Cơ chế GTAF để xác minh xem DPA có đang ở trạng thái hoạt động tốt hay không.

Phần còn lại của tài liệu này giải thích chi tiết về từng thành phần API này. Trừ phi có lưu ý rõ ràng, tất cả thông tin liên lạc PHẢI diễn ra qua HTTPS (có chứng chỉ DPA SSL hợp lệ). Tuỳ thuộc vào các tính năng thực tế được hỗ trợ, toán tử MAY sẽ chọn triển khai tất cả hoặc một nhóm nhỏ các 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 về gói dữ liệu người dùng.

Hình 4 minh hoạ quy trình gọi được liên kết với một ứng dụng truy vấn trạng thái gói dữ liệu của người dùng và các thông tin khác về gói dữ liệu. Quy trình 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. Máy khách yêu cầu 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 tới AFAF.
  2. GTAF sử dụng khoá người dùng và mã nhận dạng ứng dụng để truy vấn toán tử DPA của toán tử. Các giá trị nhận dạng khách hàng được hỗ trợ là mobiledataplan và youtube. Khi DPA nhận được cuộc gọi có một trong các giá trị nhận dạng ứng dụng này, bạn phải phản hồi bằng thông tin gói mà ứng dụng có thể sử dụng.
  3. GTAF trả về thông tin yêu cầu cho ứng dụng khách và thông tin gói được GTAF lưu vào bộ nhớ đệm cho đến thời điểm DPA chỉ định hết hạn.

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 để nhận trạng thái gói:

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

Ứng dụng mà GTAF đang liên hệ với DPA sẽ xác định bằng cách sử dụng CLIENT_ID. Tuỳ thuộc vào thoả thuận giữa ứng dụng khách và nhà mạng của Google, 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 biểu thị 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 SHALL bao gồm tiêu đề Accept-Language cho biết ngôn ngữ mà các chuỗi con người có thể đọc được (ví dụ: nội dung mô tả kế hoạch) phải thuộc ngôn ngữ đó.

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

Mỗi mô-đun gói có thể chứa nhiều Danh mục lưu lượng truy cập mô-đun kế hoạch (PMTCs)để lập mô hình 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 cho trò chơi và âm nhạc. Các PMTC sau đây được xác định trước: GENERIC, VIDEO, VIDEO_BROWSING, VIDEO_OFFLINE, MUSIC, GAMING, SOCIAL and MESSAGING. Theo dự kiến, các nhà vận hành sẽ liên hệ với từng nhóm Google để thống nhất về nhóm danh mục lưu lượng truy cập và ngữ nghĩa của các danh mục đó phù hợp với nhiều ứng dụng của Google.

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

GTAF đưa ra yêu cầu HTTP sau đây để nhận ưu đãi của gói từ nhà cung cấp dịch vụ:

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

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

Phần nội dung phản hồi chứa một thực thể 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ự trình bày các gói dữ liệu cho người dùng. Ngoài ra, nếu ứng dụng chỉ có thể hiển thị các kế hoạch x do giao diện người dùng hoặc các giới hạn khác và phản hồi chứa y > x chỉ lập kế hoạch các kế hoạch x đầu tiên SHALL. GTAF chỉ chia sẻ tối đa 10 gói nếu ứng dụng truy vấn ưu đãi là giao diện người dùng Gói dữ liệu di động thuộc Dịch vụ Google Play. Điều này giúp đảm bảo trải nghiệm người dùng tốt cho người dùng Dịch vụ Google Play.

Các chuỗi trong offerInfo nhằm cho phép người dùng đọc thêm về ưu đãi và cũng bao gồm cách để chọn không nhận thêm ưu đãi từ các ứng dụng bên trong. Lý do để có các trường này là vì một số nhà cung cấp dịch vụ 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à sẽ yêu cầu cơ chế chọn không cho phép người dùng chọn không sử dụng. Xin lưu ý rằng toán tử PHẢI có một cơ chế để thực hiện yêu cầu mua hàng đối với bất kỳ ưu đãi nào mở rộng cho người dùng. Cơ chế mà thông qua đó người dùng sẽ bị tính phí cho giao dịch mua có thể được thông báo bằng GTAF bằng cách sử dụng tuỳ chọn formOfPayment trong phản hồi.

Yêu cầu SHALL bao gồm tiêu đề Accept-Language cho biết ngôn ngữ mà các chuỗi con người có thể đọc được (ví dụ: nội dung mô tả kế hoạch) phải thuộc ngôn ngữ đó.

Mua dữ liệu

API kế hoạch mua hàng xác định cách GTAF có thể mua 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 SHALL bao gồm một mã nhận dạng giao dịch duy nhất (transactionId) để theo dõi các yêu cầu và tránh thực thi 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/không thành công.

Yêu cầu giao dịch

Sau khi nhận được yêu cầu từ khách hàng, GTAF sẽ gửi yêu cầu POST tới 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. Phần nội dung của 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 về giao dịch

DPA SHALL sẽ trả về các nguyên nhân phổ biến gây ra lỗi trong trường hợp xảy ra lỗi. Ngoài ra, những mã lỗi sau đây thể hiện những kết quả giao dịch không thành công:

  • DPA trả về mã lỗi YÊU CẦU BAD 400 để cho GTAF biết rằng mã gói đã mua không hợp lệ.
  • DPA trả về mã lỗi 402 PAYMENT bắt buộc 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 CONFLICT 409 cho GTAF biết rằng gói mà bạn mua sẽ 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 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, việc cố gắng mua gói trả trước cho người dùng trả sau sẽ dẫn đến lỗi CONFLICT 409.
  • DPA trả về mã lỗi 403 FORBIDDEN cho GTAF biết 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 đó. Mã DPA PHẢI trả về các nguyên nhân lỗi sau đây để phản hồi:
    • Nếu giao dịch trước đó là không thành công, thì lỗi sẽ cho biết lý do lỗi.
    • Nếu giao dịch trước đó thành công, DUPLICATE_TRANSACTION.
    • Nếu giao dịch trước đó vẫn đang chờ xử lý, REQUEST_QUEUED.

DPA SHALL chỉ tạo phản hồi 200 OK cho một giao dịch được thực thi thành công hoặc một giao dịch đã xếp hàng đợi. Trong trường hợp giao dịch đã đưa vào hàng đợi, DPA sẽ chỉ điền trạng thái giao dịch và để trống các trường khác trong nội dung phản hồi. DPA PHẢI gọi lại GTAF bằng một phản hồi sau khi hệ thống đã xử lý xong một giao dịch đã xếp hàng. Phần nội dung của phản hồi là một thực thể của transactionResponse bao gồm các 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 SHALL giả định rằng gói này đã được kích hoạt.

GTAF CÓ thể đưa ra yêu cầu sau đây để chuyển tùy chọn đồng ý của người dùng đến nhà mạng.

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

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

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

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

GTAF CÓ thể đưa ra yêu cầu sau đây để 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}

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

DPA SHALL sẽ trả về các nguyên nhân phổ biến gây ra lỗi trong trường hợp xảy ra lỗi. Ngoài ra, DPA SHALL trả về lỗi trong các trường hợp lỗi sau:

  • DPA trả về mã lỗi 400 BAD REQUEST cho GTAF biết rằng planId không hợp lệ.
  • DPA trả về mã lỗi CONFLICT 409 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 SHALL sẽ trả về phản hồi 200 OK. Định dạng của một EligibleResponse 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 bao gồm một planId, phản hồi chỉ bao gồm gói đó. Nếu không, danh sách 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ì PHẢI PHẢI trả về lỗi 400 BAD REQUEST.

Đ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 được phân phối bởi API Chia sẻ gói dữ liệu di động của Google, trong đó DPA gửi thông tin đến GTAF bằng các API của Google. Để đăng ký MSISDN, GTAF sẽ gửi yêu cầu POST tới DPA:

POST DPA_URL/đăng ký

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

{
  "msisdn": "<msisdn_string>"
}

Nếu đăng ký thành công của MSISDN thành công thì DPA PHẢI trả về phản hồi 200 OK, bao gồm registerResponse. Đị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 hết hạn expirationTime.

Nếu xảy ra lỗi, bạn sẽ 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ể xảy ra cho các điều kiện lỗi khác nhau tại đây. Cụ thể, nếu người dùng đang chuyển vùng hoặc không chọn chia sẻ thông tin gói dữ liệu với Google, thì yêu cầu đăng ký MSISDN phải trả về mã trạng thái HTTP 403.

API theo dõi

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 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 theo dõi.

Định nghĩa API

API theo dõi 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ả phụ trợ của DPA đang hoạt động chính xác thì DPA phải phản hồi truy vấn này bằng mã trạng thái HTTP 200 và nội dung phản hồi có một bản sao 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 hoạt động này hoạt động không đúng cách, thì DPA phải phản hồi bằng mã trạng thái HTTP 500 và nội dung phản hồi có bản sao của DpaStatus.

Hành vi của DPA

Khi phát hiện lỗi, DPA phải trả về trạng thái "UNAVAILABLE" cho tất cả truy vấn dpaStatus. Ngoài ra, tài khoản này phải ngừng gửi thông tin về gói dữ liệu với khoảng thời gian lưu vào bộ nhớ đệm dài. Bạn 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 ngắn cho bộ nhớ đệm.
  2. Ngừng gửi toàn bộ thông tin về gói dữ liệu.

Hành vi GTAF

GTAF sẽ định kỳ thăm dò ý kiến dpaStatus. Khi phát hiện lỗi DPA (dựa trên phản hồi "UNAVAILABLE"), ứng dụng sẽ xoá bộ nhớ đệm của 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ã trạng thái HTTP tương ứng với một trong các loại sau:

  • Người dùng hiện đang chuyển vùng và truy vấn DPA đã bị tắt đối với người dùng này. DPA trả về lỗi 403.
  • DPA trả về mã lỗi 404 NOT_LOOK cho biết GTAF biết rằng khoá người dùng không hợp lệ (tức là khoá người dùng không tồn tại).
  • DPA sẽ trả về mã lỗi GONE 410 cho biết GTAF rằng ứng dụng sẽ nhận được khóa của 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 mã này không hỗ trợ lệnh gọi này.
  • Dịch vụ tạm thời không khả dụng. DPA sẽ trả về một DỊCH VỤ 503 KHÔNG DÙNG ĐƯỢC với tiêu đề Thử lại sau khi cho biết thời điểm có thể thực hiện một yêu cầu mới.
  • DPA sẽ trả về mã lỗi 500 LỖI MÁY CHỦ NỘI BỘ cho tất cả các lỗi khác không xác định.
  • DPA trả về lỗi 429 TOO_MANY_ nghĩa là có tiêu đề Thử lại sau khi cho biết GTAF đang gửi quá nhiều yêu cầu đến DPA.
  • DPA trả về lỗi CONFLICT 409 cho biết không thể hoàn thành yêu cầu do có 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, phần nội dung của phản hồi HTTP PHẢI bao gồm đối tượng JSON kèm theo thêm thông tin về lỗi. Phần nội dung phản hồi lỗi PHẢI chứa một bản sao của ErrorResponse.

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

Các giá trị cause hiện đã được xác định là một phần của tệp đối chiếu ErrorError.

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

Quốc tế hóa

Các yêu cầu GTAF gửi tới DPA bao gồm tiêu đề Chấp nhận ngôn ngữ cho biết ngôn ngữ mà các chuỗi con người có thể đọc được (ví dụ: nội dung mô tả kế hoạch) phải thuộc ngôn ngữ đó. Ngoài ra, 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ụ: "vi-VN") 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 đó.