NerdGraph cloud integrations API tutorial

This document provides examples of how to use New Relic NerdGraph to query and modify your cloud integration configuration data, including Amazon AWS, Microsoft Azure, and Google Cloud Platform (GCP). Using the NerdGraph GraphiQL explorer, you can also query NRQL data.

These examples for querying cloud integration configuration data use GraphQL queries and mutations:

  • Queries: requests that are intended to only fetch data
  • Mutations: requests that create or update data on the server

Requirements

Before querying cloud integration data with NerdGraph, ensure you have:

Access the NerdGraph GraphiQL explorer

To access the NerdGraph GraphiQL explorer:

  1. Go to https://api.newrelic.com/graphiql.
  2. Add any of the following examples.

Query examples

Queries are requests that are intended to only fetch data (no side effects). Queries in NerdGraph are not static, meaning that you can ask for more or less data depending on your needs. For each query, you can specify exactly what data you want to retrieve, as long as it is supported by the schema.

Available provider accounts

This query returns a list of all provider accounts available in your infrastructure data. Depending on the provider, additional properties can be requested. For example, for GCP, you can also ask for the serviceAccountId property, which is needed when linking a new GCP project to New Relic.

Anonymous:

{
  actor {
    account(id: <NR_ACCOUNT_ID>) {
      cloud {
        providers {
          id
          name
          slug
          ... on CloudGcpProvider {
            serviceAccountId
          }
        }
      }
    }  
  }
}

Named:

query cloudProviders {
  actor {
    account(id: <NR_ACCOUNT_ID>) {
      cloud {
        providers {
          id
          name
          slug
        }
      }
    }
  }
}
Specific provider account information

This query returns information about a specific provider account for your Amazon AWS integration. The properties id, name, slug are requested, along with a list of integrations available to be monitored.

{
  actor {
    account(id: <NR_ACCOUNT_ID>) {
      cloud {
        provider(slug: "aws") {
          id
          slug
          name
          services {
            id
            slug
            name
          }
        }
      }
    }
  }
}
Specific integration data from a specific cloud provider

This query returns information about a specific cloud service integration of a provider. In this example, the integration is the Amazon AWS ALB monitoring integration and the provider is AWS. The properties id, name, slug, and isAllowed are requested with the available configuration parameters.

{
  actor {
    account(id: <NR_ACCOUNT_ID>) {
      cloud {
        provider(slug: "aws") {
          service(slug: "alb") {
            id
            name
            slug
            isEnabled
          }
        }
      }
    }
  }
}
List of enabled cloud accounts

This query returns the list of cloud accounts enabled with your New Relic account. (Your cloud account associates your New Relic account and a specific provider account with your integration.) You can enable multiple cloud provider accounts in the same New Relic account, even with the same cloud provider.

{
  actor {
    account(id: <NR_ACCOUNT_ID>) {
      cloud {
        linkedAccounts {
          id
          name    
          createdAt
          provider {
            id
            name      
          }
        }
      }
    }
  }
}
Specific linked account data

This query returns information about a linked account, including the properties name, providerId, and a list of the cloud integrations enabled for monitoring.

{
  actor {
    account(id: <NR_ACCOUNT_ID>) {
      cloud {
        linkedAccount(id: <LINKED_ACCOUNT_ID>) {
          name
          provider {
            id
            name
          }
          integrations {
            id
            name
            createdAt
            updatedAt
          }
        }
      }
    }
  }
}
Enabled cloud integrations for all linked accounts

This query returns all monitored integrations for all the provider cloud accounts.

{
  actor {
    account(id: <NR_ACCOUNT_ID>) {
      cloud {
        linkedAccounts {
          name
          provider {
            id
            name
          }
          integrations {
            id
            name
            service {
              id
              name        
            }
            createdAt
            updatedAt
          }
        }
      }
    }
  }
}
Specific cloud integration data for a specific linked account

This query returns information about a specific integration from a specific linked account.

