NerdGraph チュートリアル: ダッシュボードの作成と管理

NerdGraph APIを使用してを作成および管理できます。

概要

カスタムダッシュボード機能の概要については、ダッシュボードドキュメントを参照してください。

NerdGraph を使用してダッシュボードを構成する場合、監視対象のアプリ、ホスト、サービスなど、エンティティと見なされる他のものと同様に、ダッシュボードがエンティティと見なされ、独自のエンティティ ID があることを理解しておくと役立ちます。

ダッシュボードにウィジェットとグラフを追加して構成する方法については、「グラフとその他のウィジェットを構成する」を参照してください。

ダッシュボードのCRUD操作

このドキュメントでは、NerdGraph API を使用してダッシュボードを作成、読み取り、更新、削除する方法について説明します (CRUD)。これらの操作によりダッシュボード全体が変更されます。

ダッシュボードの作成

ダッシュボードには少なくとも 1 ページが必要です。1 つ以上のページを含むダッシュボードを作成でき、各ページには 1 つ以上のウィジェットを含めることができます。

api.newrelic.com/graphiql の NerdGraph GraphiQL エクスプローラーにアクセスします。
NerdGraph のダッシュボードAPIを使用して、新しいダッシュボードとその設定を作成します。
name 、 permissionsなどの必須フィールドと少なくとも1ページが含まれていることを確認してください。

mutation {
  dashboardCreate(
    accountId: 1
    dashboard: {
      name: "My New Dashboard"
      description: "This is my new dashboard created via NerdGraph"
      permissions: PUBLIC_READ_WRITE
      pages: [
        {
          name: "Page 1"
          description: "This is the first page"
          widgets: [
            {
              visualization: { id: "viz.billboard" }
              layout: { column: 1, row: 1, height: 3, width: 4 }
              title: "Total Transaction Count"
              rawConfiguration: {
                nrqlQueries: [
                  { accountIds: [1], query: "SELECT count(*) FROM Transaction" }
                ]
              }
            }
          ]
        }
      ]
      variables: [
        {
          name: "nrql_variable"
          title: "countries"
          type: NRQL
          nrqlQuery: {
            accountIds: [1]
            query: "SELECT uniqueCount(countryCode) FROM PageView"
          }
          replacementStrategy: STRING
        }
      ]
    }
  ) {
    entityResult {
      guid
      name
      description
      createdAt
      updatedAt
      owner {
        email
        userId
      }
      permissions
      pages {
        guid
        name
        description
        createdAt
        updatedAt
        widgets {
          id
          visualization {
            id
          }
          layout {
            column
            row
            height
            width
          }
          title
          linkedEntities {
            guid
          }
          rawConfiguration
        }
      }
      variables {
        name
        items {
          title
          value
        }
        defaultValues {
          value {
            string
          }
        }
        nrqlQuery {
          accountIds
          query
        }
        options {
          excluded
          ignoreTimeRange
          showApplyAction
        }
        title
        type
        isMultiSelection
        replacementStrategy
      }
    }
    errors {
      type
      description
    }
  }
}

クエリを簡単に更新できるように、変数を使用することをお勧めします。以下は上記と同じミューテーションですが、変数を使用しています。

mutation CreateDashboard($accountId: Int!, $dashboard: DashboardInput!) {
  dashboardCreate(accountId: $accountId, dashboard: $dashboard) {
    entityResult {
      guid
      name
      description
      createdAt
      updatedAt
      owner {
        email
        userId
      }
      permissions
      pages {
        guid
        name
        description
        createdAt
        updatedAt
        widgets {
          id
          visualization {
            id
          }
          layout {
            column
            row
            height
            width
          }
          title
          linkedEntities {
            guid
          }
          rawConfiguration
        }
      }
      variables {
        name
        items {
          title
          value
        }
        defaultValues {
          value {
            string
          }
        }
        nrqlQuery {
          accountIds
          query
        }
        options {
          excluded
          ignoreTimeRange
          showApplyAction
        }
        title
        type
        isMultiSelection
        replacementStrategy
      }
    }
    errors {
      type
      description
    }
  }
}

