Định cấu hình chính sách ghi lại giao dịch

Bạn đang xem tài liệu về Apigee Edge.
Truy cập vào tài liệu Apigee X. thông tin

Định cấu hình chính sách ghi lại giao dịch cho từng sản phẩm API trong gói sản phẩm API của bạn, như mô tả trong các phần sau.

Giới thiệu

Chính sách ghi nhận giao dịch cho phép tính năng kiếm tiền nắm bắt các thông số giao dịch và thuộc tính tuỳ chỉnh. Hệ thống kiếm tiền cần thông tin này để thực hiện quy trình xử lý việc kiếm tiền, chẳng hạn như áp dụng kế hoạch giá.

Ví dụ: nếu bạn thiết lập một kế hoạch tỷ lệ chia sẻ doanh thu, thì một tỷ lệ phần trăm doanh thu được tạo từ mỗi giao dịch liên quan đến sản phẩm API có kiếm tiền của bạn sẽ được chia sẻ với nhà phát triển ứng dụng đưa ra yêu cầu. Phần chia sẻ doanh thu dựa trên giá ròng hoặc giá gộp của giao dịch (bạn chỉ định giá nào), tức là một tỷ lệ phần trăm của giá gộp hoặc giá ròng của mỗi giao dịch được dùng để xác định phần chia sẻ doanh thu. Do đó, tính năng kiếm tiền cần biết giá gộp hoặc giá ròng của một giao dịch (nếu có). Giá trị này lấy giá gộp hoặc giá ròng từ chế độ cài đặt mà bạn thực hiện trong chính sách ghi lại giao dịch.

Nếu thiết lập một kế hoạch bảng giá, trong đó bạn tính phí nhà phát triển cho mỗi giao dịch, thì bạn có thể đặt mức phí cho kế hoạch dựa trên một thuộc tính tùy chỉnh, chẳng hạn như số byte được truyền trong một giao dịch. Tính năng kiếm tiền cần biết thuộc tính tuỳ chỉnh là gì và cách tìm thuộc tính đó. Vì vậy, bạn cần chỉ định thuộc tính tùy chỉnh trong chính sách ghi lại giao dịch.

Ngoài việc chỉ định các thuộc tính giao dịch trong chính sách ghi lại giao dịch, bạn có thể chỉ định tiêu chí thành công của giao dịch để xác định thời điểm giao dịch thành công (cho mục đích tính phí). Để xem ví dụ về cách đặt tiêu chí thành công của giao dịch, hãy xem bài viết Ví dụ về cách đặt tiêu chí thành công của giao dịch trong chính sách ghi lại giao dịch. Bạn cũng có thể chỉ định các thuộc tính tuỳ chỉnh cho một sản phẩm API (dựa vào đó để tính phí gói giá).

Định cấu hình chính sách ghi lại giao dịch

Truy cập vào trang Gói sản phẩm, như mô tả bên dưới.

Định cấu hình thuộc tính giao dịch

Trong phần Thuộc tính giao dịch, hãy chỉ định các tiêu chí cho biết một giao dịch kiếm tiền thành công.

1. Trong trường Tiêu chí thành công của giao dịch, hãy chỉ định biểu thức dựa trên giá trị của thuộc tính Trạng thái (được mô tả tiếp theo) để xác định thời điểm giao dịch thành công (cho mục đích tính phí). Những giao dịch không thành công (tức là không đáp ứng tiêu chí trong biểu thức) sẽ được ghi lại, nhưng không áp dụng kế hoạch giá cho những giao dịch đó. Ví dụ:

   txProviderStatus == 'OK'

2. Thuộc tính Trạng thái chứa giá trị mà biểu thức dùng để định cấu hình trong trường Tiêu chí thành công của giao dịch. Định cấu hình thuộc tính Trạng thái bằng cách xác định các trường sau:

   Trường	Mô tả
   Tài nguyên API	Mẫu URI được xác định trong sản phẩm API sẽ được dùng để xác định các giao dịch được kiếm tiền.
   Vị trí phản hồi	Vị trí của phản hồi nơi thuộc tính được chỉ định. Các giá trị hợp lệ bao gồm: Biến luồng, Tiêu đề, Nội dung JSON và Nội dung XML.
   Giá trị	Giá trị của câu trả lời. Để chỉ định nhiều giá trị, hãy nhấp vào + Thêm x (ví dụ: + Thêm biến luồng).

