ใช้ API รายงานที่กําหนดเองแบบอะซิงโครนัส

คุณกำลังดูเอกสารประกอบของ Apigee Edge
ไปที่เอกสารประกอบของ Apigee X ข้อมูล

Edge Analytics มีชุดแดชบอร์ดแบบอินเทอร์แอกทีฟ เครื่องมือสร้างรายงานที่กำหนดเอง และความสามารถที่เกี่ยวข้องมากมาย อย่างไรก็ตาม ฟีเจอร์เหล่านี้มีวัตถุประสงค์ให้มีการโต้ตอบ กล่าวคือคุณส่งคำขอ API หรือ UI และคำขอจะถูกบล็อกจนกว่าเซิร์ฟเวอร์ข้อมูลวิเคราะห์จะตอบกลับ

อย่างไรก็ตาม คำขอข้อมูลวิเคราะห์อาจหมดเวลาหากคำขอใช้เวลานานเกินไป หากคำขอการค้นหาต้องประมวลผลข้อมูลจำนวนมาก (เช่น 100 GB) คำขออาจดำเนินการไม่สำเร็จเนื่องจากหมดเวลา

การประมวลผลการค้นหาแบบอะซิงโครนัสช่วยให้คุณค้นหาชุดข้อมูลที่มีขนาดใหญ่มากและดึงผลลัพธ์ในภายหลังได้ คุณอาจลองใช้การค้นหาแบบออฟไลน์เมื่อพบว่าการค้นหาแบบอินเทอร์แอกทีฟหมดเวลาแล้ว สถานการณ์บางอย่างที่การประมวลผลข้อความค้นหาแบบอะซิงโครนัส อาจเป็นทางเลือกที่ดี ได้แก่

• การวิเคราะห์และสร้างรายงานที่ครอบคลุมช่วงเวลาขนาดใหญ่
• การวิเคราะห์ข้อมูลด้วยมิติข้อมูลการจัดกลุ่มที่หลากหลายและข้อจำกัดอื่นๆ ที่เพิ่มความซับซ้อนให้กับการสืบค้นข้อมูล
• จัดการการค้นหาเมื่อพบว่าปริมาณข้อมูลเพิ่มขึ้นอย่างมากสำหรับผู้ใช้หรือองค์กรบางราย

เอกสารนี้อธิบายวิธีเริ่มคำค้นหาแบบอะซิงโครนัสโดยใช้ API นอกจากนี้คุณยังใช้ UI ได้ตามที่อธิบายไว้ในการเรียกใช้รายงานที่กำหนดเอง

การเปรียบเทียบ API รายงานกับ UI

สร้างและจัดการรายงานที่กำหนดเองจะอธิบายวิธีใช้ Edge UI เพื่อสร้างและเรียกใช้รายงานที่กำหนดเอง คุณสามารถเรียกใช้รายงานดังกล่าวแบบพร้อมกัน หรือไม่พร้อมกันก็ได้

แนวคิดในการสร้างรายงานที่กำหนดเองด้วย UI โดยส่วนใหญ่จะใช้กับการใช้ API กล่าวคือ เมื่อสร้างรายงานที่กำหนดเองด้วย API คุณจะระบุmetrics มิติข้อมูล และตัวกรองที่มีอยู่ใน Edge และเมตริกที่กำหนดเองทั้งหมดที่คุณสร้างขึ้นโดยใช้นโยบายเครื่องมือรวบรวมข้อมูลสถิติ

ความแตกต่างที่สำคัญระหว่างรายงานที่สร้างใน UI และใน API คือรายงานที่สร้างด้วย API จะเขียนเป็นไฟล์ CSV หรือ JSON (คั่นด้วยการขึ้นบรรทัดใหม่) แทนการเขียนลงในรายงานภาพที่แสดงใน UI

ขีดจำกัดในแบบผสมของ Apigee

Apigee ในแบบผสมจะบังคับใช้ขีดจำกัดขนาด 30 MB ในชุดข้อมูลผลลัพธ์

