Outil GraphiQL

GraphiQL permet d'explorer le schéma et de tester des requêtes pour le noeud final GraphQL.

1. Télécharger et installer GraphiQL.
2. Ouvrez l'application GraphiQL et entrez les en-têtes HTTP que vous souhaitez autoriser.
3. Entrez le noeud final correct dans la zone GraphQl Endpoint. Utilisez https://api.cis.cloud.ibm.com/v1/<crn>/zones/<zoneid>/graphql.

La fenêtre se compose d'un panneau de requête et d'un panneau de réponse. Vous pouvez définir les variables de requête, qui sont interpolées dans la requête dans le panneau de requête.

Pour générer une requête, procédez comme suit :

1. Sélectionnez POST dans le menu déroulant Method.
2. Cliquez sur Edit HTTP Headers.
3. Entrez le jeton X-Auth-User-Token ou Authorization et définissez application/json pour Content-Type:. Sauvegardez les données.

Commencez à générer votre requête dans le panneau de requête. Utilisez Document Explorer pour explorer le schéma et la documentation. Document Explorer affiche différentes options disponibles pour des jeux de données, des opérations et des fonctions. Les termes "zone" et "domaine" sont synonymes dans Document Explorer.

Créez le fragment test suivant dans le panneau de requête et observez la réponse dans le panneau de réponse en ajustant la valeur de datetime en fonction de vos besoins ;

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

Paramètres de requête pour les limites d'un compte

Pour obtenir des informations spécifiques sur les limites d'un noeud de données, utilisez le noeud settings.

Voici un exemple de requête :

{
  viewer {
    zones(filter: { zoneTag: $zoneTag }) {
      settings {
        browserInsightsAdaptiveGroups {
          maxDuration
          maxNumberOfFields
          maxPageSize
          enabled
          notOlderThan
        }
      }
    }
  }
}

La réponse de la requête est la suivante :

{
  "data": {
    "viewer": {
      "zones": [
        {
          "settings": {
            "browserInsightsAdaptiveGroups": {
              "enabled": true,
              "maxDuration": 2592000,
              "maxNumberOfFields": 30,
              "maxPageSize": 10000,
              "notOlderThan": 2595600
            }
          }
        }
      ]
    }
  },
  "errors": null
}

Limites de requête

Le volume de données qu'une requête peut renvoyer est limité et des limites sont appliquées au volume de données quotidien par utilisateur. Les limites suivantes s'appliquent en plus des limites de débit générales mises en place par l'API :

• Une requête dont la portée est définie au niveau des zones peut inclure jusqu'à dix zones.
• Les requêtes peuvent demander jusqu'à 30 zones, comme indiqué par maxNumberOfFields dans settings.
• Les réponses peuvent renvoyer jusqu'à 10000 enregistrements. Cette limite est indiquée par maxPageSize dans settings.

Les requêtes doivent spécifier explicitement le nombre maximal d'enregistrements à renvoyer à l'aide de l'argument limit.

Exemples de tri

Tri de données brutes :

firewallEventsAdaptive (orderBy: [clientCountryName_ASC]) {
    clientCountryName
}

Tri de données brutes à l'aide de zones multiples :

firewallEventsAdaptive (orderBy: [clientCountryName_ASC, datetime_DESC]) {
    clientCountryName
    datetime
}

Tri de groupes par fonction d'agrégation :

httpRequests1hGroups (orderBy: [sum_bytes_DESC]){
    sum {
        bytes
        requests
    }
    dimensions {
        datetime
    }
}

Pages de requête sans curseurs

L'exemple suivant suppose que les relations date et clientCountryName sont uniques.

Obtenez les premiers résultats N d'une requête.

Pour limiter les résultats, ajoutez le paramètre limit. Par exemple, demandez les deux premiers enregistrements.

firewallEventsAdaptive (limit: 2, orderBy: [datetime_ASC, clientCountryName_ASC]) {
    datetime
    clientCountryName
}

La spécification d'un ordre de tri par date renvoie des résultats moins précis que la spécification d'un ordre de tri par date et par pays.