3. Để định cấu hình các thuộc tính giao dịch không bắt buộc, hãy bật nút Sử dụng thuộc tính không bắt buộc rồi định cấu hình bất kỳ thuộc tính giao dịch nào được xác định trong bảng sau.

   Thuộc tính	Mô tả
   Giá gộp	Thuộc tính này chỉ áp dụng cho những gói giá sử dụng mô hình chia sẻ doanh thu. Đối với những gói giá đó, bạn bắt buộc phải cung cấp Giá gộp hoặc Giá ròng. Đảm bảo rằng giá trị số được biểu thị dưới dạng loại Chuỗi. Giá gộp của một giao dịch. Đối với các kế hoạch chia sẻ doanh thu, bạn cần ghi lại thuộc tính Giá gộp hoặc thuộc tính Giá ròng. Thuộc tính bắt buộc phụ thuộc vào cơ sở chia sẻ doanh thu. Ví dụ: bạn có thể thiết lập một kế hoạch tỷ lệ chia sẻ doanh thu dựa trên giá gộp của một giao dịch. Trong trường hợp đó, bạn phải điền vào trường Giá gộp.
   Giá tịnh	Thuộc tính này chỉ áp dụng cho những gói giá sử dụng mô hình chia sẻ doanh thu. Đối với những gói giá đó, bạn bắt buộc phải cung cấp Giá gộp hoặc Giá ròng. Đảm bảo rằng giá trị số được biểu thị dưới dạng loại Chuỗi. Giá ròng của một giao dịch. Đối với các kế hoạch chia sẻ doanh thu, bạn cần ghi lại trường Giá ròng hoặc trường Giá gộp. Trường nào là bắt buộc sẽ tuỳ thuộc vào cơ sở chia sẻ doanh thu. Ví dụ: bạn có thể thiết lập một kế hoạch tỷ lệ chia sẻ doanh thu dựa trên giá ròng của một giao dịch. Trong trường hợp đó, bạn phải điền vào trường Giá ròng.
   Đơn vị tiền tệ	Bạn phải sử dụng thuộc tính này cho những gói giá sử dụng mô hình chia sẻ doanh thu. Loại đơn vị tiền tệ áp dụng cho giao dịch.
   Mã lỗi	Mã lỗi liên quan đến giao dịch. Thông báo này cung cấp thêm thông tin về một giao dịch không thành công.
   Mô tả mặt hàng	Nội dung mô tả giao dịch.
   Thuế	Thuộc tính này chỉ liên quan đến các mô hình chia sẻ doanh thu và chỉ khi số tiền thuế được ghi lại trong các lệnh gọi API. Đảm bảo rằng giá trị số được biểu thị dưới dạng loại Chuỗi. Số tiền thuế khi mua hàng. Giá thực cộng thuế = giá gộp.

Ví dụ: bằng cách đặt các giá trị sau, hoạt động kiếm tiền sẽ nhận được giá trị của biến luồng từ phản hồi của thông báo trong một biến có tên là response.reason.phrase. Nếu giá trị là OK và chính sách Kiểm tra giới hạn kiếm tiền được đính kèm vào yêu cầu ProxyEndpoint của API proxy, thì tính năng kiếm tiền sẽ tính yêu cầu đó là một giao dịch.

Định cấu hình thuộc tính tuỳ chỉnh

Trong phần Thuộc tính tuỳ chỉnh, bạn xác định các thuộc tính tuỳ chỉnh cần đưa vào chính sách ghi lại giao dịch. Ví dụ: nếu thiết lập một gói bảng giá, trong đó bạn tính phí nhà phát triển cho mỗi giao dịch, bạn có thể đặt mức phí cho gói dựa trên một thuộc tính tùy chỉnh, chẳng hạn như số lượng byte được truyền trong một giao dịch. Sau đó, bạn cần thêm thuộc tính tùy chỉnh đó vào chính sách ghi lại giao dịch.