วิธีสร้างการสืบค้นข้อมูล Analytics แบบไม่พร้อมกัน

คุณสามารถสร้างคำค้นหา Analytics แบบไม่พร้อมกันได้ใน 3 ขั้นตอน ดังนี้

1. ส่งคำค้นหา

2. ดูสถานะการค้นหา

3. ดึงผลการค้นหา

ขั้นตอนที่ 1 ส่งคำค้นหา

คุณต้องส่งคำขอ POST ไปยัง API /queries โดย API นี้จะบอกให้ Edge ดำเนินการตามคำขอของคุณในเบื้องหลัง หากส่งคำขอสำเร็จ API จะแสดงสถานะ 201 และรหัสที่คุณจะใช้อ้างอิงการค้นหาในขั้นตอนต่อๆ ไป

เช่น

curl -X POST -H "Content-Type:application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/queries -d @json-query-file
-u orgAdminEmail:password

เนื้อหาของคำขอคือคำอธิบาย JSON ของคำค้นหา ในเนื้อหา JSON ให้ระบุmetrics มิติข้อมูล และตัวกรองที่กำหนดรายงาน

ด้านล่างนี้เป็นตัวอย่างไฟล์ json-query-file

{ 
   "metrics":  [
     {
         "name": "message_count",
         "function": "sum",
         "alias": "sum_txn"
    }
        ],
    "dimensions": ["apiproxy"],
    "timeRange": "last24hours",
    "limit": 14400,
    "filter":"(message_count ge 0)"         
}

โปรดดูเกี่ยวกับเนื้อหาของคำขอด้านล่างเพื่อดูคำอธิบายที่สมบูรณ์ของไวยากรณ์ของเนื้อหาคำขอ

ตัวอย่างคำตอบ

โปรดทราบว่าคำตอบนี้จะมีรหัสคำค้นหา 9cfc0d85-0f30-46d6-ae6f-318d0cb961bd รวมอยู่ด้วย นอกจากสถานะ HTTP 201 แล้ว state ของ enqueued หมายความว่าคำขอประสบความสำเร็จ

HTTP/1.1 201 Created

{  
  "self":"/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd",
  "created":"2018-05-10T07:11:10Z",
  "state":"enqueued",
  "error":"false",
}

ขั้นตอนที่ 2 ดูสถานะการค้นหา

ทำการเรียก GET เพื่อขอสถานะการค้นหา คุณระบุรหัสข้อความค้นหาที่ถูกส่งคืนจากการเรียก POST เช่น

curl -X GET -H "Content-Type:application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd
-u email:password

ตัวอย่างคำตอบ

หากการค้นหายังคงดำเนินอยู่ คุณจะได้รับการตอบกลับในลักษณะนี้ โดยที่ state คือ running

{
    "self": "/organizations/myorg/environments/myenv/queries/1577884c-4f48-4735-9728-5da4b05876ab",
    "state": "running",
    "created": "2018-02-23T14:07:27Z",
    "updated": "2018-02-23T14:07:54Z"
}

หลังจากการค้นหาเสร็จสมบูรณ์แล้ว คุณจะเห็นการตอบกลับในลักษณะนี้ โดยตั้งค่า state เป็น completed

{
      "self": "/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd",
      "state": "completed",
      "result": {
        "self": "/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd/result",
        "expires": "2017-05-22T14:56:31Z"
      },
      "resultRows": 1,
      "resultFileSize": "922KB",
      "executionTime": "11 sec",
      "created": "2018-05-10T07:11:10Z",
      "updated": "2018-05-10T07:13:22Z"
}

ขั้นตอนที่ 3 ดึงผลการค้นหา

หลังจากสถานะการค้นหาคือ completed คุณจะใช้ API รับผลลัพธ์ เพื่อดึงผลการค้นหาได้ โดยรหัสการค้นหาจะเป็น 9cfc0d85-0f30-46d6-ae6f-318d0cb961bd อีกครั้ง

curl -X GET -H "Content-Type:application/json" -O -J https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd/result
-u email:password

