Chính sách Nâng cao

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

  • Nếu bạn không chỉ định source, thì thẻ đó sẽ được coi là một thông báo đơn giản. Ví dụ: nếu chính sách nằm trong luồng yêu cầu, thì nguồn sẽ mặc định sẽ là đối tượng request. Nếu nằm trong quy trình phản hồi, thì chính sách sẽ mặc định là đối tượng phản hồi. Nếu bỏ qua source (nguồn), bạn có thể sử dụng tham chiếu tuyệt đối đến biến luồng làm nguồn của bản sao. Ví dụ: chỉ định giá trị là {request.header.user-agent}.
  • Nếu biến nguồn không phân giải được hoặc chuyển thành loại không phải tin nhắn, thì <Copy> sẽ không phản hồi.
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 variablePrefixvariableSuffix 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 đề Content-Type.

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áchXử 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