この突然変異で使用する変数は次のとおりです。

{
  "accountId": 1,
  "dashboard": {
    "name": "My New Dashboard",
    "description": "This is my new dashboard created via NerdGraph",
    "permissions": "PUBLIC_READ_WRITE",
    "pages": [
      {
        "name": "Page 1",
        "description": "This is the first page",
        "widgets": [
          {
            "visualization": { "id": "viz.billboard" },
            "layout": { "column": 1, "row": 1, "height": 3, "width": 4 },
            "title": "Total Transaction Count",
            "rawConfiguration": {
              "nrqlQueries": [
                {
                  "accountIds": [1],
                  "query": "SELECT count(*) FROM Transaction"
                }
              ]
            }
          }
        ]
      }
    ],
    "variables": [
      {
        "name": "nrql_variable",
        "title": "countries",
        "type": "NRQL",
        "nrqlQuery": {
          "accountIds": [1],
          "query": "SELECT uniqueCount(countryCode) FROM PageView"
        },
        "replacementStrategy": "STRING"
      }
    ]
  }
}

ダッシュボードを読む

api.newrelic.com/graphiql の NerdGraph GraphiQL エクスプローラーにアクセスします。
エンティティ GUID でダッシュボードを検索するには、 actor > entity()を使用します。
NerdGraph のダッシュボードAPIを使用して、既存のダッシュボードとその設定を読み込みます。

この例では、 DASHBOARD_GUID 、読み取りたいダッシュボードの実際の GUID に置き換えます。

query GetDashboardEntityQuery {
  actor {
    entity(guid: "DASHBOARD_GUID") {
      ... on DashboardEntity {
        guid
        name
        description
        createdAt
        updatedAt
        owner {
          email
          userId
        }
        permissions
        pages {
          guid
          name
          description
          createdAt
          updatedAt
          widgets {
            id
            visualization {
              id
            }
            layout {
              column
              row
              height
              width
            }
            title
            linkedEntities {
              guid
            }
            rawConfiguration
          }
        }
        variables {
          name
          items {
            title
            value
          }
          defaultValues {
            value {
              string
            }
          }
          nrqlQuery {
            accountIds
            query
          }
          options {
            excluded
            ignoreTimeRange
            showApplyAction
          }
          title
          type
          isMultiSelection
          replacementStrategy
        }
      }
    }
  }
}

取得する情報に応じて、クエリ内のフィールドを変更できます。

ダッシュボードを更新する

ダッシュボードを更新するには、1 つの要素のみを更新する場合でも、すべてのページとウィジェットを含むダッシュボードの完全な設定を提供する必要があります。更新操作はダッシュボードのコンテンツを完全に置き換えます。

重要

ダッシュボードを更新するときに、ページ guid またはウィジェット ID が指定されていない場合、既存のページまたはウィジェットはダッシュボードから削除され、ミューテーションで指定された新しいページまたはウィジェットに置き換えられます。

api.newrelic.com/graphiql の NerdGraph GraphiQL エクスプローラーにアクセスします。
「ダッシュボードを読む」セクションに示すように、NerdGraph のダッシュボードAPIを使用して、エンティティ GUID によってダッシュボードを読み取り、既存のダッシュボード設定を取得します。
ダッシュボード設定で更新したいフィールドを変更します。
NerdGraph のダッシュボードAPIを使用して、変更した設定で既存のダッシュボードを更新します。

重要

ウィジェットでFacet Linking使用している場合、ダッシュボードを読み取るときはフィールドはlinkedEntities { guid }ですが、ダッシュボードを更新するときはlinkedEntityGuids: [ "GUID" ]使用する必要があります。

