配置GraphQL
GraphQL是 API 的查詢語言。 您可以在單一上執行查詢 /graphql
端點。 GraphiQL使用內建的自省系統透過模式公開資訊。
GraphQL分析 API 端點僅適用於企業級計畫。
必要條件
您必須擁有下列權限才能繼續:
- 您必須擁有實例層級或區域層級的檢視者權限。
- 您必須擁有區域層級的讀者權限。
GraphiQL工具
使用GraphiQL,您可以探索架構並測試查詢GraphQL端點。
- 下載並安裝GraphiQL。
- 開啟 GraphiQL 應用程式,並輸入您要授權的 HTTP 標頭。
- 在中輸入正確的端點 GraphQl端點場地。 使用
https://api.cis.cloud.ibm.com/v1/<crn>/zones/<zoneid>/graphql
。
此視窗分為查詢窗格和回應窗格。 您可以定義查詢變數,這些變數會插入查詢窗格中的查詢。
若要建立查詢,請依照下列步驟操作。
- 選擇
POST
來自方法列表菜單。 - 按一下 Edit HTTP Headers(編輯 標頭 )。
- 輸入
X-Auth-User-Token
或授權令牌,並設定內容類型:application/json
。 一定要救救他們。
開始在查詢窗格中建立查詢。 使用文件瀏覽器探索架構和文件。 文件資源管理器顯示資料集、維度、操作和函數的不同可用選項。 「區域」和「域」這兩個字在文件資源管理器中是同義詞。
將以下測試片段貼到查詢窗格中,並觀察回應窗格中的回應,調整 datetime
滿足您的需求。
query {
viewer {
zones(filter: {zoneTag: "<your domain ID>"}) {
httpRequests1hGroups(limit: 5, filter: { datetime_gt: "2020-08-30T04:00:00Z", datetime_lt: "2020-08-31T06:00:00Z"}) {
sum {
countryMap {
bytes
clientCountryName
}
}
dimensions {
date
datetime
}
}
firewallEventsAdaptiveGroups(limit: 10, filter: { datetime_gt: "2020-08-30T04:00:00Z", datetime_lt: "2020-08-31T06:00:00Z"}) {
count
dimensions {
clientCountryName
clientAsn
datetimeHour
}
}
}
}
}
查詢基礎知識
GraphQL將資料結構為圖表。 要取得所需的數據,您可以探索圖表的邊緣。 這是一個範例查詢格式:
viewer {
zones(filter:...) {
requests(filter:...) {
date, time, bytes,...
}
}
}
使用者執行查詢的初始節點是 viewer
。 查看者能夠存取一個或多個網域(區域)。 每個區域包含不同的資料集,例如區域的防火牆事件。
表示聚合資料的節點包括 groups
後綴,例如 firewallEventsAdaptiveGroups
。 每個群組都遵循特定的結構,如下例所示。
type ExampleGroup {
count # No subfields, it is just the group size.
sum {
# fields that support summing (numbers, maps of numbers)
}
avg {
# fields that support averaging (numbers)
}
uniq {
# fields that support uniqueing (numbers, strings, enums, IPs, dates, etc.)
}
}
此範例顯示了一個有效的群組:
httpRequests1mGroups {
sum {
bytes
}
uniq {
uniques # unique IPs
}
dimensions {
datetimeMinute
}
}
資料集
以下是可用的常用資料集的清單。 有關資料集的更多信息,您可以使用 GraphQL自省機制。
資料集 | Node |
---|---|
瀏覽器洞察 | browserInsightsAdaptiveGroups |
防火牆活動日誌 | firewallEventsAdaptive firewallEventsAdaptiveByTimeGroups |
防火牆分析 | firewallEventsAdaptiveGroups |
健康檢查分析 | healthCheckEvents healthCheckEventsGroups |
HTTP 要求 | httpRequests1mGroups httpRequests1hGroups httpRequests1dGroups httpRequestsAdaptiveGroups |
影像調整大小分析 | imageResizingRequests1mGroups |
負載平衡分析 | loadBalancingRequests loadBalancingRequestsGroups |
SYN 攻擊(DoS分析) | synAvgPps1mGroups |
邊緣函數指標 | workersInvocationsAdaptive |
錯誤
GraphQL Analytics API 是基於 HTTPS 請求與 JSON 回應的 RESTful API,並會傳回我們熟悉的 HTTP 狀態代碼 (例如 404
, 500
, 504
)。依照 GraphQL 規格,200
回應可以包含錯誤,這與一般的 REST 方式不同。
所有回應都包含一個錯誤數組,如果沒有錯誤,則該數組為空。 非空錯誤包含 message
,path
,和 timestamp
。
以下代碼是錯誤回應的範例:
{
"data": null,
"errors": [
{
"message": "cannot request data older than 2678400s",
"path": [
"viewer",
"zones",
"0",
"firewallEventsAdaptiveGroups"
],
"extensions": {
"timestamp": "2019-12-09T21:27:19.195060142Z"
}
}
]
}
限制
下表定義了保留歷史資料的限制。
資料節點 | 企業 |
---|---|
browserInsightsAdaptiveGroups |
30 天 |
firewallEventsAdaptiveByTimeGroups |
30 天 |
firewallEventsAdaptiveGroups |
30 天 |
healthCheckEventsGroups |
90 天 |
healthCheckEvents |
90 天 |
httpRequestsAdaptiveGroups |
30 天 |
httpRequests1dGroups |
365 天 |
httpRequests1hGroups |
90 天 |
httpRequests1mGroups |
7 天 |
loadBalancingRequestsGroups |
30 天 |
loadBalancingRequests |
30 天 |
synAvgPps1mGroups |
7 天 |
查詢帳戶限額設定
要獲取有關資料節點限制的特定信息,請使用 settings
節點。
欄位 | 說明 |
---|---|
enabled |
退貨 true 資料集(節點)是否可用於目前計劃。 |
maxDuration |
定義一次查詢中可以請求的最大時間段(以秒為單位)(因資料節點而異)。 |
maxNumberOfFields |
定義一次查詢中可以請求的最大欄位數(因資料節點而異)。 |
maxPageSize |
定義一次查詢中可以傳回的最大記錄數(因資料節點而異)。 |
notOlderThan |
限制查詢可以在記錄中搜尋多遠(以秒為單位,因資料節點和計劃而異)。 |
以下是一個查詢範例:
{
viewer {
zones(filter: { zoneTag: $zoneTag }) {
settings {
browserInsightsAdaptiveGroups {
maxDuration
maxNumberOfFields
maxPageSize
enabled
notOlderThan
}
}
}
}
}
查詢回應如下:
{
"data": {
"viewer": {
"zones": [
{
"settings": {
"browserInsightsAdaptiveGroups": {
"enabled": true,
"maxDuration": 2592000,
"maxNumberOfFields": 30,
"maxPageSize": 10000,
"notOlderThan": 2595600
}
}
}
]
}
},
"errors": null
}
查詢限制
查詢可以傳回的資料量是有限的,且使用者每天的資料量有限制。 除了 API 強制執行的一般速率限制之外,還適用以下限制:
- 區域範圍的查詢最多可以包含 10 個區域。
- 查詢最多可以請求 30 個字段,如下所示
maxNumberOfFields
在settings
。 - 回應最多可傳回 10,000 筆記錄。 此限制由下式表示
maxPageSize
在settings
。
查詢必須使用以下命令明確指定要傳回的記錄的上限 limit
爭論。
排序
您可以使用以下命令對查詢結果元素的順序進行排序 orderBy
爭論。 預設情況下,結果會按資料集(表)的主鍵排序。 如果您指定另一個欄位進行排序,則主鍵將包含在排序鍵中,以保持分頁結果的一致性。
不支援嵌套結構內的排序。
排序範例
原始資料排序:
firewallEventsAdaptive (orderBy: [clientCountryName_ASC]) {
clientCountryName
}
使用多個欄位對原始資料進行排序:
firewallEventsAdaptive (orderBy: [clientCountryName_ASC, datetime_DESC]) {
clientCountryName
datetime
}
透過聚合函數進行分組排序:
httpRequests1hGroups (orderBy: [sum_bytes_DESC]){
sum {
bytes
requests
}
dimensions {
datetime
}
}
分頁
分頁,將查詢結果分解成更小的部分,可以使用 limit
,orderBy
,以及過濾參數。 這GraphQL Analytics API 不支援分頁遊標。
limit
(整數)定義要傳回的記錄數。orderBy
(字串)定義資料的排序順序。
沒有遊標的查詢頁面
以下範例假設 date
和 clientCountryName
關係是獨一無二的。
獲得第一個_n_查詢的結果。
若要限制結果,請新增 limit
範圍。 例如查詢前兩筆記錄。
firewallEventsAdaptive (limit: 2, orderBy: [datetime_ASC, clientCountryName_ASC]) {
datetime
clientCountryName
}
按日期指定排序順序傳回的具體結果比按日期和國家/地區指定排序順序傳回的具體結果要少。
查詢回應如下:
{
"firewallEventsAdaptive" : [
{
"datetime": "2018-11-12T00:00:00Z",
"clientCountryName": "UM"
},
{
"datetime": "2018-11-12T00:00:00Z",
"clientCountryName": "US"
}
]
}
使用過濾器查詢下一頁
為了得到下一個_n_ results,指定一個篩選器以排除上一個查詢中的最後一個結果。 使用前面的範例,您可以附加大於運算子 (_gt
)到 clientCountryName
字段和大於或等於運算符 datetime
場地。 透過制定特定的訂單,您可以獲得最完整的結果。
firewallEventsAdaptive (limit: 2, orderBy: [datetime_ASC, clientCountryName_ASC], filter: {date_geq: "2018-11-12T00:00:00Z", clientCounterName_gt: "US"}) {
date
clientCountryName
}
查詢回應如下:
{
"firewallEventsAdaptive" : [
{
"datetime": "2018-11-12T00:00:00Z",
"clientCountryName": "UY"
},
{
"datetime": "2018-11-12T00:00:00Z",
"clientCountryName": "UZ"
}
]
}
查詢上一頁
為了得到之前的_n_結果,反轉過濾器並排序順序。
firewallEventsAdaptive (limit: 2, orderBy: [datetime_DESC, clientCountryName_DESC, filter: {date_leq: "2018-11-12T00:00:00Z", clientCountryName_lt: "UY"}]) {
datetime
clientCountryName
}
查詢回應如下:
{
"firewallEventsAdaptive" : [
{
"datetime": "2018-11-12T00:00:00Z",
"clientCountryName": "US"
},
{
"datetime": "2018-11-12T00:00:00Z",
"clientCountryName": "UM"
}
]
}
過濾
篩選器將查詢限制為特定帳戶或一組區域(網域)、按日期的請求或特定查詢代理。 如果沒有過濾器,效能可能會下降,且結果可能包含不重要的資料。
結構
這GraphQL過濾器表示為 GraphQL輸入對象。
過濾器可以用作以下資源的參數:
- 區域(域)
- 表格(資料集)
- 帳戶
區域(域)過濾器
區域過濾器允許透過區域(域)ID 查詢區域相關資料(zoneTag
)。
zones(filter: {zoneTag: "your domain (zone) ID"}) {
...
}
區域過濾器必須符合以下語法:
filter
{ zoneTag: t }
{ zoneTag_gt: t }
{ zoneTag_in: [t, ...] }
複合過濾器(逗號分隔,AND
,OR
)不支持。 區域始終按字母數字排序。
表(資料集)過濾器
表格過濾器要求您至少查詢一個節點。 這 AND
運算符可用於建立和組合多節點過濾器。
帳戶過濾器
支援帳戶級別過濾,並且有必填的過濾參數。 例如:
accounts(filter: {accountTag: $accountTag}) {
...
}
Operator
操作員支援有所不同,取決於節點類型和節點名稱。 所有類型都支援下列運算符號:
操作員 | 比較 |
---|---|
gt |
大於 |
lt |
小於 |
geq |
大於或等於 |
leq |
小於或等於 |
neq |
不等於 |
in |
於 |
範例
一般範例:
{
myQuery(
filter: {
clientCountry: "UK" # all objects having client country equal to "UK"
datetime_gt: "2020-01-01 10:00:00" # all object having datetime greater than "2020-01-01 10:00:00"
}
)
}
過濾特定節點:
httpRequests1hGroups(filter: {datetime: "2020-01-01 10:00:00"}) {
...
}
對多個欄位進行過濾:
httpRequests1hGroups(filter: {datetime_gt: "2018-01-01 10:00:00", datetime_lt: "2018-01-01 11:00:00"}) {
...
}
過濾器使用 OR
操作員:
httpRequests1hGroups(filter: {
datetime: "2020-01-01 10:00:00",
OR:[{clientCountryName: "US"}, {clientCountryName: "UK"}]) {
...
}