{
  actor {
    account(id: <NR_ACCOUNT_ID>) {
      cloud {
        linkedAccount(id: <LINKED_ACCOUNT_ID>) {
          name
          provider {
            id
            name
          }
          integration(id: <INTEGRATION_ID>) {
            id
            name
            service {
              id
              name        
            }
            createdAt
            updatedAt     
          }
        }
      }
    }
  }
}

Mutation examples

Mutations are requests that are intended to have side effects, such as creating or updating data on the server. Mutations require the keyword mutation and the name of the mutation. NerdGraph mutations are restricted to a subset of all possible mutations.

This mutation allows linking cloud provider accounts to a New Relic account, creating one or more linked accounts. It can link one specific cloud provider account (for example aws) to the New Relic account or multiple cloud provider accounts to one New Relic account.

Required:

  • The parameter <PROVIDER_ACCOUNT_NAME> is required and cannot be empty. It must be unique in your New Relic account.
  • Other parameters are specific to the provider (AWS, GCP, and Azure) and are also required. In the following sections, you can see which parameters are required for each provider account. After linking an account the createdAt and updatedAt values are equal.
mutation {
  cloudLinkAccount(
      accounts: {
        accountId: <NR_ACCOUNT_ID>,
        aws: [{
          name: <PROVIDER_ACCOUNT_NAME>,
          <other_params>
        }]
        azure: [{
          name: <PROVIDER_ACCOUNT_NAME>,
          <other_params>
        }]
        gcp: [{
          name: <PROVIDER_ACCOUNT_NAME>,
          <other_params>
        }]
      }
    ) {
      linkedAccounts {
        id
        name
        authLabel
        createdAt
        updatedAt
      }
    }
  }
}

This mutation links an Amazon AWS provider account to your New Relic account.

mutation {
  cloudLinkAccount(
      accountId: <NR_ACCOUNT_ID>,
      accounts: {
        aws: [{
          name: <PROVIDER_ACCOUNT_NAME>,
          arn: <AWS_ROLE_ARN>
        }]
      }
    ) {
      linkedAccounts {
        id
        name
        authLabel
        createdAt
        updatedAt
      }
    }
  }
}

This mutation links a Microsoft Azure cloud subscription to the New Relic account.

mutation {
  cloudLinkAccount(
    accountId: <NR_ACCOUNT_ID>,
    accounts: {
      azure: [{        
        name: <PROVIDER_ACCOUNT_NAME>, 
        applicationId: <azure_application_id>, 
        clientSecret: <azure_application_key>, 
        tenantId: <azure_tenant_id>, 
        subscriptionId: <azure_subscription_id>
       }]          
    }
  ) {
    linkedAccounts {
      id
      name
      authLabel
      createdAt
      updatedAt
    }
  }
}

This mutation links a GCP project to the New Relic account.

mutation {
  cloudLinkAccount(
    accountId: <NR_ACCOUNT_ID>,
    accounts: {
      gcp: [{        
        name: <PROVIDER_ACCOUNT_NAME>,
        projectId: <GCP_PROJECT_ID>
       }]
    }
  ) {
    linkedAccounts {
      id
      name
      authLabel
      createdAt
      updatedAt
    }
  }
}
Rename one or more cloud accounts

This mutation allows you to rename one or more linked provider accounts. The name parameter is required, cannot be empty, and must be unique within your New Relic account.

mutation {
  cloudRenameAccount(
    accountId: <NR_ACCOUNT_ID>,
    accounts: [
      {        
        id: <linked_account_id_1>,
        name: <new_provider_account_name>
      },
      {
        id: <linked_account_id_2>,
        name: <new_provider_account_name>
      }
    ]
  ) {
    linkedAccounts {
      id          
      name
    }
  }
}
Enable an integration in a cloud account

This mutation allows you to enable the monitoring of one or more specific cloud integrations in an existing cloud account. With this mutation, New Relic records data for the enabled integration from the provider account. For each provider account you have access to different input parameters, matching each available service.

mutation {
  cloudConfigureIntegration (
    accountId: <NR_ACCOUNT_ID>,
    integrations: {
      <provider_slug> : {
        <integration_slug>: [{            
            linkedAccountId: <LINKED_ACCOUNT_ID>,
            <other_parameters> 
        }]
      }
    }
  ) {
    integrations {
      id
      name
      integration {
        id
        slug
      }
      ... on SqsIntegration {
        awsRegions
      }
    }
  }
}
Enable an integration in multiple cloud accounts