mutation UpdateDashboard(
  $guid: EntityGuid!
  $dashboard: DashboardUpdateInput!
) {
  dashboardUpdate(guid: $guid, dashboard: $dashboard) {
    entityResult {
      guid
      name
      description
      createdAt
      updatedAt
      owner {
        email
        userId
      }
      permissions
      pages {
        guid
        name
        description
        createdAt
        updatedAt
        widgets {
          id
          visualization {
            id
          }
          layout {
            column
            row
            height
            width
          }
          title
          linkedEntities {
            guid
          }
          rawConfiguration
        }
      }
      variables {
        name
        items {
          title
          value
        }
        defaultValues {
          value {
            string
          }
        }
        nrqlQuery {
          accountIds
          query
        }
        options {
          excluded
          ignoreTimeRange
          showApplyAction
        }
        title
        type
        isMultiSelection
        replacementStrategy
      }
    }
    errors {
      type
      description
    }
  }
}

この突然変異で使用する変数は次のとおりです。

{
  "guid": "DASHBOARD_GUID",
  "dashboard": {
    "name": "My Updated Dashboard",
    "description": "This is my updated dashboard created via NerdGraph",
    "permissions": "PUBLIC_READ_WRITE",
    "pages": [
      {
        "guid": "PAGE_GUID",
        "name": "Updated Page 1",
        "description": "This is the updated first page",
        "widgets": [
          {
            "id": "WIDGET_ID",
            "visualization": { "id": "viz.billboard" },
            "layout": { "column": 1, "row": 1, "height": 3, "width": 4 },
            "title": "Updated Total Transaction Count",
            "linkedEntityGuids": [],
            "rawConfiguration": {
              "nrqlQueries": [
                {
                  "accountIds": [1],
                  "query": "SELECT count(*) FROM Transaction"
                }
              ]
            }
          }
        ]
      }
    ],
    "variables": [
      {
        "name": "nrql_variable",
        "title": "countries",
        "type": "NRQL",
        "nrqlQuery": {
          "accountIds": [1],
          "query": "SELECT uniqueCount(countryCode) FROM PageView"
        },
        "replacementStrategy": "STRING"
      }
    ]
  }
}

ダッシュボードの削除

ダッシュボードを削除するには、削除するダッシュボードのエンティティ GUID を指定する必要があります。この操作は、ダッシュボードを回復できる論理削除を実行します。

api.newrelic.com/graphiql の NerdGraph GraphiQL エクスプローラーにアクセスします。
NerdGraph のダッシュボード API を使用して、エンティティ GUID によってダッシュボードを削除します。
statusとerrorsをチェックして削除を確認します。

ダッシュボードの削除を取り消す

ダッシュボードエンティティ GUID を指定すると、以前に削除されたダッシュボードを復元できます。カスタムタグは回復できません。

api.newrelic.com/graphiql の NerdGraph GraphiQL エクスプローラーにアクセスします。
NerdGraph のダッシュボード API を使用して、エンティティ GUID によってダッシュボードの削除を解除します。
errorsをチェックして削除の取り消しを確認します。

ダッシュボードページの操作

この操作はダッシュボードの特定のページを変更します。

ダッシュボードページを更新する

ダッシュボードページエンティティ GUID を指定すると、既存のダッシュボードの 1 ページを更新できます。メタデータからウィジェット設定まで、完全で更新されたダッシュボードページ要素を指定する必要があります。

api.newrelic.com/graphiql の NerdGraph GraphiQL エクスプローラーにアクセスします。
「ダッシュボードを読む」セクションに示すように、NerdGraph のダッシュボードAPIを使用して、エンティティ GUID によってダッシュボードを読み取り、既存のダッシュボード設定を取得します。
ダッシュボードから更新するページを識別して抽出します。
ページ内で更新するフィールドを変更します。
ページを変更するにはdashboardUpdatePage()を使用します。
errorsがある場合はチェックしてください。

重要

ページを更新するときにウィジェット ID が指定されていない場合、既存のウィジェットはダッシュボードから削除され、ミューテーションで指定された新しいウィジェットに置き換えられます。

ヒント

idフィールドなしでwidgets配列に新しいウィジェットを含めることで、ページに新しいウィジェットを追加できます。
widgets配列からウィジェットを省略することで、ページからウィジェットを削除できます。

