Pcx 1086 analytics graphql update getting started (#503)

* PCX-1086 Analytics GraphQL Getting started update

* PCX-1086 Fix article on exploring schema

* PCX-1086 Minor copy edits

* PCX-1086 Edit Explore schema topic

* PCX-1086 Edits for building a query in graphql

* PCX-1086 Update header name

* PCX-1086 Address comments and edits

* PCX-1086 Incorporated comments

Co-authored-by: Aine Riordan <[email protected]>
Co-authored-by: Aaron Ruby <[email protected]>
Co-authored-by: Jeremy Pugh <[email protected]>

Author: 3 people

products/analytics/package.json

@@ -4,11 +4,11 @@
     "cloudflare-docs-engine": "git+https://github.com/cloudflare/cloudflare-docs-engine.git"
   },
   "scripts": {
-    "bootstrap": "node_modules/cloudflare-docs-engine/bin/commands.sh bootstrap",
-    "build": "node_modules/cloudflare-docs-engine/bin/commands.sh build",
-    "develop": "node_modules/cloudflare-docs-engine/bin/commands.sh develop",
-    "ghactionsbootstrap": "node_modules/cloudflare-docs-engine/bin/commands.sh ghactionsbootstrap",
-    "savechanges": "node_modules/cloudflare-docs-engine/bin/commands.sh savechanges",
-    "serve": "node_modules/cloudflare-docs-engine/bin/commands.sh serve"
+    "bootstrap": "sh ./node_modules/cloudflare-docs-engine/bin/commands.sh bootstrap",
+    "build": "sh ./node_modules/cloudflare-docs-engine/bin/commands.sh build",
+    "develop": "sh ./node_modules/cloudflare-docs-engine/bin/commands.sh develop",
+    "ghactionsbootstrap": "sh ./node_modules/cloudflare-docs-engine/bin/commands.sh ghactionsbootstrap",
+    "savechanges": "sh ./node_modules/cloudflare-docs-engine/bin/commands.sh savechanges",
+    "serve": "sh ./node_modules/cloudflare-docs-engine/bin/commands.sh serve"
   }
 }

products/analytics/src/content/graphql-api/getting-started/authentication/api-key-auth.md

@@ -1,6 +1,6 @@
 ---
 title: Authenticate with a Cloudflare API key
-order: 20
+order: 30
 ---
 
 # Authenticate with a Cloudflare API key
