Chính sách về chú thích cho phần mở rộng

Bạn đang xem tài liệu về Apigee Edge.
Chuyển đến tài liệu về Apigee X. thông tin

Sử dụng Chính sách Chú thích mở rộng để kết hợp tiện ích vào proxy API.

Một tiện ích cho phép truy cập vào một tài nguyên cụ thể bên ngoài Apigee Edge. Tài nguyên có thể là các dịch vụ của Google Cloud Platform như Cloud Storage hoặc Giải pháp chuyển lời nói thành văn bản của Cloud. Tuy nhiên, tài nguyên có thể là bất kỳ tài nguyên bên ngoài nào có thể truy cập được qua HTTP hoặc HTTPS.

Để biết tổng quan về tiện ích, hãy xem bài viết Tiện ích là gì? Để xem hướng dẫn giới thiệu, hãy xem Hướng dẫn: Thêm và sử dụng tiện ích.

Trước khi sử dụng một tiện ích thông qua chính sách Chú thích mở rộng, bạn phải thêm, định cấu hình và triển khai tiện ích này qua một gói tiện ích đã được cài đặt vào tổ chức Apigee Edge.

Mẫu

Dưới đây là chính sách mẫu về cách sử dụng cùng tiện ích Ghi nhật ký trên đám mây:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="false" enabled="true" name="Logging-Extension">
        <DisplayName>Logging Extension</DisplayName>
        <Connector>cloud-extension-sample</Connector>
        <Action>log</Action>
        <Input>{
                "logName" : "example-log",
                "metadata" : "test-metadata",
                "message" : "This is a test"
        }</Input>
    <Output>cloud-extension-example-log</Output>
</ConnectorCallout>

Hãy xem phần Hướng dẫn: Sử dụng tiện ích để biết hướng dẫn đầy đủ về cách sử dụng tiện ích Ghi nhật ký trên đám mây.

Để biết ví dụ về tất cả các tiện ích hiện có, hãy xem bài viết Tổng quan về tài liệu tham khảo về tiện ích.

Giới thiệu về Chính sách chú thích mở rộng

Sử dụng Chính sách chú thích tiện ích khi bạn muốn sử dụng một tiện ích đã định cấu hình để truy cập vào tài nguyên bên ngoài từ bên trong proxy API.

Trước khi sử dụng chính sách này, bạn sẽ cần:

  • Một số thông tin chi tiết về tài nguyên bên ngoài mà bạn muốn truy cập trong chính sách này. Những thông tin chi tiết này sẽ dành riêng cho tài nguyên đó. Ví dụ: nếu chính sách này cho phép truy cập vào cơ sở dữ liệu Cloud Firestore của bạn, thì bạn sẽ cần phải biết bộ sưu tập và tên tài liệu mà bạn muốn tạo hoặc truy cập. Thông thường, bạn sẽ sử dụng thông tin cụ thể về tài nguyên khi định cấu hình quá trình xử lý yêu cầu và phản hồi của chính sách này.
  • Một tiện ích đã thêm, định cấu hình và triển khai vào môi trường nơi proxy API của bạn sẽ được triển khai. Nói cách khác, nếu bạn định sử dụng chính sách này để truy cập vào một dịch vụ cụ thể của Google Cloud, thì tiện ích đã triển khai cho dịch vụ đó phải tồn tại trong môi trường của bạn. Thông tin cấu hình thường bao gồm thông tin bắt buộc để thu hẹp quyền truy cập vào tài nguyên, chẳng hạn như mã dự án hoặc tên tài khoản.

Sử dụng chính sách ExtensionChú thích trong PostClientFlow

Bạn có thể gọi chính sách Chú thích tiện ích từ PostClientFlow của proxy API. PostClientFlow thực thi sau khi phản hồi được gửi đến ứng dụng yêu cầu. Việc này đảm bảo rằng tất cả các chỉ số đều có sẵn để ghi nhật ký. Để biết thông tin chi tiết về cách sử dụng PostClientFlow, hãy xem Tài liệu tham khảo về cấu hình proxy API.

