Bạn đang xem tài liệu về Apigee Edge.
Chuyển đến tài liệu về
Apigee X. thông tin
Nội dung
Tạo một thông báo tuỳ chỉnh để phản hồi một điều kiện lỗi. Sử dụng RaiseFault để xác định một phản hồi lỗi được trả về ứng dụng yêu cầu khi một điều kiện cụ thể phát sinh.
Để biết thông tin chung về cách xử lý lỗi, hãy xem phần Xử lý lỗi.
Mẫu
Trả về lỗi
Trong cách sử dụng phổ biến nhất, RaiseFault được dùng để trả về một phản hồi lỗi tuỳ chỉnh cho ứng dụng yêu cầu. Ví dụ: chính sách này sẽ trả về một mã trạng thái 404
không có tải trọng:
<RaiseFault name="404"> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <FaultResponse> <Set> <StatusCode>404</StatusCode> <ReasonPhrase>The resource requested was not found</ReasonPhrase> </Set> </FaultResponse> </RaiseFault>
Tải trọng trả về lỗi
Một ví dụ phức tạp hơn là việc trả về một tải trọng phản hồi lỗi tuỳ chỉnh, cùng với các tiêu đề HTTP và mã trạng thái HTTP. Trong ví dụ sau, phản hồi lỗi được điền sẵn bằng một thông báo XML chứa mã trạng thái HTTP mà Edge nhận được từ dịch vụ phụ trợ và một tiêu đề chứa loại lỗi đã xảy ra:
<RaiseFault name="ExceptionHandler"> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <FaultResponse> <Set> <Payload contentType="text/xml"> <root>Please contact support@company.com</root> </Payload> <StatusCode>{response.status.code}</StatusCode> <ReasonPhrase>Server error</ReasonPhrase> </Set> <Add> <Headers> <Header name="FaultHeader">{fault.name}</Header> </Headers> </Add> </FaultResponse> </RaiseFault>
Để biết danh sách tất cả các biến có sẵn để điền động thông báo FaultResponse, hãy xem Tài liệu tham khảo về biến
Xử lý lỗi chú thích dịch vụ
Giới thiệu về chính sách RaiseFault
Apigee Edge cho phép bạn xử lý ngoại lệ tuỳ chỉnh bằng chính sách thuộc loại RaiseFault. Chính sách RaiseFault, tương tự như Chính sách assignMessage, cho phép bạn tạo phản hồi lỗi tuỳ chỉnh để phản hồi một điều kiện lỗi.
Sử dụng chính sách RaiseFault để xác định một phản hồi lỗi được trả về ứng dụng yêu cầu khi một điều kiện lỗi cụ thể phát sinh. Phản hồi lỗi có thể bao gồm các tiêu đề HTTP, tham số truy vấn và tải trọng thông báo. Phản hồi lỗi tuỳ chỉnh có thể hữu ích cho nhà phát triển ứng dụng và người dùng cuối của ứng dụng so với thông báo lỗi chung hoặc mã phản hồi HTTP.
Khi được thực thi, chính sách RaiseFault sẽ chuyển quyền kiểm soát từ luồng hiện tại sang luồng Lỗi, sau đó sẽ trả về phản hồi lỗi được chỉ định cho ứng dụng khách đưa ra yêu cầu. Khi Luồng thông báo chuyển sang luồng Lỗi, quy trình xử lý chính sách sẽ không tiếp tục diễn ra. Mọi Bước xử lý còn lại đều được bỏ qua và phản hồi lỗi được trả về trực tiếp cho ứng dụng yêu cầu.
Bạn có thể sử dụng RaiseFault trong ProxyEndpoint hoặc TargetEndpoint. Thông thường, bạn sẽ đính kèm một Condition (Điều kiện) vào chính sách RaiseFault. Sau khi RaiseFault thực thi, Apigee sẽ tiến hành xử lý lỗi thông thường, đánh giá FaultRules hoặc nếu không có quy tắc lỗi nào được xác định, Apigee sẽ chấm dứt việc xử lý yêu cầu.
Tham chiếu phần tử
Tham chiếu phần tử mô tả các phần tử và thuộc tính của chính sách RaiseFault.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <RaiseFault async="false" continueOnError="false" enabled="true" name="Raise-Fault-1"> <DisplayName>RaiseFault 1</DisplayName> <FaultResponse> <AssignVariable> <Name/> <Value/> </AssignVariable> <Add> <Headers/> </Add> <Copy source="request"> <Headers/> <StatusCode/> <ReasonPhrase/> </Copy> <Remove> <Headers/> </Remove> <Set> <Headers/> <Payload/> <ReasonPhrase/> <StatusCode/> </Set> </FaultResponse> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </RaiseFault>
Thuộc tính <RaiseFault>
<RaiseFault async="false" continueOnError="false" enabled="true" name="Raise-Fault-1">
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 Nếu muốn, bạn có thể sử dụng phần tử |
Không áp dụng | Bắt buộc |
continueOnError |
Đặt thành Đặt thành |
false | Không bắt buộc |
enabled |
Đặt thành Đặt thà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 |
---|---|
Sự hiện diện | Không bắt buộc |
Loại | Chuỗi |
Phần tử <IgnoreUnresolvedVariables>
(Không bắt buộc) Bỏ qua mọi lỗi biến chưa được giải quyết trong Luồng. Giá trị hợp lệ: true/false.
true
mặc định.
Phần tử <FaultResponse>
(Không bắt buộc) Xác định thông báo phản hồi được trả về ứng dụng yêu cầu. FaultResponse sử dụng các chế độ cài đặt tương tự như AssignMessage chính sách (không có trong Apigee Edge dành cho đám mây riêng tư).
Phần tử <FaultResponse><assignVariable>
Chỉ định giá trị cho biến luồng đích.
Nếu biến luồng không tồn tại, thì AssignVariable
sẽ tạo biến đó.
Ví dụ: sử dụng mã sau đây để đặt biến có tên myFaultVar
trong chính sách RaiseFault:
<FaultResponse> <AssignVariable> <Name>myFaultVar</Name> <Value>42</Value> </AssignVariable> ... </FaultResponse>
Sau đó, bạn có thể tham chiếu đến biến đó trong các mẫu thông báo ở phần sau của chính sách RaiseFault. Ngoài ra, một chính sách đính kèm với FaultRule có thể truy cập vào biến đó. Ví dụ: chính sách AttributionMessage sau đây sử dụng biến được đặt trong RaiseFault để đặt Tiêu đề trong phản hồi lỗi:
<AssignMessage enabled="true" name="Assign-Message-1"> <Add> <Headers> <Header name="newvar">{myFaultVar}</Header> </Headers> </Add> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <AssignTo createNew="false" transport="http" type="response"/> </AssignMessage>
<AssignVariable>
trong chính sách RaiseFault sử dụng cú pháp giống như phần tử <AssignVariable>
trong chính sáchAssignMessage. Xin lưu ý rằng chức năng này hiện không có trong Apigee Edge dành cho đám mây riêng tư.
Phần tử <FaultResponse><Add>/<Headers>
Thêm tiêu đề HTTP vào thông báo lỗi. Xin lưu ý rằng tiêu đề trống <Add><Headers/></Add>
không thêm tiêu đề nào. Ví dụ này sao chép giá trị của biến luồng request.user.agent vào tiêu đề.
<Add> <Headers> <Header name="user-agent">{request.user.agent}</Header> </Headers> </Add>
Mặc định: |
Không áp dụng |
Sự hiện diện: |
Không bắt buộc |
Loại: |
Chuỗi |
Phần tử <FaultResponse><Copy>
Sao chép thông tin từ thông báo do thuộc tính source
chỉ định cho thông báo lỗi.
<Copy source="request"> <Headers/> <StatusCode/> <ReasonPhrase/> </Copy>
Mặc định: |
Không áp dụng |
Sự hiện diện: |
Không bắt buộc |
Loại: |
Chuỗi |
Thuộc tính
<Copy source="response">
Thuộc tính | Nội dung mô tả | Sự hiện diện | Loại |
---|---|---|---|
source |
Chỉ định đối tượng nguồn của bản sao.
|
Không bắt buộc | Chuỗi |
Phần tử <FaultResponse><Copy>/<Headers>
Sao chép tiêu đề HTTP được chỉ định từ nguồn tới thông báo lỗi. Để sao chép tất cả tiêu đề,
hãy chỉ định <Copy><Headers/></Copy>.
<Copy source='request'> <Headers> <Header name="headerName"/> </Headers> </Copy>
Nếu có nhiều tiêu đề có cùng tên, hãy sử dụng cú pháp sau:
<Copy source='request'> <Headers> <Header name="h1"/> <Header name="h2"/> <Header name="h3.2"/> </Headers> </Copy>
Ví dụ này sao chép "h1", "h2" và giá trị thứ hai là "h3". Nếu "h3" chỉ có một giá trị, thì giá trị đó sẽ không được sao chép.
Mặc định: |
Không áp dụng |
Sự hiện diện: |
Không bắt buộc |
Loại: |
Chuỗi |
Phần tử <FaultResponse><Copy>/<StatusCode>
Mã trạng thái HTTP cần sao chép từ đối tượng do thuộc tính nguồn chỉ định sang thông báo lỗi.
<Copy source='response'> <StatusCode>404</StatusCode> </Copy>
Mặc định: |
false |
Sự hiện diện: |
Không bắt buộc |
Loại: |
Chuỗi |
Phần tử <FaultResponse><Copy>/<Reason #>
Nội dung mô tả lý do cần sao chép từ đối tượng do thuộc tính nguồn chỉ định sang thông báo lỗi.
<Copy source='response'> <ReasonPhrase>The resource requested was not found.</ReasonPhrase> </Copy>
Mặc định: |
false |
Sự hiện diện: |
Không bắt buộc |
Loại: |
Chuỗi |
Phần tử <FaultResponse><Remove>/<Headers>
Xoá các tiêu đề HTTP được chỉ định khỏi thông báo lỗi. Để xoá tất cả tiêu đề, hãy chỉ định <Remove><Headers/></Remove>
. Ví dụ này sẽ xoá tiêu đề user-agent
khỏi thông báo.
<Remove> <Headers> <Header name="user-agent"/> </Headers> </Remove>
Nếu có nhiều tiêu đề có cùng tên, hãy sử dụng cú pháp sau:
<Remove> <Headers> <Header name="h1"/> <Header name="h2"/> <Header name="h3.2"/> </Headers> </Remove>
Ví dụ này sẽ xoá "h1", "h2" và giá trị thứ hai là "h3". Nếu "h3" chỉ có một giá trị, thì giá trị đó sẽ không bị xoá.
Mặc định: |
Không áp dụng |
Sự hiện diện: |
Không bắt buộc |
Loại: |
Chuỗi |
Phần tử <FaultResponse><Set>
Thiết lập thông tin trong thông báo lỗi.
<Set> <Headers/> <Payload> </Payload> <StatusCode/> <ReasonPhrase/> </Set>
Mặc định: |
Không áp dụng |
Sự hiện diện: |
Không bắt buộc |
Loại: |
Không áp dụng |
Phần tử <FaultResponse>/<Set>/<Headers>
Đặt hoặc ghi đè tiêu đề HTTP trong thông báo lỗi. Xin lưu ý rằng tiêu đề trống <Set><Headers/></Set>
không đặt tiêu đề nào. Ví dụ này thiết lập tiêu đề user-agent
thành biến thông báo được chỉ định bằng phần tử <AssignTo>
.
<Set> <Headers> <Header name="user-agent">{request.header.user-agent}</Header> </Headers> </Set>
Mặc định: |
Không áp dụng |
Sự hiện diện: |
Không bắt buộc |
Loại: |
Chuỗi |
Phần tử <FaultResponse>/<Set>/<Payload>
Đặt trọng tải của thông báo lỗi.
<Set> <Payload contentType="text/plain">test1234</Payload> </Set>
Đặt tải trọng JSON:
<Set> <Payload contentType="application/json"> {"name":"foo", "type":"bar"} </Payload> </Set>
Trong tải trọng JSON, bạn có thể chèn các biến bằng cách sử dụng thuộc tính variablePrefix
và variableSuffix
có các ký tự phân tách như minh hoạ trong ví dụ sau.
<Set> <Payload contentType="application/json" variablePrefix="@" variableSuffix="#"> {"name":"foo", "type":"@variable_name#"} </Payload> </Set>
hoặc kể từ bản phát hành đám mây 16.08.17, bạn cũng có thể chèn dấu ngoặc nhọn để chèn biến:
<Set> <Payload contentType="application/json"> {"name":"foo", "type":"{variable_name}"} </Payload> </Set>
Đặt tải trọng hỗn hợp trong XML:
<Set> <Payload contentType="text/xml"> <root> <e1>sunday</e1> <e2>funday</e2> <e3>{var1}</e3> </Payload> </Set>
Mặc định: |
|
Sự hiện diện: |
Không bắt buộc |
Loại: |
Chuỗi |
Thuộc tính
<Payload contentType="content_type" variablePrefix="char" variableSuffix="char">
Thuộc tính | Nội dung mô tả | Sự hiện diện | Loại |
---|---|---|---|
contentType |
Nếu bạn chỉ định contentType, thì giá trị của contentType sẽ được gán cho tiêu đề |
Không bắt buộc | Chuỗi |
variablePrefix | Bạn có thể chỉ định dấu phân cách ở đầu trên một biến luồng (flow) vì các tải trọng JSON không thể sử dụng ký tự "{" mặc định. | Không bắt buộc | Ký tự |
variableSuffix | Bạn có thể chỉ định dấu phân cách ở cuối trên một biến luồng (flow) vì tải trọng JSON không thể sử dụng ký tự "}" mặc định. | Không bắt buộc | Ký tự |
Phần tử <FaultResponse>/<Set>/<StatusCode>
Thiết lập mã trạng thái của phản hồi.
<Set source='request'> <StatusCode>404</StatusCode> </Set>
Mặc định: |
false |
Sự hiện diện: |
Không bắt buộc |
Loại: |
Boolean |
Phần tử <FaultResponse>/<Set>/<ReasonTerms>
Đặt cụm từ lý do của câu trả lời.
<Set source='request'> <ReasonPhrase>The resource requested was not found.</ReasonPhrase> </Set>
Mặc định: |
false |
Sự hiện diện: |
Không bắt buộc |
Loại: |
Boolean |
Phần tử <ShortFaultReason>
Chỉ định hiển thị một lý do lỗi ngắn trong phản hồi:
<ShortFaultReason>true|false</ShortFaultReason>
Theo mặc định, lý do lỗi trong phản hồi của chính sách là:
"fault":{"faultstring":"Raising fault. Fault name : Raise-Fault-1","detail":{"errorcode":"errorCode"}}}
Để thông báo dễ đọc hơn, bạn có thể đặt phần tử <ShortFaultReason>
thành true để rút ngắn faultstring
thành tên chính sách:
"fault":{"faultstring":"Raise-Fault-1","detail":{"errorcode":"errorCode"}}}
Giá trị hợp lệ: true/false(mặc định).
Mặc định: |
false |
Sự hiện diện: |
Không bắt buộc |
Loại: |
Boolean |
Biến luồng
Các biến luồng cho phép hành vi động của các chính sách và Luồng trong thời gian chạy, dựa trên tiêu đề HTTP, nội dung thông báo hoặc ngữ cảnh Luồng. Bạn có thể sử dụng các biến Flow được định nghĩa trước sau đây sau khi thực thi chính sách RaiseFault. Để biết thêm thông tin về biến Flow, hãy xem bài viết Tài liệu tham khảo về biến.
Biến | Loại | Quyền | Nội dung mô tả |
---|---|---|---|
fault.name | Chuỗi | Chỉ có thể đọc | Khi chính sách RaiseFault thực thi, biến này luôn được đặt thành chuỗi RaiseFault . |
fault.type | Chuỗi | Chỉ có thể đọc | Trả về loại lỗi trong lỗi và nếu không có thì trả về một chuỗi trống. |
fault.category | Chuỗi | Chỉ có thể đọc | Trả về danh mục lỗi trong lỗi và nếu không có giá trị thì trả về một chuỗi trống. |
Ví dụ về cách sử dụng RaiseFault
Ví dụ sau đây sử dụng một Điều kiện để thực thi sự hiện diện của queryparam
có tên zipcode
trong yêu cầu đến. Nếu không có queryparam
, quy trình này sẽ gây ra lỗi thông qua RaiseFault:
<Flow name="flow-1"> <Request> <Step> <Name>RF-Error-MissingQueryParam</Name> <Condition>request.queryparam.zipcode = null</Condition> </Step> ... </Request> ... <Condition>(proxy.pathsuffix MatchesPath "/locations") and (request.verb = "GET")</Condition> </Flow>Nội dung sau đây minh hoạ nội dung sẽ có trong RaiseFault:
<RaiseFault name='RF-Error-MissingQueryParam'> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <FaultResponse> <Set> <Payload contentType='application/json'>{ "error" : { "code" : 400.02, "message" : "invalid request. Pass a zipcode queryparam." } } </Payload> <StatusCode>400</StatusCode> <ReasonPhrase>Bad Request</ReasonPhrase> </Set> </FaultResponse> </RaiseFault>
Tham chiếu lỗi
Phần này mô tả các mã lỗi và thông báo lỗi được trả về, cũng như các biến lỗi do Edge đặt khi chính sách này kích hoạt lỗi. Thông tin này đóng vai trò quan trọng trong việc phát triển các quy tắc lỗi để xử lý lỗi. Để 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à 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.
Mã lỗi | Trạng thái HTTP | Nguyên nhân |
---|---|---|
steps.raisefault.RaiseFault |
500 | Xem chuỗi lỗi. |
Lỗi triển khai
Không nội dung nào.
Biến lỗi
Các biến này được đặt khi xảy ra lỗi thời gian chạy. Để biết thêm thông tin, hãy xem Những điều bạn cần biết về lỗi chính sách.
Biến | Trong đó | Ví dụ: |
---|---|---|
fault.name="fault_name" |
fault_name là tên của lỗi, như liệt kê trong bảng Lỗi thời gian chạy ở trên. Tên lỗi là phần cuối cùng của mã lỗi. | fault.name = "RaiseFault" |
raisefault.policy_name.failed |
policy_name là tên của chính sách báo lỗi do người dùng chỉ định. | raisefault.RF-ThrowError.failed = true |
Ví dụ về phản hồi lỗi
{ "fault":{ "detail":{ "errorcode":"steps.raisefault.RaiseFault" }, "faultstring":"Raising fault. Fault name: [name]" } }
Lược đồ
Mỗi loại chính sách được xác định bằng một giản đồ XML (.xsd
). Giản đồ chính sách có sẵn trên GitHub để bạn tham khảo.
Chủ đề có liên quan
Xem phần Xử lý lỗi