La réponse de la requête est la suivante :

{
  "firewallEventsAdaptive" : [
    {
      "datetime": "2018-11-12T00:00:00Z",
      "clientCountryName": "UM"
    },
    {
      "datetime": "2018-11-12T00:00:00Z",
      "clientCountryName": "US"
    }
  ]
}

Requête de la page suivante à l'aide d'un filtre

Pour obtenir les résultats N suivants, spécifiez un filtre pour exclure le dernier résultat de la requête précédente. A l'aide de l'exemple précédent, vous pouvez ajouter l'opérateur supérieur à (_gt) à la zone clientCountryName et l'opération supérieur ou égal à à la zone datetime. En définissant un ordre spécifique, vous pouvez obtenir les résultats les plus complets.

firewallEventsAdaptive (limit: 2, orderBy: [datetime_ASC, clientCountryName_ASC], filter: {date_geq: "2018-11-12T00:00:00Z", clientCounterName_gt: "US"}) {
    date
    clientCountryName
}

La réponse de la requête est la suivante :

{
  "firewallEventsAdaptive" : [
    {
      "datetime": "2018-11-12T00:00:00Z",
      "clientCountryName": "UY"
    },
    {
      "datetime": "2018-11-12T00:00:00Z",
      "clientCountryName": "UZ"
    }
  ]
}

Requête de la page précédente

Pour obtenir les résultats N précédents, inverses les filtres et l'ordre de tri.

firewallEventsAdaptive (limit: 2, orderBy: [datetime_DESC, clientCountryName_DESC, filter: {date_leq: "2018-11-12T00:00:00Z", clientCountryName_lt: "UY"}]) {
  datetime
  clientCountryName
}

La réponse de la requête est la suivante :

{
  "firewallEventsAdaptive" : [
    {
      "datetime": "2018-11-12T00:00:00Z",
      "clientCountryName": "US"
    },
    {
      "datetime": "2018-11-12T00:00:00Z",
      "clientCountryName": "UM"
    }
  ]
}

Structure

Le filtre GraphQL est représenté par l'objet d'entrée GraphQL.

Des filtres peuvent être utilisés en tant qu'argument pour les ressources suivantes :

• Zones (domaines)
• Tables (jeux de données)
• Comptes

Filtre de zone (domaine)

Le filtre de zone permet la requête de données liées à des zones en fonction d'un ID de zone (domaine) (zoneTag).

zones(filter: {zoneTag: "your domain (zone) ID"}) {
    ...
}

Le filtre de zone doit respecter la syntaxe suivante :

filter
    { zoneTag: t }
    { zoneTag_gt: t }
    { zoneTag_in: [t, ...] }

Les filtres composés (séparés par une virgule, AND, OR) ne sont pas pris en charge. Les zones sont toujours triées par ordre alphanumérique.

Filtre de table (jeu de données)

Les filtres de table requièrent l'interrogation d'au moins un noeud. L'opérateur AND peut être utilisé pour créer et combiner des filtres à noeuds multiples.

Filtres de compte

Le filtrage au niveau d'un compte est pris en charge et il existe un paramètre de filtre obligatoire. Exemple :

accounts(filter: {accountTag: $accountTag}) {
    ...
}

Opérateurs

La prise en charge des opérateurs varie en fonction du type et du nom de noeud. Les opérateurs suivants sont pris en charge pour tous les types :

Exemples

Exemple général :

{
  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"
    }
  )
}

Filtrage d'un noeud spécifique :

httpRequests1hGroups(filter: {datetime: "2020-01-01 10:00:00"}) {
    ...
}

Filtrage de plusieurs zones :

httpRequests1hGroups(filter: {datetime_gt: "2018-01-01 10:00:00", datetime_lt: "2018-01-01 11:00:00"}) {
    ...
}

Filtrage à l'aide de l'opérateur OR :

httpRequests1hGroups(filter: {
    datetime: "2020-01-01 10:00:00",
    OR:[{clientCountryName: "US"}, {clientCountryName: "UK"}]) {
    ...
}