@@ -9,35 +9,3 @@ API keys are unique to each Cloudflare user and used only for authentication. An
 
 * Learn how to [find your API Key](https://support.cloudflare.com/hc/articles/200167836) in the Cloudflare Dashboard
 * Learn how to [retrieve your API Key](https://api.cloudflare.com/#getting-started-requests) using the Cloudflare API
-
-## Edit HTTP headers for GraphiQL authentication
-
-1. Launch _GraphiQL_
-
-2. Click **Edit HTTP Headers**
-   ![ ](../../../static/images/GraphiQL-edit-http-headers.png)
-   The _Edit HTTP Headers_ window appears.
-   ![ ](../../../static/images/GraphiQL-edit-http-headers-window.png)
-
-3. Click **Add Header**
-   ![ ](../../../static/images/GraphiQL-add-header.png)
-
-4. Enter **X-AUTH-EMAIL** in the _Header name_ field and your email address registered with Cloudflare in the _Header value_ field, and click **Save**
-
-5. Click **Add Header**
-
-6. Enter **X-AUTH-KEY** in the _Header Name_ field, then paste your Global API Key in the _Header value_ field, and click **Save**
-   ![ ](../../../static/images/GraphiQL-edit-http-headers-complete.png)
-
-7. Click anywhere outside the _Edit HTTP Headers_ window in _GraphiQL_ to return to the _Untitled Query 1_ tab
-
-8. Enter `https://api.cloudflare.com/client/v4/graphql` in the _GraphQL Endpoint_ field
-   ![ ](../../../static/images/GraphiQL-response-pane.png)
-
-<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_.

products/analytics/src/content/graphql-api/getting-started/authentication/api-token-auth.md

@@ -1,6 +1,6 @@
 ---
 title: Configure an Analytics API token
-order: 30
+order: 20
 ---
 
 # Configure an Analytics API token
@@ -48,7 +48,7 @@ To configure a custom token, follow these steps:
 
   ![Create Custom Token page](../../../static/images/create-custom-api-token.png)
 
-1. Use the **Token name** text input to enter a descriptive name for your token.
+1. Enter a descriptive name for your token in the **Token name** text input field.
 
 1. To configure access to the GraphQL Analytics API, use the **Permissions** drop-down lists. To set permissions for the GraphQL Analytics API, select _Analytics_ from the second drop-down list.
 
@@ -70,7 +70,7 @@ To configure a custom token, follow these steps:
 
 1. Click **Continue to summary**.
 
-The next section of this walk through shows you how to [review and test your API token](#review-and-test-your-api-token).
+The next section of this walkthrough shows you how to [review and test your API token](#review-and-test-your-api-token).
 
 ## Review and create your API token
 
@@ -90,11 +90,11 @@ When you create a new token, a confirmation page displays that includes your tok
 
 To copy the token to your device's clipboard, click the **Copy** button.  
 
-<Aside type='note' header='Note'>
+<Aside type='warning' header='Warning'>
 
-The confirmation page is the only time that you can see the token, so make sure you store it safely, since anyone who has token can use it to access your data.
+The token displays only on the confirmation page, so copy the token and store it safely, since anyone who has the token can use it to access your data.
 
-If you lose the secret, you can [regenerate the token from the API Tokens page](https://support.cloudflare.com/hc/en-us/articles/200167836-Managing-API-Tokens-and-Keys#12345681), so that you do not have to configure all the permissions again.
+If you lose the token, you can [regenerate it from the API Tokens page](https://support.cloudflare.com/hc/en-us/articles/200167836-Managing-API-Tokens-and-Keys#12345681), so that you do not have to configure all the permissions again.
 
 </Aside>
 

products/analytics/src/content/graphql-api/getting-started/authentication/graphql-client-headers.md

@@ -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**.
+   ![Click Edit HTTP Headers](../../../static/images/GraphiQL-edit-http-headers.png)
+   The _Edit HTTP Headers_ window appears.
+   ![Edit HTTP Headers Window](../../../static/images/GraphiQL-edit-http-headers-window.png)
+1. Click **Add Header**.
+   ![Click Add Header](../../../static/images/GraphiQL-add-header.png)
+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**.
+   ![HTTP Headers](../../../static/images/GraphiQL-edit-http-headers-token.png)
+   * **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**.
+   ![HTTP Headers](../../../static/images/GraphiQL-edit-http-headers-complete.png)
+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
+   ![Edit GraphQL Endpoint](../../../static/images/GraphiQL-response-pane.png)
+
+<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_.

products/analytics/src/content/graphql-api/getting-started/authentication/index.md

@@ -5,9 +5,9 @@ order: 10
 
 # Authentication
 
-Cloudflare separates service configuration by zone. When there are multiple accounts each with many zones, it is important to restrict GraphQL Analytics API access to only those account and zone resources that are relevant for the task at hand.
+Cloudflare separates service configuration by zone. When there are multiple accounts, each with many zones, it is important to restrict GraphQL Analytics API access to only those account and zone resources that are relevant for the task at hand.
 
-To secure access your GraphQL Analytics data, use a Cloudflare API key or token to authenticate an API request.
+To secure access to your GraphQL Analytics data, use a Cloudflare API key or token to authenticate an API request.
 
 This table outlines the differences between Cloudflare API keys and tokens:
 
@@ -21,20 +21,20 @@ This table outlines the differences between Cloudflare API keys and tokens:
       </tr>
   </thead>
   <tbody>
+      <tr>
+        <td><a href='https://developers.cloudflare.com/api/tokens/create'>API Tokens</a></td>
+        <td>Cloudflare recommends API Tokens as the preferred way to interact with Cloudflare APIs. You can configure the scope of tokens to limit access to account and zone resources, and you can define the Cloudflare APIs to which the token authorizes access.</td>
+      </tr>
       <tr>
         <td><a href='https://developers.cloudflare.com/api/keys'>API Keys</a></td>
         <td><p>Unique to each Cloudflare user and used only for authentication. API keys do not authorize access to accounts or zones.</p>
         <p>Use the Global API Key for authentication. Only use the Origin CA Key when you create origin certificates through the API.</p></td>
       </tr>
-      <tr>
-        <td><a href='https://developers.cloudflare.com/api/tokens/create'>API Tokens</a></td>
-        <td>Cloudflare recommends API Tokens as the preferred way to interact with Cloudflare APIs. You can configure the scope of tokens to limit access to account and zone resources, and you can define the Cloudflare APIs to which the token authorizes access.</td>
-      </tr>
   </tbody>
 </table>
 
 </TableWrap>
 
-To find and retrieve API keys, as well as edit HTTP headers for authentication in GraphiQL, see [_Authenticate with a Cloudflare API key_](/graphql-api/getting-started/authentication/api-key-auth/).
-
 To create and configure GraphQL Analytics API tokens, see [_Configure an Analytics API token_](/graphql-api/getting-started/authentication/api-token-auth/).
+
+To find and retrieve API keys, as well as edit HTTP headers for authentication in GraphiQL, see [_Authenticate with a Cloudflare API key_](/graphql-api/getting-started/authentication/api-key-auth/).

products/analytics/src/content/graphql-api/getting-started/compose-graphql-query.md

@@ -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:
+
+![GraphiQL base query](../../static/images/graphiql-base-query.png)
+
+<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. Insert your cursor in the query, in this case on the line below `zones`, and start entering a value to engage the feature. For example, when you type `firewall`, a popup menu displays the data sets that return firewall information:
+
+![firewall nodes](../../static/images/graphiql-word-completion.png)
+
+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.
+
+## 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:
+
+![GraphiQL parameters](../../static/images/graphiql-set-up-base-query.png)
+
+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:
+
+![GraphiQL parameters](../../static/images/graphiql-parameters.png)
+
+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`:
+
+![GraphiQL filter fields](../../static/images/graphiql-filter-fields.png)
+
+This example query shows the required `filter` and `limit` arguments for `firewallEventsAdaptive`:
+
+![GraphiQL filter values](../../static/images/graphiql-filter-values.png)
+
+## 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):
+
+![GraphiQL parameters](../../static/images/graphiql-set-up-base-query.png)
+
+**The Documentation Explorer** opens and displays a list of fields:
+
+![List of fields](../../static/images/graphiql-return-fields.png)
+
+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:
+
+![Example query with return fields](../../static/images/graphiql-query-return-field-values.png)
+
+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.
+
+![GraphiQL response](../../static/images/create-query-fw-data-set-play.png)
+
+## 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:
+
+![GraphiQL query variables](../../static/images/graphiql-query-variables.png)

products/analytics/src/content/graphql-api/getting-started/execute-graphql-query.md

@@ -0,0 +1,71 @@
+---
+title: Use curl to query the Analytics API
+order: 60
+---
+
+# Use curl to query the Analytics API
+
+You can submit a [query built with the GraphiQL client](/graphql-api/getting-started/compose-graphql-query) as the payload in the `data` field of a POST request to the Analytics API.
+
+The advantage of executing a 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/
+```