Nếu bạn muốn sử dụng chính sách Chú thích mở rộng để gọi tiện ích Ghi nhật ký đám mây của Google từ PostClientFlow, hãy đảm bảo rằng bạn đặt cờ features.allowExtensionsInPostClientFlow thành true trong tổ chức của mình.

  • Nếu bạn là khách hàng của Apigee Edge dành cho đám mây công cộng, thì cờ features.allowExtensionsInPostClientFlow sẽ được đặt thành true theo mặc định.

  • Nếu bạn là khách hàng của Apigee Edge dành cho đám mây riêng tư, hãy sử dụng API Cập nhật thuộc tính của tổ chức để đặt cờ features.allowExtensionsInPostClientFlow thành true.

Tất cả các hạn chế về việc gọi chính sáchMessageLogging từ PostClientFlow cũng áp dụng cho chính sách ExtensionChú thích. Xem Ghi chú sử dụng để biết thêm thông tin.

Tham chiếu phần tử

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="false" enabled="true" name="Extension-Callout-1">
    <DisplayName/>
    <Connector/>
    <Action/>
    <Input/>
    <Output/>
</ConnectorCallout>

Thuộc tính <Trình kết nối>

<ConnectorCallout name="Extension-Callout-1" continueOnError="false" enabled="true" async="false">

Bảng sau đây mô tả các thuộc tính chung cho tất cả phần tử mẹ của chính sách:

Thuộc tính Nội dung mô tả Mặc định Sự hiện diện
name

Tên nội bộ của chính sách. Giá trị của thuộc tính name có thể chứa chữ cái, số, dấu cách, dấu gạch nối, dấu gạch dưới và dấu chấm. Giá trị này không được vượt quá 255 ký tự.

Nếu muốn, bạn có thể sử dụng phần tử <DisplayName> để gắn nhãn cho chính sách này trong trình chỉnh sửa proxy giao diện người dùng quản lý bằng tên ngôn ngữ tự nhiên khác.

 Không áp dụng Bắt buộc
continueOnError

Đặt thành false để trả về lỗi khi một chính sách không hoạt động. Đây là hành vi dự kiến đối với hầu hết các chính sách.

Đặt thành true để quá trình thực thi luồng tiếp tục ngay cả khi chính sách không thành công.

 false Không bắt buộc
enabled

Đặt thành true để thực thi chính sách.

Đặt thành false để tắt chính sách này. Chính sách này sẽ không được thực thi ngay cả khi chính sách vẫn được đính kèm vào một quy trình.

 đúng Không bắt buộc
async

Thuộc tính này không được dùng nữa.

 false Không được dùng nữa

Phần tử <DisplayName>

Sử dụng cùng với thuộc tính name để gắn nhãn cho chính sách trong trình chỉnh sửa proxy giao diện người dùng quản lý bằng tên khác theo ngôn ngữ tự nhiên.

<DisplayName>Policy Display Name</DisplayName>
Mặc định

Không áp dụng

Nếu bạn bỏ qua phần tử này, thì giá trị thuộc tính name của chính sách sẽ được sử dụng.
Sự hiện diện Không bắt buộc
Loại Chuỗi

Phần tử <Action>

Hành động hiển thị với tiện ích mà chính sách nên gọi.

<Action>action-exposed-by-extension</Action>
Mặc định Không có
Sự hiện diện Bắt buộc
Loại Chuỗi

Mỗi tiện ích hiển thị một tập hợp thao tác riêng để cấp quyền truy cập vào chức năng của tài nguyên mà tiện ích đại diện. Bạn có thể xem một thao tác là một hàm mà bạn gọi bằng chính sách này, sử dụng nội dung của phần tử <Input> để chỉ định các đối số của hàm đó. Phản hồi của hành động được lưu trữ trong biến mà bạn chỉ định bằng phần tử <Output>.

Để biết danh sách các hàm của tiện ích, hãy xem tài liệu tham khảo dành cho tiện ích mà bạn đang gọi từ chính sách này.

