You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: products/analytics/src/content/graphql-api/getting-started/compose-graphql-query.md
+65-30Lines changed: 65 additions & 30 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,61 +5,96 @@ order: 50
5
5
6
6
# Create a query in a GraphQL client
7
7
8
-
You can use a GraphQL client to build and execute queries to the GraphQL API endpoint. The example below uses the GraphiQL client.
8
+
You can use a GraphQL client to build and execute queries to the GraphQL API endpoint. The example below uses the [GraphiQL](https://github.com/graphql/graphiql/tree/main/packages/graphiql#readme) client.
9
9
10
-
Before you begin, configure the API endpoint and HTTP headers in the GraphQL client.
10
+
## Prerequisites
11
11
12
-
Click on the editing pane of GraphiQL and add the following base query:
12
+
This article assumes that you are already familiar with [_Querying basics_](/graphql-api/getting-started/querying-basics).
13
13
14
-
```json
15
-
query {
16
-
viewer {
17
-
zones(filter: { zoneTag: "{zone-id}"}) {
14
+
Before you begin, [configure the API endpoint and HTTP headers](/graphql-api/getting-started/authentication/graphql-client-headers) in the GraphiQL client.
18
15
19
-
}
20
-
}
21
-
}
22
-
```
16
+
<Asidetype='tip'header='Tip'>
17
+
18
+
To explore the documentation for the data sets and fields in the Cloudflare GraphQL schema, click **Docs** to open the _Documentation Explorer_ pane.
19
+
20
+
For an introduction, see [Explore the GraphQL schema](/graphql-api/getting-started/explore-graphql-schema).
21
+
22
+
</Aside>
23
+
24
+
## Set up a query and choose a data set
25
+
26
+
Click on the editing pane of GraphiQL and add this base query, replacing `zone-id` with your Cloudflare zone ID:
23
27
24
-
To explore the documentation for the nodes and fields in the Cloudflare GraphQL schema, click **Docs** to open the _Documentation Explorer_ pane.
28
+
25
29
26
-
The GraphiQL client has auto completion, to assist query building. Place your cursor on the line under "zones" and start typing a word: a popup window appears, listing all the possible fields that contain that word. For example, if you type`firewall`, the popup displays the fields that return firewall information:
To find the ID for a zone, log in to your Cloudflare account and click the site for which you want to obtain the zone ID. In the Cloudflare dashboard **Overview** page, scroll to the **API** section in the right sidebar, which displays your zone ID and account ID.
33
+
34
+
</Aside>
35
+
36
+
To assist query building, the GraphiQL client has word completion. Place your cursor on the line below `zones` and start entering a value—a popup menu displays. For example, when you type `firewall`, the popup displays the data sets that return firewall information:
The text at the bottom of the list displays a short description of the data that the node returns.
31
41
32
-
Select the field you want to use and insert it into your query: either click the item in the list, or scroll using arrow keys and hit return.
42
+
Select the data set you want to query and insert it—either click the item in the list, or scroll using arrow keys and press <kbd>Return</kbd>. This example uses the `firewallEventsAdaptive` data set.
43
+
44
+
## Supply required parameters
45
+
46
+
Hover your mouse over a field to display a tooltip that describes the data set. In this example, hovering over the `firewallEventsAdaptive` node displays this description:
Hover your mouse over a field to open a popup window showing the documentation for that field. The following popup window appears when you hover over the `firewallEventsAdaptive` field:
50
+
To display information about the data set, including required parameters, click the data set name (blue text). The **Documentation Explorer** opens and displays details about the data set:
Click on the node name (blue text) to display information about the field, including the required parameters, in the _Documentation Explorer_ pane.
54
+
Note that the `filter` and `limit` arguments are required, as indicated by the exclamation mark (`!`) after their type definitions (gold text). In this example, the `orderBy` argument is not required, though when used it requires a value of type `ZoneFirewallEventsAdaptiveOrderBy`.
39
55
40
-
Click on the type definition (gold text) to display information about the field type in the _Documentation Explorer_ pane.
56
+
To browse a list of supported filter fields, click the filter type definition (gold text) in the Documentation Explorer. In this example the type is `ZoneFirewallEventsAdaptiveFilter_InputObject`:
41
57
42
-
Add the required parameters for the field in the editing pane: type the open parenthesis character, `(`, after the field name. GraphiQL inserts the closing parenthesis and opens a popup window with a list of required parameters:
To add the data fields that you want to display, type the opening bracket `{` after the closing parenthesis containing parameters. GraphiQL automatically inserts the closing bracket. For readability, hit the return key between the brackets.
64
+
## Define the fields to return with your query
49
65
50
-
Click the field type definition to display the list of fields in in the _Documentation Explorer_ pane:
66
+
To browse the fields you can return with your query, hover your cursor over the dataset name in your query, and in the tooltip that displays, click the data type definition (gold text):
51
67
52
-
Start typing the name of a field that you want to fetch, to open an auto-complete list. Once you have entered all the fields you want, click the **Play** button to submit the query. The response pane contains the data fetched from the Cloudflare GraphQL API endpoint.
70
+
**The Documentation Explorer** opens and displays a list of fields:
55
71
56
-
The GraphiQL client allows you to create variables to use in the query.
57
-
In the following example, the _Query variables_ pane contains a variable that represents a zone ID:
72
+
73
+
74
+
To add the data fields that you want to display, type an opening brace (`{`) after the closing parenthesis for the parameters, then start typing the name of a field that you want to fetch. Use word completion to choose a field.
75
+
76
+
This example query returns the `action`, `datetime`, `clientRequestHTTPHost`, and `userAgent` fields:
77
+
78
+
79
+
80
+
Once you have entered all the fields you want your query to return, you can click the **Play** button to submit the query. The response pane contains the data fetched from the Cloudflare GraphQL API endpoint.
The GraphiQL client allows you to create variables for use in your queries.
87
+
88
+
To add a query variable, click the **Query Variables** pane and enter a JSON object that defines your variable.
89
+
90
+
This example JSON object defines a query variable for a zone ID:
58
91
59
92
```json
60
93
{"zoneTag":"xxxxxxxxx"}
61
94
```
62
95
63
-
Use `$zoneTag`to refer to the variable in a query.
96
+
To use a variable in your query, prepend the `$` character to your variable name and use it to replace the desired value. When using a variable as a value in a query, do not wrap the variable in quotes as you would for a literal value.
Copy file name to clipboardExpand all lines: products/analytics/src/content/graphql-api/getting-started/execute-graphql-query.md
+7-4Lines changed: 7 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,19 +3,22 @@ title: Use curl to query the GraphQL API
3
3
order: 60
4
4
---
5
5
6
-
# Use CURL to query the GraphQL API
6
+
# Use curl to query the GraphQL API
7
7
8
8
You can submit a query you built up in the GraphiQL client as a payload in the `data` field of a POST request to the GraphQL API.
9
9
10
-
The advantage of executing the request as a CURL request is that you can redirect the response to a file, and execute other post processing methods.
10
+
The advantage of executing the request with [curl](https://curl.se/) is that you can redirect the response to a file, and execute other post processing methods.
11
11
12
-
The GraphQL endpoint requires valid JSON, so you must pass the query as the _value_ part of a JSON _key/value_ pair with a key named "query".
12
+
The GraphQL endpoint requires valid JSON, so you must pass the query as the _value_ part of a JSON _key:value_ pair with a key named "query".
13
13
14
14
Pass the list of variables in another JSON _key:value_ pair with a key named "variables".
15
15
16
16
The script below returns the firewall events in one zone over the last 24 hours:
17
17
18
-
```
18
+
```bash
19
+
---
20
+
header: Example bash script that uses curl to query Analytics API
21
+
---
19
22
#!/bin/bash
20
23
#
21
24
# This script fetches the last 24 hours of firewall events for the ZoneID passed
Refer to [_Data Sets (tables)_](/graphql-api/features/data-sets) for details on nomenclature and behavior of these nodes.
68
+
Refer to [_Data Sets (tables)_](/graphql-api/features/data-sets) for details on the nomenclature and behavior of these nodes.
69
69
70
70
To view the fields available for a particular data set, click on its type definition. If you click on the **ZoneFirewallEventsAdaptive** type definition in the **firewallEventsAdaptive** node, a list of fields is displayed:
0 commit comments