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.
Tham khảo tài liệu về Apigee X. thông tin

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

Một tiện ích cung cấp quyền 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 Cloud Speech-to-Text. Tuy nhiên, tài nguyên đó có thể là tài nguyên bên ngoài bất kỳ, có thể truy cập qua HTTP hoặc HTTPS.

Để biết thông tin 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 truy cập vào 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 từ một gói tiện ích đã được cài đặt trong tổ chức Apigee Edge của mình.

Mẫu

Dưới đây là ví dụ về chính sách sử dụng với tiện ích Ghi nhật ký đá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 về chú thích cho phần 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ừ trong proxy API.

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

  • Một vài 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. Đây là những thông tin dành riêng cho từng 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à mình 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 xử lý yêu cầu và phản hồi của chính sách này.
  • 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 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. Chi tiết 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 ExtensionExtensions trong PostClientFlow

Bạn có thể gọi chính sách Chú thích mở rộng từ PostClientFlow của một proxy API. PostClientFlow thực thi sau khi phản hồi được gửi đến ứng dụng yêu cầu. Điều này giúp đảm bảo rằng tất 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 ExtensionExtensions để gọi tiện ích Ghi nhật ký trên đám mây của Google từ mộ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 sử dụng Apigee Edge cho dịch vụ đám mây công cộng, 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ế đối với việc gọi chính sáchMessageLogging từ PostClientFlow cũng áp dụng cho chính sách ExtensionAnnotation. Hãy xem phần 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 Chú thích>

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

Bảng sau đây mô tả các thuộc tính phổ biến với tất cả các phần tử chính sách chính:

Thuộc tính 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, hãy sử dụng phần tử <DisplayName> để gắn nhãn chính sách trong trình chỉnh sửa proxy của giao diện người dùng quản lý bằng một 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 thành cô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 để tiếp tục thực thi luồng ngay cả sau khi chính sách không hoạt động.

 sai Không bắt buộc
enabled

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

Đặ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 vẫn nằm trong quy trình.

 true Không bắt buộc
async

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

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

Phần tử <DisplayName>

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

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

Không áp dụng

Nếu bạn bỏ qua phần tử này, hệ thống sẽ sử dụng giá trị của thuộc tính name của chính sách.
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 sẽ 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 các thao tác riêng để cung 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 hành động 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 qua chính sách này.

Phần tử <Connector>

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 đặt cho tiện ích khi tiện ích được định cấu hình để triển khai lên 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. Những giá trị cấu hình này có thể thể hiện những điểm 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 phần mở rộng.
Loại Chuỗi

Về cơ bản, đây là một đối số cho thao tác 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à hành động mà bạn gọi. Xem tài liệu về gói tiện ích để biết thông tin chi tiết về thuộc tính của từng hành động.

Lưu ý rằng mặc dù nhiều giá trị phần tử <Input> sẽ hoạt động chính xác mà không cần nằm trong phần <![CDATA[]]>, nhưng quy tắc của JSON cho phép các giá trị không được phân tích cú pháp dưới dạng XML. Tốt nhất là bạn nên đưa JSON vào 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 cách trong đó các thuộc tính chỉ định các giá trị cần gửi đến thao tác 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 cần đư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 dự định đặt giá trị thuộc tính trong JSON trong dấu ngoặc kép khi 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 vẫn áp dụng ngay cả khi bạn chỉ định một biến luồng là 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 mã 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ẽ 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 trong 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ó dấu ngoặc kép đóng.

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 phần mở rộng.
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 ở định dạng JSON. Có hai phương án về cách chính sách này xử lý 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 cho biến đầu ra là extensionOutput, 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 được 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ề qua 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

Các lỗi do chính sách Apigee Edge trả về sẽ có đị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.