หากต้องการเรียกไฟล์ที่ดาวน์โหลด คุณต้องกำหนดค่าเครื่องมือที่ใช้ เพื่อให้ระบบบันทึกไฟล์ที่ดาวน์โหลด เช่น

• หากใช้ cURL คุณจะใช้ตัวเลือก -O -J ได้ดังที่แสดงด้านบน

• หากใช้ Postman คุณจะต้องเลือกปุ่มบันทึกและดาวน์โหลด ในกรณีนี้ ระบบจะดาวน์โหลดไฟล์ ZIP ชื่อ response

• หากคุณใช้เบราว์เซอร์ Chrome ระบบจะยอมรับการดาวน์โหลดโดยอัตโนมัติ

หากคำขอสำเร็จและมีชุดผลลัพธ์ที่ไม่ใช่ 0 ระบบจะดาวน์โหลดผลลัพธ์ไปยังไคลเอ็นต์เป็นไฟล์ JSON ที่บีบอัด (คั่นด้วยการขึ้นบรรทัดใหม่) ชื่อไฟล์ที่ดาวน์โหลดจะเป็นดังนี้

OfflineQueryResult-<query-id>.zip

เช่น

OfflineQueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd.zip

ไฟล์ ZIP มีไฟล์ที่เก็บถาวร .gz ของผลลัพธ์ JSON หากต้องการเข้าถึงไฟล์ JSON ให้แตกไฟล์ดาวน์โหลด แล้วใช้คำสั่ง gzip เพื่อดึงไฟล์ JSON ดังนี้

unzip OfflineQueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd.zip
gzip -d QueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd-000000000000.json.gz

เกี่ยวกับเนื้อหาของคำขอ

ส่วนนี้จะอธิบายพารามิเตอร์แต่ละรายการที่คุณใช้ในเนื้อหาคำขอ JSON สำหรับการค้นหาได้ โปรดดูรายละเอียดเกี่ยวกับเมตริกและมิติข้อมูลที่คุณใช้ในการค้นหาได้ที่ข้อมูลอ้างอิงของ Analytics

{  
   "metrics":[  
      {  
        "name":"metric_name",
        "function":"aggregation_function",
        "alias":"metric_dispaly_name_in_results",
        "operator":"post_processing_operator",
        "value":"post_processing_operand"
      },
   ...
   ],
   "dimensions":[  
      "dimension_name",
      ...
   ],
   "timeRange":"time_range",
   "limit":results_limit,
   "filter":"filter",
   "groupByTimeUnit": "grouping",
   "outputFormat": "format",
   "csvDelimiter": "delimiter"
}

"metrics":[  
  {  
    "name":"response_processing_latency",
    "function":"avg",
    "alias":"average_response_time_in_seconds",
    "operator":"/",
    "value":"1000"
  }
]

"timeRange": {
    "start": "2018-07-29T00:13:00Z",
    "end": "2018-08-01T00:18:00Z"
}

ไวยากรณ์ของนิพจน์ตัวกรอง

ส่วนอ้างอิงนี้จะอธิบายโทเค็นที่ใช้สร้างนิพจน์ตัวกรองในเนื้อหาคำขอได้ ตัวอย่างเช่น นิพจน์ต่อไปนี้ใช้โทเค็น "ge" (มากกว่าหรือเท่ากับ)

"filter":"(message_count ge 0)"

(apiproxy in 'ethorapi','weather-api')

(apiproxy in 'ethorapi')

(apiproxy in 'Search','ViewItem')

(response_status_code in 400,401,500,501)

(response_status_code notin 400,401,500,501)

(response_status_code eq 504)

(apiproxy eq 'non-prod')

(response_status_code ne 500)

(apiproxy ne 'non-prod')

(response_status_code gt 500)

(response_status_code lt 500)

(target_response_code ge 400)

(target_response_code le 300)

(apiproxy like '%buy%')

(apiproxy like '%item')

(apiproxy like 'Prod%')

(apiproxy not like '%buy%')

(apiproxy not like '%item')

