-
Notifications
You must be signed in to change notification settings - Fork 10.4k
Pcx 1086 analytics graphql update getting started #503
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
stumblefiend
merged 9 commits into
cloudflare:production
from
aaron-ruby-df:PCX-1086-analytics-graphql-update-getting-started
Feb 3, 2021
Merged
Changes from 7 commits
Commits
Show all changes
9 commits
Select commit
Hold shift + click to select a range
e3dcfdd
PCX-1086 Analytics GraphQL Getting started update
ariordan-docforce 7e7f604
PCX-1086 Fix article on exploring schema
aaron-ruby-df 8a7fff1
PCX-1086 Minor copy edits
aaron-ruby-df 9bba90e
PCX-1086 Edit Explore schema topic
aaron-ruby-df fd7d47b
PCX-1086 Edits for building a query in graphql
aaron-ruby-df 4e2239c
PCX-1086 Update header name
aaron-ruby-df 4dd3c99
PCX-1086 Address comments and edits
aaron-ruby-df 7697d77
PCX-1086 Incorporated comments
aaron-ruby-df 64ce9fc
Merge branch 'production' into PCX-1086-analytics-graphql-update-gett…
stumblefiend File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
33 changes: 33 additions & 0 deletions
33
...rc/content/graphql-api/getting-started/authentication/graphql-client-headers.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,33 @@ | ||
| --- | ||
| title: Configure GraphQL client endpoint and HTTP headers | ||
| order: 40 | ||
| --- | ||
|
|
||
| # Configure GraphQL client endpoint and HTTP headers | ||
|
|
||
| 1. Launch _GraphiQL_. | ||
| 1. Click **Edit HTTP Headers**. | ||
|  | ||
| The _Edit HTTP Headers_ window appears. | ||
|  | ||
| 1. Click **Add Header**. | ||
|  | ||
| 1. Enter **X-AUTH-EMAIL** in the _Header name_ field and your email address registered with Cloudflare in the _Header value_ field, and click **Save**. | ||
| 1. To configure authentication, click **Add Header**. You can use Cloudflare Analytics API token authentication (recommended) or Cloudflare API key authentication. | ||
| * **Token authentication**: | ||
| Enter **Authorization** in the _Header Name_ field, and enter **Bearer {your-analytics-token}** in the _Header value_ field, then click **Save**. | ||
|  | ||
| * **Key authentication**: | ||
| Enter **X-AUTH-KEY** in the _Header Name_ field, and paste your Global API Key in the _Header value_ field, then click **Save**. | ||
|  | ||
| 1. Click anywhere outside the _Edit HTTP Headers_ window in _GraphiQL_ to close it and return to the main _GraphiQL_ display. | ||
| 1. Enter `https://api.cloudflare.com/client/v4/graphql` in the _GraphQL Endpoint_ field | ||
|  | ||
|
|
||
| <Aside type='note' header='Note'> | ||
|
|
||
| The right-side response pane is empty when you enter your information correctly. An error displays when there are problems with your header credentials. | ||
|
|
||
| </Aside> | ||
|
|
||
| Now that you have configured authentication with a Cloudflare API key, you are ready to run queries using _GraphiQL_. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
100 changes: 100 additions & 0 deletions
100
...ucts/analytics/src/content/graphql-api/getting-started/compose-graphql-query.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,100 @@ | ||
| --- | ||
| title: Create a query in GraphiQL | ||
| order: 50 | ||
| --- | ||
|
|
||
| # Create a query in GraphiQL | ||
|
|
||
| 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. | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| This article assumes that you are already familiar with [_Querying basics_](/graphql-api/getting-started/querying-basics). | ||
|
|
||
| Before you begin, [configure the API endpoint and HTTP headers](/graphql-api/getting-started/authentication/graphql-client-headers) in the GraphiQL client. | ||
|
|
||
| <Aside type='tip' header='Tip'> | ||
|
|
||
| To explore the documentation for the data sets and fields in the Cloudflare GraphQL schema, click **Docs** to open the _Documentation Explorer_ pane. | ||
|
|
||
| For an introduction, see [Explore the GraphQL schema](/graphql-api/getting-started/explore-graphql-schema). | ||
|
|
||
| </Aside> | ||
|
|
||
| ## Set up a query and choose a data set | ||
|
|
||
| Click on the editing pane of GraphiQL and add this base query, replacing `zone-id` with your Cloudflare zone ID: | ||
|
|
||
|  | ||
|
|
||
| <Aside type='tip' header='Tip'> | ||
|
|
||
| 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. | ||
|
|
||
| </Aside> | ||
|
|
||
| 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. | ||
|
|
||
| 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. | ||
stumblefiend marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| ## Supply required parameters | ||
|
|
||
| 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: | ||
|
|
||
|  | ||
|
|
||
| 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: | ||
|
|
||
|  | ||
|
|
||
| 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`. | ||
|
|
||
| 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`: | ||
|
|
||
|  | ||
|
|
||
| This example query shows the required `filter` and `limit` arguments for `firewallEventsAdaptive`: | ||
|
|
||
|  | ||
|
|
||
| ## Define the fields to return with your query | ||
|
|
||
| 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): | ||
|
|
||
|  | ||
|
|
||
| **The Documentation Explorer** opens and displays a list of fields: | ||
|
|
||
|  | ||
|
|
||
| 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. | ||
|
|
||
| This example query returns the `action`, `datetime`, `clientRequestHTTPHost`, and `userAgent` fields: | ||
|
|
||
|  | ||
|
|
||
| Once you have entered all the fields you want your query to return, click the **Play** button to submit the query. The response pane contains the data fetched from the Cloudflare GraphQL API endpoint. | ||
|
|
||
|  | ||
|
|
||
| ## Variable substitution | ||
|
|
||
| The GraphiQL client allows you to create variables for use in your queries. | ||
|
|
||
| To add a query variable, click the **Query Variables** pane and enter a JSON object that defines your variable. | ||
|
|
||
| This example JSON object defines a query variable for a zone ID: | ||
|
|
||
| ```json | ||
| {"zoneTag":"xxxxxxxxx"} | ||
| ``` | ||
|
|
||
| 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. | ||
|
|
||
| This example query uses the zoneTag query variable to represent the zone ID: | ||
|
|
||
|  | ||
71 changes: 71 additions & 0 deletions
71
...ucts/analytics/src/content/graphql-api/getting-started/execute-graphql-query.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,71 @@ | ||
| --- | ||
| title: Use curl to query the GraphQL API | ||
| order: 60 | ||
| --- | ||
|
|
||
| # Use curl to query the Analytics API | ||
|
|
||
| You can submit a query built with the GraphiQL client as the payload in the `data` field of a POST request to the Analytics API. | ||
|
|
||
| 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. | ||
|
|
||
| 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". | ||
|
|
||
| Pass the list of variables in another JSON _key:value_ pair with a key named "variables". | ||
|
|
||
| The script below returns the firewall events in one zone over the last 24 hours: | ||
|
|
||
| ```bash | ||
| --- | ||
| header: Example bash script that uses curl to query Analytics API | ||
| --- | ||
| #!/bin/bash | ||
| # | ||
| # This script fetches the last 24 hours of firewall events for the ZoneID passed | ||
| # in as the first parameter using the global key passed in as the second parameter. | ||
| ###################################################################################### | ||
|
|
||
| ZoneID="$1" | ||
| global_key="$2" | ||
| Email="[email protected]" | ||
| # | ||
| # Calculate 24 hours back and produce the start and end times in the appropriate format. | ||
| back_seconds=60*60*24 # 24 hours | ||
| end_epoch=$(date +'%s') | ||
| let start_epoch=$end_epoch-$back_seconds | ||
| start_date=$(date --date="@$start_epoch" +'%Y-%m-%dT%H:%m:%SZ') | ||
| end_date=$(date --date="@$end_epoch" +'%Y-%m-%dT%H:%m:%SZ') | ||
|
|
||
| PAYLOAD='{ "query": | ||
| "query { | ||
| viewer { | ||
| zones(filter: { zoneTag: $zoneTag }) { | ||
| firewallEventsAdaptive( | ||
| filter: $filter | ||
| limit: 10000 | ||
| orderBy: [datetime_DESC, rayName_DESC] | ||
| ) { | ||
| action, | ||
| datetime, | ||
| rayName, | ||
| clientRequestHTTPHost, | ||
| userAgent | ||
| } | ||
| } | ||
| } | ||
| }",' | ||
| PAYLOAD="$PAYLOAD | ||
|
|
||
| \"variables\": { | ||
| \"zoneTag\": \"$ZoneID\", | ||
| \"filter\": { | ||
| \"datetime_gt\": \"$start_date\", | ||
| \"datetime_leq\": \"$end_date\" | ||
| } | ||
| } | ||
| }" | ||
|
|
||
| # Run query to GraphQL API endpoint | ||
|
|
||
| curl -s -X POST -H "Content-Type: application/json" -H "X-Auth-Email: $Email" -H X-Auth-Key: $global_key --data "$(echo $PAYLOAD)" https://api.cloudflare.com/client/v4/graphql/ | ||
| ``` |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.