mutation UpdateDashboardPage(
  $pageGuid: EntityGuid!
  $page: DashboardUpdatePageInput!
) {
  dashboardUpdatePage(guid: $pageGuid, page: $page) {
    errors {
      type
      description
    }
  }
}

この突然変異で使用する変数は次のとおりです。

{
  "guid": "PAGE_GUID",
  "page": {
    "name": "Updated Page 1",
    "description": "This is the updated first page",
    "widgets": [
      {
        "id": "WIDGET_ID",
        "visualization": { "id": "viz.billboard" },
        "layout": { "column": 1, "row": 1, "height": 3, "width": 4 },
        "title": "Updated Total Transaction Count",
        "linkedEntityGuids": [],
        "rawConfiguration": {
          "nrqlQueries": [
            {
              "accountIds": [1],
              "query": "SELECT count(*) FROM Transaction"
            }
          ]
        }
      }
    ]
  }
}

mutation UpdateDashboardPage(
  $pageGuid: EntityGuid!
  $page: DashboardUpdatePageInput!
) {
  dashboardUpdatePage(guid: $pageGuid, page: $page) {
    errors {
      type
      description
    }
  }
}

この突然変異で使用する変数は次のとおりです。

{
  "guid": "PAGE_GUID",
  "page": {
    "name": "Updated Page 1",
    "description": "This is the updated first page",
    "widgets": [
      {
        "id": "WIDGET_ID",
        "visualization": { "id": "viz.billboard" },
        "layout": { "column": 1, "row": 1, "height": 3, "width": 4 },
        "title": "Updated Total Transaction Count",
        "linkedEntityGuids": [],
        "rawConfiguration": {
          "nrqlQueries": [
            {
              "accountIds": [1],
              "query": "SELECT count(*) FROM Transaction"
            }
          ]
        }
      },
      {
        "visualization": { "id": "viz.line" },
        "layout": { "column": 5, "row": 1, "height": 3, "width": 4 },
        "title": "New Line Chart",
        "rawConfiguration": {
          "nrqlQueries": [
            {
              "accountIds": [1],
              "query": "SELECT count(*) FROM PageView TIMESERIES"
            }
          ]
        }
      }
    ]
  }
}

ページ内のウィジェットを更新します

ダッシュボードページエンティティ GUID を指定して、ダッシュボードページの既存のウィジェットのセットを更新できます。更新するウィジェットのセットとその完全な設定を指定する必要があります。

重要

この操作では、ページにウィジェットを追加したり、ページからウィジェットを削除したりすることはできません。ウィジェットを追加または削除するには、ダッシュボードページの更新操作を使用します。

api.newrelic.com/graphiql の NerdGraph GraphiQL エクスプローラーにアクセスします。
「ダッシュボードを読む」セクションに示すように、NerdGraph のダッシュボードAPIを使用して、エンティティ GUID によってダッシュボードを読み取り、既存のダッシュボード設定を取得します。
ダッシュボードから更新するページ内のウィジェットを識別して抽出します。
ウィジェットで更新するフィールドを変更します。
ウィジェットを変更するにはdashboardUpdateWidgetsInPage()使用します。
errorsがある場合はチェックしてください。

mutation UpdateWidgetsInPage(
  $pageGuid: EntityGuid!
  $widgets: [DashboardUpdateWidgetInput!]!
) {
  dashboardUpdateWidgetsInPage(guid: $pageGuid, widgets: $widgets) {
    errors {
      type
      description
    }
  }
}

この突然変異で使用する変数は次のとおりです。

{
  "guid": "PAGE_GUID",
  "widgets": [
    {
      "id": "WIDGET_ID",
      "visualization": { "id": "viz.billboard" },
      "layout": { "column": 1, "row": 1, "height": 3, "width": 4 },
      "title": "Updated Total Transaction Count",
      "linkedEntityGuids": [],
      "rawConfiguration": {
        "nrqlQueries": [
          {
            "accountIds": [1],
            "query": "SELECT count(*) FROM Transaction"
          }
        ]
      }
    }
  ]
}

