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.
Truy cập vào tài liệu Apigee X. thông tin

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

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 này có thể là các dịch vụ của Google Cloud Platform, chẳng hạn 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 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 từ chính sách ExtensionCallout, 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 ví dụ về chính sách để sử dụng với tiện ích Cloud Logging:

<?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 các tiện ích để biết hướng dẫn đầy đủ về cách sử dụng tiện ích Cloud Logging.

Để xem ví dụ về tất cả các tiện ích có sẵn, 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 ExtensionCallout

Sử dụng chính sách ExtensionCallout khi bạn muốn 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ừ bên trong một proxy API.

Trước khi sử dụng chính sách này, bạn 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 theo chính sách này. Những thông tin này sẽ dành riêng cho tài nguyên. Ví dụ: nếu chính sách sẽ truy cập vào cơ sở dữ liệu Cloud Firestore, bạn cần phải biết tên 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 dành riêng cho tài nguyên khi định cấu hình quy 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 đượ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ụ cụ thể của Google Cloud, thì phải có một tiện ích đã triển khai cho dịch vụ đó 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 ExtensionCallout trong PostClientFlow

Bạn có thể gọi chính sách ExtensionCallout từ PostClientFlow của một proxy API. PostClientFlow sẽ thực thi sau khi phản hồi được gửi đến ứng dụng khách yêu cầu, điều 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 ExtensionCallout để gọi tiện ích Google Cloud Logging 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 của Apigee Edge 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 cho Đám mây riêng, hãy sử dụng API Cập nhật thuộc tính tổ chức để đặt cờ features.allowExtensionsInPostClientFlow thành true.

Tất cả các quy định hạn chế đối với việc gọi chính sách MessageLogging từ PostClientFlow cũng áp dụng cho chính sách ExtensionCallout. Hãy xem Ghi chú về cách sử dụng để biết thêm thông tin.

Tài liệu tham khảo về 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 <ConnectorCallout>

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

&lt;DisplayName&gt; 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>

Phần tử <Action>

Thao tác do tiện ích hiển thị mà chính sách sẽ gọi.

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

Mỗi tiện ích sẽ hiển thị một bộ hành động riêng, cho phép 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 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 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 hàm 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.

Phần tử <Connector>

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

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

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 khác được triển khai 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 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 tiện ích chính xác để 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>

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à 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ề các thuộc tính của từng thao tác.

Xin lưu ý rằng mặc dù nhiều giá trị phần tử <Input> sẽ hoạt động bình thường mà không cần được đặt trong phần <![CDATA[]]>, nhưng các quy tắc của JSON cho phép những giá trị sẽ không phân tích cú pháp dưới dạng XML. Theo phương pháp hay nhất, hãy đặ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ó cấu trúc rõ ràng, trong đó các thuộc tính chỉ định giá trị cần gửi đến thao tác tiện ích để gọi. Ví dụ: thao tác log của tiện ích Tiện ích Cloud Logging của Google Cloud sẽ lấy các giá trị chỉ định nhật ký để 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à 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 JSON <Input>

Nội dung của <Input> được coi là mẫu tin nhắn. Đ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 tại 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 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 muốn một giá trị thuộc tính trong JSON được đặt 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 vẫn đúng ngay cả khi bạn chỉ định một biến luồng dưới dạng giá trị thuộc tính JSON sẽ được phân giải trong thời gian chạy.

Ví dụ về <Input> sau đây có 2 tham chiếu biến luồng:

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

Khi 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 có dấu ngoặc kép bao quanh. Điều này có thể hữu ích nếu giá trị của biến là chính 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 bao quanh.

Phần tử <Output>

Tên của một biến lưu trữ phản hồi của hành động 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 ở đây, nơi bạn có thể truy cập vào 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ó 2 lựa chọn về cách chính sách 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 bằng 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, 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 biệt bằng cách sử dụng chính sách JavaScript.)

Thuộc tính <Output>

Biến dòng

Không có.

Mã lỗi

Các lỗi do chính sách Apigee Edge trả về tuân theo một định dạng nhất quán như mô tả trong phần 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.