IBM Cloud Docs
配置GraphQL

配置GraphQL

GraphQL是 API 的查詢語言。 您可以在單一上執行查詢 /graphql 端點。 GraphiQL使用內建的自省系統透過模式公開資訊。

GraphQL分析 API 端點僅適用於企業級計畫。

必要條件

您必須擁有下列權限才能繼續:

  • 您必須擁有實例層級或區域層級的檢視者權限。
  • 您必須擁有區域層級的讀者權限。

GraphiQL工具

使用GraphiQL,您可以探索架構並測試查詢GraphQL端點。

  1. 下載並安裝GraphiQL
  2. 開啟 GraphiQL 應用程式,並輸入您要授權的 HTTP 標頭。
  3. 在中輸入正確的端點 GraphQl端點場地。 使用 https://api.cis.cloud.ibm.com/v1/<crn>/zones/<zoneid>/graphql

此視窗分為查詢窗格和回應窗格。 您可以定義查詢變數,這些變數會插入查詢窗格中的查詢。

若要建立查詢,請依照下列步驟操作。

  1. 選擇 POST 來自方法列表菜單。
  2. 按一下 Edit HTTP Headers(編輯 標頭 )。
  3. 輸入 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自省機制

常用的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 個字段,如下所示 maxNumberOfFieldssettings
  • 回應最多可傳回 10,000 筆記錄。 此限制由下式表示 maxPageSizesettings

查詢必須使用以下命令明確指定要傳回的記錄的上限 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(字串)定義資料的排序順序。

沒有遊標的查詢頁面

以下範例假設 dateclientCountryName 關係是獨一無二的。

獲得第一個_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"}]) {
    ...
}