If you have many provider accounts linked, you can enable the same integration in the many cloud accounts at the same time.

For the output of the operation, you can use GraphQL fragments for integration specific configuration parameters.

mutation {
  cloudConfigureIntegration (
    accountId: <NR_ACCOUNT_ID>,
    integrations: {
      <provider_slug> : {
        <integration_slug> : [
          { linkedAccountId: <linked_account_id_1>  }, 
          { linkedAccountId: <linked_account_id_2>  }
        ]
      } 
    }
  ) {
    integrations {
      id
      name
      integration {
        id 
        name
      }
      ... on SqsIntegration {
            awsRegions
      }
    }
  }
}
Enable multiple integrations in multiple cloud accounts

If you have multiple cloud accounts linked, you can also enable multiple integrations in multiple linked cloud accounts at the same time.

For the output of the operation, you can use GraphQL fragments to ask for integration specific configuration parameters.

mutation {
  cloudConfigureIntegration (
    accountId: <NR_ACCOUNT_ID>,
    integrations: {
      <provider_slug_1>: {
        <integration_slug_1>: [
          { linkedAccountId: <linked_account_id_1> }
        ]
        <integration_slug_2>: [
          { linkedAccountId: <linked_account_id_2> }
        ]
      },
      <provider_slug_2>: {
        <integration_slug_3>: [
          { linkedAccountId: <linked_account_id_3>},
          { linkedAccountId: <linked_account_id_4>}
        ]
      } 
    }
  ) {
    integrations {
      id
      name
      service {
        id 
        name
      }
      ... on SqsIntegration {
            awsRegions
      }
    }
  }
}
Modify an integration's configuration (regions, polling intervals, etc.)

This mutation also allows you to modify one or more cloud integrations and change one or more configuration parameters. Each service will have specific parameters that you can modify.

For parameters of a type list (for example, awsRegion) supply the full list. For the output of the operation, you can use GraphQL fragments to ask for integration specific configuration parameters.

mutation {
  cloudConfigureIntegration (
    accountId: <NR_ACCOUNT_ID>,
    integrations: {
      <provider_slug>: {
        <integration_slug>: [{          
          linkedAccountId: <LINKED_ACCOUNT_ID>,
          metricsPollingInterval: <new_polling_interval>,
          <parameter_1>: <value_1>,
          <parameter_N>: <value_N>,
        }]
      }
    }
  ) {
    integrations {
      id
      name
      service {
        id
        slug
      }
      ... on SqsIntegration {            
        metricsPollingInterval,
        <parameter_1>,
        <parameter_N>
      }
    }
    errors {
      type
      message
    }
  }
}
Disable (remove) an integration

This mutation allows you to disable an integration and stop data collection for the specific cloud integration.

mutation {
  cloudDisableIntegration (
    accountId: <NR_ACCOUNT_ID>,
    integrations: {
      : {
        : [
          { linkedAccountId: <LINKED_ACCOUNT_ID> }
        ]
      }
    }
  ) {
    disabledIntegrations {
      id
      name
      authLabel
      provider {
        id
      }
    }
    errors {
      type
      message
    }
  }
}</integration_slug></provider_slug>

Unlink account

This mutation allows you to unlink cloud provider accounts from New Relic account.

This action can not be undone. However, you can link the account again, but account history will still be lost.

mutation {
  cloudUnlinkAccount (
    accountId: <NR_ACCOUNT_ID>,
    accounts: {
      { linkedAccountId: <LINKED_ACCOUNT_ID> }
    }
  ) {
    unlinkedAccounts {
      id
      name
    }
    errors {
      type
      message
    }
  }
}</integration_slug></provider_slug>

Enable an Amazon AWS integration

This example uses an Amazon AWS SQS integration and assumes you have connected an AWS account to New Relic.

To enable an Amazon AWS integration:

Send query to fetch account data

Send a query to fetch data about the account, specifically available providers and already created provider accounts:

{
  actor {
    account(id: <NR_ACCOUNT_ID>) {
      cloud {
        providers {
          id 
          name
          slug
        }     
        linkedAccounts {
          name
          integrations {
            id
            name
          }
        }
      }
    }
  }
}

Link an AWS provider account, if there is not one already linked or if you want to link another AWS account:

  1. Use your New Relic account identifier in the <NR_ACCOUNT_ID> parameter.
  2. Provide a name for the provider account in the <PROVIDER_ACCOUNT_NAME>.
  3. Include the ARN of the AWS role used to fetch data from your AWS account.
mutation {
  cloudLinkAccount(
    accountId: <NR_ACCOUNT_ID>,
    accounts: {
      aws: [{        
        name: <PROVIDER_ACCOUNT_NAME>,
        arn: <AWS_ROLE_ARN> }]
    }
  ) {
    linkedAccounts {
      id
      name
      authLabel
      createdAt
      updatedAt
    }
    errors {
      type
      message
    }
  }
}
Enable Amazon AWS SQS integration

Use your New Relic account ID in the <NR_ACCOUNT_ID> parameter and the ID of the provider account in the <LINKED_ACCOUNT_ID> parameter value.

mutation {
  cloudConfigureIntegration (
    accountId: <NR_ACCOUNT_ID>,
    integrations: {
      aws: {
        sqs: [
          { linkedAccountId: <LINKED_ACCOUNT_ID> }
        ]
      }
    } 
  ) {
    integrations {
      id
      name
      service {
        id 
        name
      }
    }
    errors {
      type
      message
    }
  }
}
Enable integration in multiple provider accounts

If you have multiple accounts with the same provider account, you can enable the same integration in multiple provider accounts at the same time. Use your New Relic account ID in the <NR_ACCOUNT_ID> parameter and the ID of the provider accounts in the <LINKED_ACCOUNT_ID_n> parameter value.

mutation {
  cloudConfigureIntegration (
    accountId: <NR_ACCOUNT_ID>,
    integrations: {
      aws: {
        sqs: [
          { linkedAccountId: <LINKED_ACCOUNT_ID_1> }, 
          { linkedAccountId: <LINKED_ACCOUNT_ID_2>, configuration_param_1: value_1, configuration_param_2: value_2 }
        ]
      } 
    }
  }) {
    integrations {
      id
      name
      service {
        id 
        name
      }
    }
    errors {
      type
      message
    }
  }
}

Change polling interval for Amazon AWS integration

This example uses an Amazon AWS SQS integration and assumes you have connected an AWS account to New Relic. To change the polling interval of an AWS integration:

Update the polling interval

To update the polling interval for an Amazon AWS SQS integration, use your New Relic account ID in the <NR_ACCOUNT_ID> parameter and the id of the linked provider account in the <LINKED_ACCOUNT_ID> parameter value:

mutation {
  cloudConfigureIntegration( 
    accountId: <NR_ACCOUNT_ID>,
    integrations: {
      aws : {
        sqs: [
          { linkedAccountId: <LINKED_ACCOUNT_ID>, metricsPollingInterval: 300 }
        ]
      }
    }
  ) {
    integrations {
      id
      name            
      service {
        id
        slug
      }
      ... on SqsIntegration {
        metricsPollingInterval
      }
    }
    errors {
      type
      message
    }
  }
}

Disable Amazon AWS integration

This example uses an Amazon AWS SQS integration and assumes you have connected an AWS account to New Relic. To disable an AWS integration:

Disable the SQS integration

Use your New Relic account identifier in the <NR_ACCOUNT_ID> parameter and the ID of the linked cloud account the <LINKED_ACCOUNT_ID> parameter value.

mutation {
  cloudDisableIntegration (
    accountId: <NR_ACCOUNT_ID>,
    integrations: {
      aws: {
        sqs: [
          { linkedAccountId: <LINKED_ACCOUNT_ID> }
        ]
      }
    }
  ) {
  disabledIntegrations {
    id
      accountId
      name 
    }
    errors {
      type
      message
    }
  }
}

For more help

If you need more help, check out these support and learning resources: