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 ExtensionAnnotation để tích hợp một 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à 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ề phần mở rộng, hãy xem bài viết Phần mở rộng 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 trong chính sách ExtensionAnnotation, bạn phải thêm, định cấu hình và triển khai tiện ích đó từ một gói tiện ích đã được cài đặt vào tổ chức Apigee Edge của bạn.

Mẫu

Dưới đây là một chính sách mẫu để 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>

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

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

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

Hãy sử dụng chính sách ExtensionAnnotation khi bạn muốn sử dụng một tiện ích đã định cấu hình để truy cập vào một 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 cần có:

• 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 từ chính sách này. Những 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 phải biết tên bộ sưu tập và tài liệu mà bạn muốn tạo hoặc truy cập. Thường thì bạn sẽ sử dụng thông tin dành riêng cho tài nguyên để định cấu hình cách xử lý yêu cầu và phản hồi của chính sách này.
• Một tiện ích đã được 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ụ Google Cloud cụ thể, thì tiện ích được 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 chi tiết về 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 ExtensionAnnotation trong PostClientFlow

Bạn có thể gọi chính sách ExtensionAnnotation 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, để đảm bảo rằng tất cả các chỉ số đều có sẵn để ghi nhật ký. Để biết 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 ExtensionAnnotation để gọi tiện ích ghi nhật ký trên Google Cloud từ PostClientFlow, hãy đảm bảo rằng cờ features.allowExtensionsInPostClientFlow được đặt thành true trong tổ chức của bạn.

• Nếu bạn là khách hàng ứng dụng Apigee Edge cho Public Cloud, Theo mặc định, cờ features.allowExtensionsInPostClientFlow được đặt thành true.

• Nếu bạn là đối tác Apigee Edge cho khách hàng Private Cloud, 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ả hạn chế về việc gọi chính sách MessageLogging từ PostClientFlow cũng áp dụng cho chính sách Phần mở rộng về chú thích. Hãy xem Ghi chú sử dụng để tìm hiểu thêm.

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>

<ConnectorCallout> thuộc tính

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

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

<DisplayName> phần tử

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

<DisplayName>Policy Display Name</DisplayName>

<Action> phần tử

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

<Action>action-exposed-by-extension</Action>

Mỗi tiện ích hiển thị một nhóm hành động 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ể coi hành động là một hàm mà bạn gọi bằng chính sách này bằng cách 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 thao tác đượ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 chức năng của tiện ích, hãy xem tài liệu tham khảo cho tiện ích mà bạn đang gọi từ chính sách này.

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

Tên của tiện ích được định cấu hình để sử dụng. Đây là tên trong 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 cho một môi trường.

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

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 trong cùng một gói, vì vậy, hãy nhớ chỉ định đúng tiện ích cần gọi.

&lt;Input&gt; phần tử

JSON chứa nội dung yêu cầu gửi tới tiện ích.

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

Về cơ bản, đây là đối số cho hành động 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à hành động mà bạn đang gọi. Hãy 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 mỗi thao tác.

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

Nội dung của <Input> được coi là 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ế bằng giá trị của biến được tham chiếu trong thời gian chạy.

Ví dụ: bạn có thể viết lại khối <Input> trước đó để sử dụng biến luồng client.ip lấy địa chỉ IP của ứng dụng khách 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 đưa 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. Điều này đúng ngay cả khi bạn chỉ định một biến luồng làm giá trị thuộc tính JSON cần được giải quyết trong thời gian chạy.

Ví dụ <Input> sau đây bao gồm hai tệp 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ị của 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 có dấu ngoặc kép. Điều này có thể hữu ích nếu chính giá trị của biến 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.

&lt;Output&gt; phần tử

Tên của một biến lưu trữ phản hồi của thao tác với tiện ích.

<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 -->

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. Tại đây, bạn có thể truy cập giá trị đó 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. Có hai lựa chọn về cách chính sách xử lý JSON:

• Phân tích cú pháp (mặc định): Chính sách 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 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 đượ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.)

&lt;Output&gt; Thuộc tính

Biến luồng

Không có.

Mã lỗi

Các lỗi do chính sách của Apigee Edge gửi đến 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.

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.