Mỗi thuộc tính này được lưu trữ trong nhật ký giao dịch mà bạn có thể truy vấn. Các thuộc tính này cũng xuất hiện khi bạn tạo một kế hoạch giá (để bạn có thể chọn một hoặc nhiều thuộc tính trong số này làm cơ sở để đặt giá cho kế hoạch).

Bạn có thể thêm các thuộc tính tuỳ chỉnh được xác định trong chính sách ghi lại giao dịch vào báo cáo tóm tắt doanh thu, như mô tả trong phần Thêm các thuộc tính giao dịch tuỳ chỉnh vào báo cáo tóm tắt doanh thu.

Để định cấu hình thuộc tính tuỳ chỉnh, hãy bật nút Sử dụng thuộc tính tuỳ chỉnh và xác định tối đa 10 thuộc tính tuỳ chỉnh. Đối với mỗi thuộc tính tùy chỉnh mà bạn đưa vào chính sách ghi lại giao dịch, bạn cần chỉ định thông tin sau.

Liên kết tài nguyên bằng mã giao dịch riêng biệt

Một số giao dịch rất đơn giản, chỉ cần một lệnh gọi API đến một tài nguyên. Tuy nhiên, các giao dịch khác có thể phức tạp hơn. Ví dụ: giả sử một giao dịch mua sản phẩm trong ứng dụng trong một ứng dụng trò chơi di động liên quan đến nhiều lệnh gọi tài nguyên:

• Một lệnh gọi đến API đặt trước để đảm bảo rằng người dùng trả trước có đủ tín dụng để mua sản phẩm và phân bổ ("đặt trước") tiền cho giao dịch mua.
• Một lệnh gọi đến API tính phí để khấu trừ tiền trong tài khoản trả trước của người dùng.

Để xử lý toàn bộ giao dịch, hoạt động kiếm tiền cần có cách liên kết tài nguyên đầu tiên (cuộc gọi và phản hồi đến và đi từ API đặt trước) với tài nguyên thứ hai (cuộc gọi và phản hồi đến và đi từ API tính phí). Để làm được việc này, bạn phải dựa vào thông tin mà bạn chỉ định trong phần Liên kết tài nguyên với mã giao dịch riêng biệt.

Để thiết lập thuộc tính tuỳ chỉnh, hãy bật nút Sử dụng mã giao dịch riêng biệt và liên kết các giao dịch. Đối với mỗi giao dịch, bạn chỉ định một tài nguyên, vị trí phản hồi và giá trị thuộc tính được liên kết với các giá trị tương ứng trong các giao dịch khác.

Ví dụ: giả sử lệnh gọi API đặt trước và lệnh gọi API tính phí được liên kết như sau: trường session_id trong tiêu đề phản hồi từ API đặt trước tương ứng với tiêu đề phản hồi reference_id từ API tính phí. Trong trường hợp này, bạn có thể đặt các mục trong phần Liên kết tài nguyên với mã giao dịch riêng biệt như sau:

Định cấu hình khoản tiền hoàn lại

Trong phần Hoàn tiền, bạn chỉ định các thuộc tính mà hoạt động kiếm tiền dùng để xử lý việc hoàn tiền.

Ví dụ: giả sử người dùng mua một sản phẩm từ một ứng dụng di động sử dụng các API được kiếm tiền của bạn. Giao dịch được kiếm tiền dựa trên kế hoạch chia sẻ doanh thu. Tuy nhiên, giả sử người dùng không hài lòng với sản phẩm và muốn trả lại sản phẩm. Nếu sản phẩm được hoàn tiền bằng cách gọi đến API của bạn để thực hiện việc hoàn tiền, thì tính năng kiếm tiền sẽ thực hiện các điều chỉnh cần thiết về việc kiếm tiền. Hệ thống sẽ thực hiện việc này dựa trên thông tin mà bạn chỉ định trong phần Tiền hoàn lại của chính sách ghi lại giao dịch.

Để thiết lập việc hoàn tiền, hãy bật nút Sử dụng thuộc tính hoàn tiền và xác định thông tin hoàn tiền:

1. Xác định tiêu chí hoàn tiền bằng cách xác định các trường sau:

   Trường	Mô tả
   Vị trí phản hồi	Tài nguyên cho giao dịch hoàn tiền. Nếu sản phẩm API cung cấp nhiều tài nguyên, bạn chỉ có thể chọn tài nguyên thực hiện việc hoàn tiền.
   Tiêu chí hoàn tiền thành công	Biểu thức dựa trên giá trị của thuộc tính Trạng thái (được mô tả tiếp theo) để xác định thời điểm giao dịch hoàn tiền thành công (cho mục đích tính phí). Những giao dịch hoàn tiền không thành công (tức là không đáp ứng các tiêu chí trong biểu thức) sẽ được ghi lại, nhưng không áp dụng kế hoạch giá cho những giao dịch đó. Ví dụ: txProviderStatus == 'OK'

2. Định cấu hình thuộc tính Trạng thái bằng cách xác định các trường sau:

   Trường	Mô tả
   Vị trí phản hồi	Vị trí của phản hồi nơi thuộc tính được chỉ định. Các giá trị hợp lệ bao gồm: Biến luồng, Tiêu đề, Nội dung JSON và Nội dung XML.
   Giá trị	Giá trị của câu trả lời. Để chỉ định nhiều giá trị, hãy nhấp vào + Thêm x (ví dụ: + Thêm biến luồng).

3. Định cấu hình thuộc tính Mã nhận dạng cấp trên bằng cách xác định các trường sau:

   Trường	Mô tả
   Vị trí phản hồi	Vị trí của phản hồi nơi thuộc tính được chỉ định. Các giá trị hợp lệ bao gồm: Biến luồng, Tiêu đề, Nội dung JSON và Nội dung XML.
   Giá trị	Mã giao dịch mà khoản tiền hoàn lại được xử lý. Ví dụ: nếu người dùng mua một sản phẩm rồi yêu cầu hoàn tiền, thì Mã giao dịch mẹ là mã của giao dịch mua. Để chỉ định nhiều giá trị, hãy nhấp vào + Thêm x (ví dụ: + Thêm biến luồng).

4. Để định cấu hình các thuộc tính không bắt buộc của khoản tiền hoàn lại, hãy bật nút Sử dụng thuộc tính không bắt buộc của khoản tiền hoàn lại rồi định cấu hình các thuộc tính. Các thuộc tính không bắt buộc của khoản tiền hoàn lại giống với các thuộc tính không bắt buộc của giao dịch, như được xác định trong phần Định cấu hình thuộc tính giao dịch.

Quản lý các chính sách ghi lại giao dịch bằng API

Các phần sau đây mô tả cách quản lý các chính sách ghi lại giao dịch bằng API.

Tạo chính sách ghi lại giao dịch bằng API

Bạn chỉ định chính sách ghi lại giao dịch dưới dạng một thuộc tính của sản phẩm API. Giá trị của thuộc tính xác định:

• Hậu tố URI của tài nguyên sản phẩm mà chính sách ghi lại giao dịch được đính kèm. Hậu tố này bao gồm một biến mẫu được đặt trong dấu ngoặc nhọn. Biến mẫu được các Dịch vụ API đánh giá trong thời gian chạy. Ví dụ: hậu tố URI sau đây có chứa biến mẫu {id}.

  /reserve/{id}**

  Trong trường hợp này, Dịch vụ API sẽ đánh giá hậu tố URI của tài nguyên là /reserve, theo sau là mọi thư mục con bắt đầu bằng một mã nhận dạng do nhà cung cấp API xác định.

• Tài nguyên trong phản hồi mà nó được đính kèm. Một sản phẩm API có thể có nhiều tài nguyên và mỗi tài nguyên có thể có một chính sách ghi lại giao dịch được đính kèm vào phản hồi từ tài nguyên đó.
• Một chính sách biến trích xuất cho phép chính sách ghi giao dịch trích xuất nội dung từ một thông báo phản hồi cho các tham số giao dịch mà bạn muốn ghi lại.

Bạn thêm thuộc tính chính sách ghi lại giao dịch vào một sản phẩm API bằng cách đưa ra yêu cầu PUT cho API quản lý https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (chứ không phải cho API kiếm tiền).

Chỉ định tiêu chí thành công của giao dịch bằng API

