Chính sách Nâng cao

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

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ề cho ứ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

<RaiseFault name="404">
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
 <FaultResponse>
   <Set>
     <StatusCode>404</StatusCode>
     <ReasonPhrase>The resource requested was not found</ReasonPhrase>
   </Set>
 </FaultResponse>
</RaiseFault>

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

Giới thiệu về chính sách RaiseFault

Apigee Edge cho phép bạn thực hiện quy trình xử lý ngoại lệ tuỳ chỉnh bằng cách sử dụ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 một 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 phản hồi lỗi được trả về cho ứ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 tiêu đề HTTP, tham số truy vấn và trọng tải thông báo. Phản hồi lỗi tuỳ chỉnh có thể hữu ích hơn cho nhà phát triển ứng dụng và người dùng cuối ứ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 đó trả về phản hồi lỗi được chỉ định cho ứng dụng khách yêu cầu. Khi luồng thông báo chuyển sang luồng Lỗi, sẽ không có hoạt động xử lý chính sách nào khác diễn ra. Tất cả các bước xử lý còn lại đều bị 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 vào chính sách RaiseFault. Sau khi RaiseFault thực thi, Apigee sẽ thực hiện 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, thì Apigee sẽ chấm dứt quá trình xử lý yêu cầu.

Tài liệu tham khảo về phần tử

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

(Không bắt buộc) Bỏ qua mọi lỗi biến chưa được giải quyết trong Flow. 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ề cho ứng dụng khách yêu cầu. FaultResponse sử dụng cùng chế độ cài đặt với chính sách AssignMessage (không có trong Apigee Edge cho Private Cloud).

Phần tử <FaultResponse><AssignVariable>

Gán một 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ụ: hãy dùng mã sau đây để đặt biến có tên là 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 sau này trong chính sách RaiseFault. Ngoài ra, một chính sách được đính kèm vào FaultRule sau đó có thể truy cập vào biến. Ví dụ: chính sách AssignMessage sau đây sử dụng biến được thiết lập trong RaiseFault để thiết lập mộ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ách AssignMessage. Xin lưu ý rằng chức năng này hiện không có trong Apigee Edge cho Đám mây riêng.

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

Phần tử <FaultResponse><Copy>

Sao chép thông tin từ thông báo do thuộc tính source chỉ định đến thông báo lỗi.

    <Copy source="request">
        <Headers/>
        <StatusCode/>
        <ReasonPhrase/>
    </Copy>

Thuộc tính

 <Copy source="response">

Phần tử <FaultResponse><Copy>/<Headers>

Sao chép tiêu đề HTTP đã chỉ định từ nguồn vào 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ù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 của "h3". Nếu "h3" chỉ có một giá trị, thì giá trị đó sẽ không được sao chép.

Phần tử <FaultResponse><Copy>/<StatusCode>

Mã trạng thái HTTP để sao chép từ đối tượng do thuộc tính nguồn chỉ định vào thông báo lỗi.

<Copy source='response'>
    <StatusCode>404</StatusCode>      
</Copy>

Phần tử <FaultResponse><Copy>/<ReasonPhrase>

Nội dung mô tả lý do để sao chép từ đối tượng do thuộc tính nguồn chỉ định vào thông báo lỗi.

<Copy source='response'>     
    <ReasonPhrase>The resource requested was not found.</ReasonPhrase>     
</Copy>

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ả cá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ù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 xoá "h1", "h2" và giá trị thứ hai của "h3". Nếu "h3" chỉ có một giá trị, thì giá trị đó sẽ không bị xoá.

Phần tử <FaultResponse><Set>

Đặt thông tin trong thông báo lỗi.

    <Set>
        <Headers/>
        <Payload> </Payload>
        <StatusCode/>
        <ReasonPhrase/>
    </Set>

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 đặt 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>

Phần tử <FaultResponse>/<Set>/<Payload>

Đặt tải trọng của thông báo lỗi.

<Set>
    <Payload contentType="text/plain">test1234</Payload>
</Set>

Đặt một gói dữ liệu 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 với các ký tự phân cá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 trên đám mây 16.08.17, bạn cũng có thể dùng dấu ngoặc nhọn để chèn các 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>

Thuộc tính

 
<Payload contentType="content_type" variablePrefix="char" variableSuffix="char">

Phần tử <FaultResponse>/<Set>/<StatusCode>

Đặt mã trạng thái của phản hồi.

<Set source='request'>
    <StatusCode>404</StatusCode>
</Set>

Phần tử <FaultResponse>/<Set>/<ReasonPhrase>

Đặt cụm từ lý do của phản hồi.

<Set source='request'>     
    <ReasonPhrase>The resource requested was not found.</ReasonPhrase>
</Set>

Phần tử <ShortFaultReason>

Chỉ định hiển thị 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"}}}

Để giúp 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).

Biến dò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 bối cảnh Luồng. Các biến Flow được xác định trước sau đây sẽ có sẵn sau khi chính sách RaiseFault thực thi. Để biết thêm thông tin về các biến trong luồng, hãy xem phần Tài liệu tham khảo về biến.

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 queryparam đó không có, luồng sẽ phát sinh 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>

<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 rất quan trọng nếu bạn đang phát triển các quy tắc lỗi để xử lý lỗi. Để tìm hiểu thêm, hãy xem 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 chính sách này thực thi.

Lỗi triển khai

Không có.

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 bài viết Những điều bạn cần biết về lỗi chính sách.

Ví dụ về phản hồi khi gặp 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). Để tham khảo, bạn có thể xem giản đồ chính sách trên GitHub.

Chủ đề có liên quan

Xem phần Xử lý lỗi