Phần tử <Trình kết nối>

Tên của tiện ích đã định cấu hình để sử dụng. Đây là tên ở phạm vi môi trường được cung cấp cho tiện ích khi tiện ích được định cấu hình để triển khai trong một môi trường.

<Connector>name-of-configured-extension</Connector>

Mặc định Không có
Sự hiện diện Bắt buộc
Loại Chuỗi

Một tiện ích có các giá trị cấu hình có thể khác với một tiện ích đã triển khai khác dựa trên cùng một gói tiện ích. Các giá trị cấu hình này có thể thể hiện sự khác biệt quan trọng về chức năng thời gian chạy giữa các tiện ích được định cấu hình từ cùng một gói, vì vậy, hãy nhớ chỉ định đúng tiện ích cần gọi.

Phần tử <Input>

JSON chứa nội dung yêu cầu để gửi đến tiện ích.

<Input><![CDATA[ JSON-containing-input-values ]]></Input>

Mặc định Không có
Sự hiện diện Không bắt buộc hoặc bắt buộc, tuỳ thuộc vào tiện ích.
Loại Chuỗi

Về cơ bản, đây là một đối số cho thao tác mà bạn chỉ định bằng phần tử <Action>. Giá trị của phần tử <Input> sẽ thay đổi tuỳ thuộc vào tiện ích và thao tác mà bạn đang gọi. Xem tài liệu về gói tiện ích để biết thông tin chi tiết về các thuộc tính của từng thao tác.

Lưu ý rằng mặc dù nhiều giá trị phần tử <Input> sẽ hoạt động đúng cách mà không cần nằm trong phần <![CDATA[]]>, nhưng các quy tắc của JSON cho phép các giá trị không phân tích cú pháp dưới dạng XML. Tốt nhất là bạn nên đặt JSON dưới dạng phần CDATA để tránh lỗi phân tích cú pháp trong thời gian chạy.

Giá trị của phần tử <Input> là JSON được định dạng đúng, trong đó các thuộc tính chỉ định những giá trị cần gửi đến hành động tiện ích cần gọi. Ví dụ: thao tác log của tiện ích Tiện ích ghi nhật ký trên đám mây của Google: nhận các giá trị chỉ định nhật ký cần ghi vào (logName), siêu dữ liệu để đưa vào mục nhập (metadata) và thông điệp nhật ký (data). Sau đây là ví dụ:

<Input><![CDATA[{
    "logName" : "example-log",
    "metadata" : {
        "resource": {
            "type": "global",
            "labels": {
                "project_id": "my-test"
            }
        }
    },
    "message" : "This is a test"
}]]></Input>

Sử dụng các biến luồng trong JSON <Input>

Nội dung của <Input> được coi là một mẫu thông báo. Điều này có nghĩa là tên biến được đặt trong dấu ngoặc nhọn sẽ được thay thế trong thời gian chạy bằng giá trị của biến được tham chiếu.

Ví dụ: bạn có thể viết lại khối <Input> trước đó để sử dụng biến luồng client.ip nhằm lấy địa chỉ IP của ứng dụng gọi proxy API:

<Input><![CDATA[{
    "logName" : "example-log",
    "metadata" : {
        "resource": {
            "type": "global",
            "labels": {
                "project_id": "my-test"
            }
        }
    },
    "message" : "{client.ip}"
}]]></Input>

Nếu bạn định đưa một giá trị thuộc tính trong JSON vào trong dấu ngoặc kép trong thời gian chạy, hãy nhớ sử dụng dấu ngoặc kép trong mã JSON của bạn. Điều này đúng ngay cả khi bạn chỉ định biến luồng làm giá trị thuộc tính JSON cần được phân giải trong thời gian chạy.

Ví dụ <Input> sau đây bao gồm 2 tham chiếu biến luồng:

<Input><![CDATA[{
  "logName" : "example-log",
  "metadata" : {my.log.entry.metadata},
  "message" : "{client.ip}"
}]]></Input>