(apiproxy not like 'Prod%')

(target_response_code gt 399) and (response_status_code ge 400)

(response_size ge 1000) or (response_status_code eq 500)

ข้อจำกัดและค่าเริ่มต้น

รายการข้อจำกัดและค่าเริ่มต้นของฟีเจอร์การประมวลผลข้อมูลการค้นหาแบบอะซิงโครนัสมีดังนี้

เกี่ยวกับผลการค้นหา

ต่อไปนี้เป็นตัวอย่างผลลัพธ์ในรูปแบบ JSON เอาต์พุตประกอบด้วยแถว JSON ที่คั่นด้วยตัวคั่นบรรทัดใหม่ ดังนี้

{"message_count":"10209","apiproxy":"guest-auth-v3","hour":"2018-08-07 19:26:00 UTC"}
{"message_count":"2462","apiproxy":"carts-v2","hour":"2018-08-06 13:16:00 UTC"}    
…

คุณดึงผลลัพธ์จาก URL ได้จนกว่าข้อมูลในที่เก็บจะหมดอายุ โปรดดูข้อจำกัดและค่าเริ่มต้น

ตัวอย่าง

ตัวอย่างที่ 1: ผลรวมของจำนวนข้อความ

ข้อความค้นหาสำหรับจำนวนรวมของจำนวนข้อความใน 60 นาทีที่ผ่านมา

การค้นหา

curl -X POST -H "Content-Type: application/json" -H "Accept: application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries"
-d @last60minutes.json
-u orgAdminEmail:password

เนื้อความของคำขอจาก last60minutes.json

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":"last60minutes"
}

ตัวอย่างที่ 2: ช่วงเวลาที่กำหนดเอง

การค้นหาโดยใช้ช่วงเวลาที่กำหนดเอง

การค้นหา

curl -X POST -H "Content-Type: application/json" -H "Accept: application/json"
https://api.enterprise.apigee.com/v1 /organizations/myorg/environments/test/queries"
-d @last60minutes.json
-u orgAdminEmail:password

เนื้อหาของคำขอจาก last60minutes.json

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum"
      },
      {  
         "name":"total_response_time",
         "function":"avg",
         "alias":"average_response_time"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":{  
      "start":"2018-11-01T11:00:00Z",
      "end":"2018-11-30T11:00:00Z"
   }
}

ตัวอย่างที่ 3: ธุรกรรมต่อนาที

การค้นหาเมตริกสำหรับธุรกรรมต่อนาที (tpm)

การค้นหา

curl -X POST -H "Content-Type: application/json" -H "Accept: application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries"
-d @tpm.json
-u orgAdminEmail:password

เนื้อหาของคำขอจาก tpm.json

{  
   "metrics":[  
      {  
         "name":"tpm"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":{  
      "start":"2018-07-01T11:00:00Z",
      "end":"2018-07-30T11:00:00Z"
   }
}

ตัวอย่างผลการค้นหา

ข้อความที่ตัดตอนมาจากไฟล์ผลลัพธ์

{"tpm":149995.0,"apiproxy":"proxy_1","minute":"2018-07-06 12:16:00 UTC"}
{"tpm":149998.0,"apiproxy":"proxy_1","minute":"2018-07-09 15:12:00 UTC"}
{"tpm":3.0,"apiproxy":"proxy_2","minute":"2018-07-11 16:18:00 UTC"}
{"tpm":148916.0,"apiproxy":"proxy_1","minute":"2018-07-15 17:14:00 UTC"}
{"tpm":150002.0,"apiproxy":"proxy_1","minute":"2018-07-18 18:11:00 UTC"}
...

ตัวอย่างที่ 4: การใช้นิพจน์ตัวกรอง

การค้นหาด้วยนิพจน์ตัวกรองที่ใช้โอเปอเรเตอร์บูลีน

การค้นหา

curl -X POST -H "Content-Type:application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries"
-d @filterCombo.json
-u orgAdminEmail:password

เนื้อหาคำขอจาก filterCombo.json

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum"
      },
      {  
         "name":"total_response_time",
         "function":"avg",
         "alias":"average_response_time"
      }
   ],
   "filter":"(apiproxy ne \u0027proxy_1\u0027) and (apiproxy ne \u0027proxy_2\u0027)",
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":{  
      "start":"2018-11-01T11:00:00Z",
      "end":"2018-11-30T11:00:00Z"
   }
}