Bạn có thể chỉ định tiêu chí thành công của giao dịch để xác định thời điểm giao dịch thành công (cho mục đích tính phí). Những giao dịch không thành công (tức là không đáp ứng tiêu chí trong biểu thức) sẽ được ghi lại, nhưng không áp dụng kế hoạch giá cho những giao dịch đó. Để xem ví dụ về cách đặt tiêu chí thành công của giao dịch, hãy xem Ví dụ về cách đặt tiêu chí thành công của giao dịch trong chính sách ghi lại giao dịch.

Bạn chỉ định tiêu chí thành công của giao dịch dưới dạng một thuộc tính của sản phẩm API. Bạn có thể thực hiện việc này bằng cách đưa ra yêu cầu PUT đối với API quản lý https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (chứ không phải đối với API kiếm tiền).

Ví dụ: trong yêu cầu sau, một giao dịch sẽ thành công nếu giá trị của txProviderStatus là success (các quy cách liên quan đến tiêu chí thành công của giao dịch được làm nổi bật).

$ curl -H "Content-Type: application/json" -X PUT -d \ 
'{
        "apiResources": [
        "/reserve/{id}**"       
        ],
        "approvalType": "auto",
        "attributes": [                         
        {
                "name": "MINT_TRANSACTION_SUCCESS_CRITERIA",
                "value": "txProviderStatus == 'OK'"
        }
        ],
        "description": "Payment",
        "displayName": "Payment",
        "environments": [
        "dev"
        ],
        "name": "payment",
        "proxies": [],
        "scopes": [
        ""
        ]
}' \
"https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/payment" \
-u email:password

Chỉ định các thuộc tính tuỳ chỉnh bằng API

Bạn có thể chỉ định các thuộc tính tuỳ chỉnh cho một sản phẩm API mà bạn dựa vào đó để tính phí theo gói giá. Ví dụ: nếu thiết lập một gói thẻ giá, trong đó bạn tính phí nhà phát triển cho mỗi giao dịch, bạn có thể đặt mức giá cho gói dựa trên một thuộc tính tùy chỉnh, chẳng hạn như số byte được truyền trong một giao dịch. Khi tạo một kế hoạch giá, bạn có thể chỉ định một hoặc nhiều thuộc tính tuỳ chỉnh để làm cơ sở cho giá của kế hoạch. Tuy nhiên, bất kỳ sản phẩm cụ thể nào trong một gói giá chỉ có thể có một thuộc tính tuỳ chỉnh để dựa vào đó tính giá cho gói.

Bạn chỉ định các thuộc tính tuỳ chỉnh làm thuộc tính của một sản phẩm API. Hãy thực hiện việc này bằng cách gửi yêu cầu PUT đến API quản lý https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (chứ không phải đến API kiếm tiền).

Đối với mỗi thuộc tính tùy chỉnh mà bạn thêm vào một sản phẩm API, bạn cần chỉ định tên và giá trị thuộc tính. Tên phải có dạng MINT_CUSTOM_ATTRIBUTE_{num}, trong đó {num} là một số nguyên.

Ví dụ: yêu cầu sau đây chỉ định 3 thuộc tính tuỳ chỉnh.

$ curl -H "Content-Type: application/json" -X PUT -d \
'{
        "apiResources": [
        "/reserve/{id}**",
        "/charge/{id}**"
        ],
        "approvalType": "auto",
        "attributes": [
        {
                "name": "MINT_CUSTOM_ATTRIBUTE_1",
                "value": "test1"
        },
        {
                "name": "MINT_CUSTOM_ATTRIBUTE_2",
                "value": "test2"
        }
 
        ],
        "name": "payment",
        "proxies": [],
        "scopes": [
                ""
        ]
}' \
"https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/payment" \
-u email:password

Ví dụ về cách đặt tiêu chí thành công của giao dịch trong chính sách ghi lại giao dịch

Bảng sau đây cung cấp ví dụ về các giao dịch thành công và không thành công, dựa trên biểu thức tiêu chí thành công của giao dịch và giá trị txProviderStatus do proxy API trả về. txProviderStatus là biến nội bộ mà hoạt động kiếm tiền sử dụng để xác định giao dịch có thành công hay không.