その他の事業

操作方法	GraphQLの操作タイプ	メモ
`dashboardCreateSnapshotUrl()`	突然変異	ダッシュボードページのスナップショット操作を作成します。特定のダッシュボードページエンティティ GUID のパブリック URL を作成できます。生成されたパブリック URL 内の静的スナップショットの形式でダッシュボードページにアクセスできるようになります。作成された URL は作成後 3 か月で廃止されます。詳細については、「API 経由でダッシュボードのスナップショットを管理する」を参照してください。
`actor > dashboard > liveUrls()`	クエリ	すべてのライブ URL を一覧表示する操作。アクセスできるライブ URL の完全なリストを取得できます。ライブ URL は、最新のデータやライブデータを含むダッシュボードページとウィジェットを公開できるメカニズムです。詳細については、「API 経由でライブチャートの URL を管理する」を参照してください。
`dashboardWidgetRevokeLiveUrl()`	突然変異	ウィジェットのライブ URL 操作を取り消します。以前に作成したウィジェットのライブ URL を取り消すことができます。その結果、ライブ URL は一般には公開されなくなります。詳細については、「API 経由でライブチャートの URL を管理する」を参照してください。
`dashboardCreateLiveUrl()`	突然変異	公開アクセス可能なライブダッシュボード URL を作成します。詳細については、「公開共有ダッシュボード URL の作成、更新、取り消し」を参照してください。
`dashboardUpdateLiveUrl()`	突然変異	公開アクセス可能なライブダッシュボード URL の有効期限を更新します。詳細については、「公開共有ダッシュボード URL の作成、更新、取り消し」を参照してください。
`dashboardRevokeLiveUrl()`	突然変異	公開アクセス可能なライブダッシュボード URL を取り消します。詳細については、「公開共有ダッシュボード URL の作成、更新、取り消し」を参照してください。
`dashboardUpdateLiveUrlCreationPolicies()`	突然変異	認証ドメインマネージャーだけが、このミューテーションを使用してアカウントのLive URL Creationポリシーを有効または無効にすることができます。ユーザーは、このポリシーが有効になっているアカウントのダッシュボードのライブ URL を作成できます。

クロスアカウントダッシュボード

NerdGraph を使用すると、複数の New Relic アカウントからデータのクエリを作成できます。アカウント ID をaccountIds配列に追加することで、複数のアカウントのデータを使用してダッシュボードを作成することもできます。

クロスアカウントダッシュボードの作成例を次に示します。

mutation {
  dashboardCreate(
    accountId: 1
    dashboard: {
      name: "Cross account queries - NerdGraph API - Cross Account Test1"
      description: null
      permissions: PUBLIC_READ_WRITE
      pages: [
        {
          name: "Page 1"
          description: null
          widgets: [
            {
              visualization: { id: "viz.billboard" }
              layout: { column: 1, row: 1, height: 3, width: 4 }
              title: "Cross Account Total Transaction Count"
              rawConfiguration: {
                legend: { enabled: true }
                nrqlQueries: [
                  {
                    accountIds: [1, 1606862, 2212585]
                    query: "SELECT count(*) FROM Transaction"
                  }
                ]
                yAxisLeft: { zero: true }
              }
              linkedEntityGuids: null
            }
            {
              visualization: { id: "viz.pie" }
              layout: { column: 5, row: 1, height: 3, width: 4 }
              title: "Cross Account Pie"
              rawConfiguration: {
                legend: { enabled: true }
                nrqlQueries: [
                  {
                    accountIds: [1, 1606862, 2212585]
                    query: "SELECT count(*) FROM Transaction FACET accountId()"
                  }
                ]
                yAxisLeft: { zero: true }
              }
              linkedEntityGuids: null
            }
            {
              visualization: { id: "viz.line" }
              layout: { column: 9, row: 1, height: 3, width: 4 }
              title: "Cross Account Line"
              rawConfiguration: {
                legend: { enabled: true }
                nrqlQueries: [
                  {
                    accountIds: [1, 1606862, 2212585]
                    query: "SELECT count(*) FROM Transaction FACET accountId() TIMESERIES"
                  }
                ]
                yAxisLeft: { zero: true }
              }
              linkedEntityGuids: null
            }
          ]
        }
      ]
    }
  ) {
    errors {
      description
      type
    }
  }
}