ตัวอย่างที่ 5: การส่งนิพจน์ในพารามิเตอร์เมตริก

การค้นหาที่มีนิพจน์ซึ่งส่งผ่านโดยเป็นส่วนหนึ่งของพารามิเตอร์เมตริก คุณสามารถใช้นิพจน์โอเปอเรเตอร์อย่างง่ายเพียงนิพจน์เดียว

การค้นหา

curl -X POST -H "Content-Type:application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries" 
-d @metricsExpression.json
-u orgAdminEmail:password

เนื้อหาของคำขอจากmetricExpression.json

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum",
         "operator":"/",
         "value":"7"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":10,
   "timeRange":"last60minutes"
}

วิธีค้นหารายงานการสร้างรายได้แบบไม่พร้อมกัน

คุณสามารถบันทึกธุรกรรมการสร้างรายได้ที่สำเร็จทั้งหมดภายในช่วงเวลาที่ระบุสำหรับเกณฑ์ที่เฉพาะเจาะจงโดยใช้ขั้นตอนที่อธิบายไว้ในส่วนนี้

เช่นเดียวกับคำค้นหาใน Analytics แบบไม่พร้อมกัน คุณจะสร้างคำค้นหารายงานการสร้างรายได้แบบไม่พร้อมกันได้ใน 3 ขั้นตอน ได้แก่ (1) ส่งคำค้นหา (2) ดูสถานะคำค้นหา และ (3) เรียกดูผลการค้นหา

ขั้นตอนที่ 1 นั่นคือการส่งคำค้นหา ซึ่งอธิบายไว้ด้านล่าง

ขั้นตอนที่ 2 และ 3 เหมือนกันทุกประการกับคำค้นหา Analytics แบบไม่พร้อมกัน ดูข้อมูลเพิ่มเติมได้ที่วิธีสร้างคำค้นหา Analytics แบบไม่พร้อมกัน

หากต้องการส่งคำค้นหารายงานการสร้างรายได้แบบไม่พร้อมกัน ให้ส่งคำขอ POST ไปที่ /mint/organizations/org_id/async-reports

(ไม่บังคับ) คุณระบุสภาพแวดล้อมโดยการส่งพารามิเตอร์การค้นหา environment ได้ หากไม่ได้ระบุไว้ พารามิเตอร์การค้นหาจะมีค่าเริ่มต้นเป็น prod เช่น

/mint/organizations/org_id/async-reports?environment=prod

ในเนื้อหาคำขอ ให้ระบุเกณฑ์การค้นหาต่อไปนี้

"devCriteria":[{
    "id":"RtHAeZ6LtkSbEH56",
    "orgId":"my_org"}
]

ตัวอย่างเช่น คำขอต่อไปนี้จะสร้างรายงานการสร้างรายได้แบบไม่พร้อมกันในเดือนมิถุนายน 2017 สำหรับผลิตภัณฑ์ API และรหัสนักพัฒนาซอฟต์แวร์ที่ระบุ วันที่และเวลาของรายงาน fromDate และ toDate เป็นเวลา UTC/GMT และอาจรวมเวลาไว้ด้วย

curl -H "Content-Type:application/json" -X POST -d \
'{
      "fromDate":"2017-06-01 00:00:00",
      "toDate":"2017-06-30 00:00:00",    
     "productIds": [
        "a_product"
    ],
    "devCriteria": [{
        "id": "AbstTzpnZZMEDwjc",
        "orgId": "myorg"
    }]

 }' \
"https://api.enterprise.apigee.com/v1/mint/organizations/myorg/async-reports?environment=prod" \
-u orgAdminEmail:password