Trong thời gian chạy, các giá trị thuộc tính JSON sẽ được phân giải như sau:

  • Giá trị thuộc tính logName – giá trị cố định kiểu chuỗi example-log.
  • Giá trị thuộc tính metadata – giá trị biến luồng my.log.entry.metadata không đặt dấu ngoặc kép. Điều này có thể hữu ích nếu giá trị của biến chính là JSON đại diện cho một đối tượng.
  • Giá trị thuộc tính message – giá trị biến luồng client.ip có đặt trong dấu ngoặc kép.

Phần tử <Output>

Tên của một biến lưu trữ phản hồi của thao tác mở rộng.

<Output>variable-name</Output> <!-- The JSON object inside the variable is parsed -->

hoặc

<Output parsed="false">variable-name</Output>  <!-- The JSON object inside the variable is raw, unparsed -->

Mặc định Không có
Sự hiện diện Không bắt buộc hoặc bắt buộc, tuỳ thuộc vào tiện ích.
Loại Chuỗi hoặc đối tượng được phân tích cú pháp, tuỳ thuộc vào chế độ cài đặt thuộc tính parsed.

Khi nhận được phản hồi, giá trị phản hồi sẽ được đặt vào biến mà bạn chỉ định tại đây, nơi bạn có thể truy cập vào biến đó từ mã proxy API khác.

Các đối tượng phản hồi của tiện ích có định dạng JSON. Chính sách này có 2 phương thức xử lý tệp JSON:

  • Phân tích cú pháp (mặc định): Chính sách này phân tích cú pháp đối tượng JSON và tự động tạo các biến có dữ liệu JSON. Ví dụ: nếu JSON chứa "messageId" : 12345; và bạn đặt tên biến đầu ra là extensionOutput, thì bạn có thể truy cập vào mã thông báo đó trong các chính sách khác bằng cách sử dụng biến {extensionOutput.messageId}.
  • Chưa phân tích cú pháp: Biến đầu ra chứa phản hồi JSON thô, chưa được phân tích cú pháp từ tiện ích. (Nếu muốn, bạn vẫn có thể phân tích cú pháp giá trị phản hồi trong một bước riêng bằng cách sử dụng chính sách JavaScript.)

Thuộc tính <Output>

Thuộc tính Nội dung mô tả Mặc định Sự hiện diện
đã phân tích cú pháp Phân tích cú pháp đối tượng JSON được trả về từ tiện ích, cho phép các chính sách khác truy cập dữ liệu trong đối tượng JSON dưới dạng biến. đúng Không bắt buộc

Biến luồng

Không nội dung nào.

Mã lỗi

Lỗi được trả về từ chính sách Apigee Edge sẽ tuân theo một định dạng nhất quán như mô tả trong Tài liệu tham khảo về lỗi chính sách.

Phần này mô tả các thông báo lỗi và biến quy trình được đặt khi chính sách này kích hoạt lỗi. Thông tin này rất quan trọng để biết liệu bạn có đang phát triển các quy tắc lỗi cho proxy hay không. Để tìm hiểu thêm, hãy xem bài viết Những điều bạn cần biết về lỗi chính sách và Cách xử lý lỗi.

Lỗi thời gian chạy

Những lỗi này có thể xảy ra khi thực thi chính sách.

Tên lỗi Trạng thái HTTP Nguyên nhân
Không thực hiện được 500 Tiện ích phản hồi với một lỗi.

Lỗi triển khai

Những lỗi này có thể xảy ra khi bạn triển khai một proxy có chứa chính sách này.

Tên lỗi Xảy ra khi Khắc phục
InvalidConnectorInstance Phần tử <Connector> trống.
ConnectorInstanceDoesNotExists Phần mở rộng được chỉ định trong phần tử <Connector> không tồn tại trong môi trường này.
InvalidAction Phần tử <Action> trong chính sách Extension Annotation bị thiếu hoặc được đặt thành một giá trị trống.
AllowExtensionsInPostClientFlow Nghiêm cấm chính sách Extension Annotation trong Luồng PostClient.