制限

ダッシュボードのプロパティの一部に設定できる値を制限しました。これにより、ダッシュボードの使い勝手を高めつつ、良好な状態を保つことができます。

ダッシュボードの制限

制限	価値
ダッシュボードの最大ページ数	25
ダッシュボード名の最大長	255
ダッシュボードの説明文の最大長	1024

ダッシュボードのページ制限

制限	価値
ダッシュボードページ内のウィジェットの最大数	150
ダッシュボードのページ名の最大長	255
ダッシュボードページの説明文の最大長	1024

制限	価値
ウィジェットタイトルの最大長	255
1つのウィジェットにリンクされたエンティティの最大数	1
1つのウィジェット内の最大クエリ数	20
ウィジェットの最大レイアウト欄	12
ウィジェットの最小レイアウト欄	1
ウィジェットの最小レイアウト列	1
ウィジェットの最大レイアウト幅	12
ウィジェットの最小レイアウト幅	1
ウィジェットの最大レイアウト高さ	32
ウィジェットの最小レイアウト高さ	1

一級市民としてのエラー

すべてのダッシュボード・ミューテーションは、実行時にエラーを求める方法を提供しています。つまり、ダッシュボードの変異を実行し、その応答をチェックすることで、予想される潜在的な問題を検出することができます。すべてのエラーにはタイプと説明があり、問題の原因が何かを特定するのに役立ちます。

これらは、事前に把握している想定内のエラーであることを念頭に置いてください。また、標準の GraphQL errors field で返ってくる予期せぬエラーについても確認しておく必要があります。

この機械翻訳は、参考として提供されています。

NerdGraph チュートリアル: ダッシュボードの作成と管理

概要

ダッシュボードのCRUD操作

ダッシュボードの作成

1 ページ、1 つのウィジェット、1 つの変数を持つダッシュボード

GraphQL変数を使用してダッシュボードを作成する

ダッシュボードを読む

ダッシュボードを更新する

重要

重要

GraphQL変数を使用してダッシュボードを更新する

ダッシュボードの削除

ダッシュボードの削除

ダッシュボードの削除を取り消す

ダッシュボードの削除を取り消す

ダッシュボードページの操作

ダッシュボードページを更新する

重要

ヒント

ページを更新する

新しいウィジェットを追加してページを更新する

ページ内のウィジェットを更新します

重要

その他の事業

クロスアカウントダッシュボード

クロスアカウントクエリを含むダッシュボード

制限

ダッシュボードの制限

ダッシュボードのページ制限

ウィジェットの制限

一級市民としてのエラー

すべての変異反応の一部としてのエラー

この機械翻訳は、参考として提供されています。

NerdGraph チュートリアル: ダッシュボードの作成と管理

概要 .css-21sua1{background:none;border:none;width:0;padding:0;}

ダッシュボードのCRUD操作

ダッシュボードの作成

GraphQL変数を使用してダッシュボードを作成する

ダッシュボードを読む

ダッシュボードを更新する

重要

重要

GraphQL変数を使用してダッシュボードを更新する

ダッシュボードの削除

ダッシュボードの削除

ダッシュボードの削除を取り消す

ダッシュボードの削除を取り消す

ダッシュボードページの操作

ダッシュボードページを更新する

重要

ヒント

ページを更新する

新しいウィジェットを追加してページを更新する

ページ内のウィジェットを更新します

重要

その他の事業

クロスアカウント ダッシュボード

クロスアカウント クエリを含むダッシュボード

制限

ダッシュボードの制限

ダッシュボードのページ制限

ウィジェットの制限

一級市民としてのエラー

すべての変異反応の一部としてのエラー

概要

クロスアカウントダッシュボード

クロスアカウントクエリを含むダッシュボード