ノートブックでのBlob Storage APIの使用

公開プレビュー

ノートブックのBlob Storage APIは現在パブリックプレビュー段階です。この機能は、弊社のプレリリースポリシーに従って提供されています。

New Relic Notebooks APIを使用すると、ブロックの全コンテンツ（NRQLクエリ、テキスト）を含め、ノートブックをプログラムで作成、読み取り、更新、削除できます。ノートブックはバージョン管理されたblobとして保存されます。つまり、保存するたびに、後で取得できる新しい不変のリビジョンが作成されます。

このAPIを使用して次のことを行います：

インシデントテンプレート、ランブック、またはCI/CDパイプラインからのノートブック作成を自動化する
バージョン管理または外部オーサリングツールからノートブックのコンテンツを同期する
調査中にノートブックにプログラムでデータを入力するインテグレーションを構築する

重要

Notebooks 複数のAPIを使用

NotebooksAPIサーフェスは2つのシステムに分割されています：

Blob Storage APIはノートブックのコンテンツ（ブロック、バージョン履歴）を処理します
NerdGraphは、エンティティレベルの操作（リスト、名前変更、タグ、組織メタデータ）を処理します
この分離は意図的なものです。Blob Storage APIはファイルコンテンツの転送とバージョン管理に最適化されています；NerdGraphは構造化されたエンティティクエリとミューテーションに最適化されています。

前提条件

ユーザーAPIキーを持つNew Relicアカウント
お客様のNew Relic組織ID
ノートブックを管理するための適切な権限

認証

すべてのNotebooks API requests New RelicユーザーAPIキーを使用した認証が必要です。

APIキーを生成する：

one.newrelic.comにアクセスします
右上隅の自分の名前をクリックします。
選択する API Keys
Userキーを作成します (Browserまたはライセンスキーではありません)

リクエストヘッダーに含める：

bash

$Api-Key: NRAK-YOUR-USER-API-KEY

ヒント

Blob Storage APIはログインコンテキストもサポートしているため、New Relicユーザーとして認証されたUIからAPIを呼び出す場合、Api-Keyヘッダーは必要ありません。

ベースエンドポイント

https://blob-api.service.newrelic.com/v1/e

EU地域のアカウントの場合は、以下を使用してください。

https://blob-api.service.eu.newrelic.com/v1/e

ノートブックのコンテンツ操作

初期のblobコンテンツを持つ新しいノートブックエンティティを作成します。

終点

POST /v1/e/organizations/{orgId}/Notebooks

リクエストパラメータ [#create-params]

パラメータ	場所	データ型	説明
`orgId`	パス	弦	必須。お客様の New Relic 組織ID。
`Api-Key`	ヘッダー	弦	必須。お使いのユーザーAPIキー。
`Content-Type`	ヘッダー	弦	必須。 `application/json` である必要があります。
`NewRelic-Entity`	ヘッダー	JSON文字列	必須。ノートブックのエンティティメタデータを含むJSONオブジェクト（以下を参照）。
リクエストボディ	体	JSON	必須。JSON形式のノートブックのコンテンツ(バージョン+ブロック)。

`NewRelic-Entity` [#create-entity-header]

フィールド	データ型	説明
`name`	弦	必須。ノートブック名。組織のスコープ内で一意である必要があります。

ノートブックの本文の形式 [#create-body-format]

フィールド	データ型	説明
`version`	弦	ノートブックペイロードのスキーマバージョン。 `"1"` を使用します。
`blocks`	配列	ノートブックブロックの順序付きリスト( NRQL 、テキストなど)。空の配列は空のノートブックを作成します。

フィールド

データ型

説明

version

弦

ノートブックペイロードのスキーマバージョン。

"1"

を使用します。

blocks

配列

ノートブックブロックの順序付きリスト(

NRQL

、テキストなど)。空の配列は空のノートブックを作成します。

宣言型UIコンテンツの例 [#create-declarative-ui]

以下の例では、宣言型UIフォーマットを使用してノートブックウィジェットのコンテンツを構成する方法を示します。

Markdownウィジェット

viz.markdownを使用して、チャートの横に静的テキスト、ラベル、または閾値の凡例をレンダリングします：

{
  "type": "widget",
  "content": {
    "type": "visualization",
    "id": "viz.markdown",
    "props": {
      "text": "# My dashboard\n\n### Cost thresholds (monthly)\n- $0 – $200 → Good\n- $200 – $500 → Warning\n- $500+ → Critical"
    }
  }
}

NRQLクエリを使用したビルボードウィジェット

viz.billboardを使用して、オプションの色分けされた閾値を持つ単一のメトリクス値を表示します：

{
  "type": "widget",
  "props": {
    "title": "Total usage this month"
  },
  "content": {
    "type": "visualization",
    "id": "viz.billboard",
    "props": {
      "nrqlQueries": [
        {
          "query": "FROM Transaction SELECT count(*) SINCE 1 month ago",
          "accountIds": [1234567]
        }
      ],
      "thresholdsWithSeriesOverrides": {
        "thresholds": [
          { "to": 200, "severity": "success" },
          { "from": 200, "to": 500, "severity": "warning" },
          { "from": 500, "severity": "critical" }
        ]
      },
      "facet": { "showOtherSeries": false },
      "platformOptions": { "ignoreTimeRange": false },
      "chartStyles": { "lineInterpolation": "linear" }
    }
  }
}

サンプルリクエスト [#create-sample-request]

bash

$curl -X POST \
>  https://blob-api.service.newrelic.com/v1/e/organizations/YOUR_ORG_ID/Notebooks \
>  -H 'Api-Key: NRAK-YOUR-API-KEY' \
>  -H 'Content-Type: application/json' \
>  -H 'NewRelic-Entity: {"name": "My awesome notebook"}' \
>  -d '{
$    "version": "1",
$    "blocks": []
$  }'

サンプル回答 [#create-sample-response]

{
  "entityGuid": "<YOUR_ENTITY_GUID>",
  "blobId": "<YOUR_BLOB_ID>",
  "blobVersionEntity": {
    "entityGuid": "<YOUR_ENTITY_GUID>",
    "version": 1
  }
}

重要

レスポンスからentityGuidを保存します。ノートブックの読み取り、更新、削除に必要になります。

ノートブックの最新コンテンツを取得します。

終点

GET /v1/e/organizations/{orgId}/Notebooks/{entityGuid}

リクエストパラメータ [#read-params]

パラメータ

場所

データ型

それは必須ですか？

説明

orgId

パス

弦

はい

New Relic

の組織ID。

entityGuid

パス

弦

はい

ノートブックのエンティティGUID。

Api-Key

ヘッダー

弦

はい

ユーザーAPIキー。

サンプルリクエスト [#read-sample-request]

bash

$curl -X GET \
>  https://blob-api.service.newrelic.com/v1/e/organizations/YOUR_ORG_ID/Notebooks/YOUR_ENTITY_GUID \
>  -H 'Api-Key: NRAK-YOUR-API-KEY'

サンプル回答 [#read-sample-response]

{
  "type": "declarative",
  "version": 1,
  "content": [
    {
      "type": "container",
      "props": {
        "layout": "stack"
      },
      "content": [
        {
          "type": "widget",
          "props": {},
          "content": {
            "type": "visualization",
            "id": "viz.billboard",
            "props": {
              "nrqlQueries": [
                {
                  "query": "FROM PageView SELECT count(*) SINCE 3 days ago",
                  "accountIds": [1]
                }
              ]
            }
          }
        }
      ]
    }
  ]
}

コンテンツを上書きすることで、既存のノートブックの新しいバージョンを作成します。以前のバージョンは最大1日間保持されます（以前のバージョンの取得を参照）。

終点

POST /v1/e/organizations/{orgId}/Notebooks/{entityGuid}

リクエストパラメータ [#update-params]

パラメータ	場所	データ型	それは必須ですか？	説明
`orgId`	パス	弦	はい	New Relic の組織ID。
`entityGuid`	パス	弦	はい	ノートブックのエンティティGUID。
`Api-Key`	ヘッダー	弦	はい	ユーザーAPIキー。
`Content-Type`	ヘッダー	弦	はい	`application/json` である必要があります。
リクエストボディ	体	JSON	はい	更新されたノートブックのコンテンツ。

サンプルリクエスト [#update-sample-request]

bash

$curl -X POST \
>  https://blob-api.service.newrelic.com/v1/e/organizations/YOUR_ORG_ID/Notebooks/YOUR_ENTITY_GUID \
>  -H 'Api-Key: NRAK-YOUR-API-KEY' \
>  -H 'Content-Type: application/json' \
>  -d '{
$    "type": "declarative",
$    "version": 1,
$    "content": [
$      {
$        "type": "container",
$        "props": {
$          "layout": "stack"
$        },
$        "content": [
$          {
$            "type": "widget",
$            "props": {
$              "title": ""
$            },
$            "content": {
$              "type": "visualization",
$              "id": "viz.billboard",
$              "props": {
$                "nrqlQueries": [
$                  {
$                    "query": "FROM PageView SELECT count(*) SINCE 2 days ago",
$                    "accountIds": [1]
$                  }
$                ]
$              }
$            }
$          }
$        ]
$      }
$    ]
$  }'

サンプル回答 [#update-sample-response]

{
  "entityGuid": "<YOUR_ENTITY_GUID>",
  "blobId": "<YOUR_BLOB_ID>",
  "blobVersionEntity": {
    "entityGuid": "<YOUR_ENTITY_GUID>",
    "version": 2
  }
}

ノートブックとそのコンテンツを削除します。

終点

DELETE /v1/e/organizations/{orgId}/Notebooks/{entityGuid}

リクエストパラメータ [#delete-params]

パラメータ

場所

データ型

それは必須ですか？

説明

orgId

パス

弦

はい

New Relic

の組織ID。

entityGuid

パス

弦

はい

削除するノートブックのエンティティGUID。

Api-Key

ヘッダー

弦

はい

ユーザーAPIキー。

サンプルリクエスト [#delete-sample-request]

bash

$curl -X DELETE \
>  https://blob-api.service.newrelic.com/v1/e/organizations/YOUR_ORG_ID/Notebooks/YOUR_ENTITY_GUID \
>  -H 'Api-Key: NRAK-YOUR-API-KEY'

サンプル回答 [#delete-sample-response]

削除が成功すると、HTTP 204 No Content を返します。

Notebook バージョンは1日保持されます。以前のリビジョンを復元するには、まずNRQLを使用して最近のバージョンを一覧表示し、次に特定のblobを取得します。

ステップ1 — 最新の5つのバージョンを一覧表示する

クエリビルダーでこのNRQLクエリを実行して、過去5回の変更のblob IDとタイムスタンプを収集します：

FROM Entity
SELECT uniques(tuple(updatedAt, content.id))
WHERE id = '<entity guid>'
SINCE 1 day ago
LIMIT 5

ステップ2 — 特定のバージョンを取得する [#retrieve-specific-version]

NRQLの結果からcontent.idを使用して、そのバージョンのコンテンツを取得します：

bash

$curl -X GET \
>  https://blob-api.service.newrelic.com/v1/blobs/<content.id> \
>  -H 'Api-Key: NRAK-YOUR-API-KEY'

エンティティ操作（NerdGraph）

一覧表示、名前変更、タグなどのエンティティレベルの操作では、Blob Storage APIではなくNerdGraphを使用します。

すべてのノートブックを一覧表示する

query listAllNotebooks {
  actor {
    entityManagement {
      entitySearch(query: "type='NOTEBOOK'") {
        entities {
          id
          name
        }
      }
    }
  }
}

ヒント

エンティティの作成は完全にトランザクションであるため、ノートブックはAPIを介してすぐに利用できます。ただし、レガシーactor.entitySearchクエリを使用してノートブックを一覧表示する場合、作成からノートブックがリスト結果に表示されるまでに短い伝播遅延が発生する可能性があります。

ノートブックの名前を変更する

mutation changeNotebookName {
  entityManagementUpdateNotebook(
    id: "<entity guid>"
    notebookEntity: { name: "<new name>" }
  ) {
    entity {
      name
    }
  }
}

ノートブックのタグを更新する

重要

タグの更新は置換操作です。変更されないものも含めて、タグの完全なセットを含める必要があります — ミューテーションから省略されたタグは削除されます。

mutation updateNotebookTags {
  entityManagementUpdateNotebook(
    id: "<entity guid>"
    notebookEntity: {
      tags: [
        { key: "<key>", values: "<value>" }
        { key: "<key>", values: "<value>" }
      ]
    }
  ) {
    entity {
      name
      tags {
        key
        values
      }
    }
  }
}

組織IDを取得する

すべてのBlob Storage API呼び出しには、組織IDが必要になります：

query getOrgId {
  actor {
    organization {
      id
    }
  }
}

ベストプラクティス

エンティティGUIDを保存する: 作成操作から返されたentityGuidを保存します。ノートブックの読み取り、更新、削除に必要になります。
アップロード前にJSONを検証する: 送信する前に、ノートブックのペイロードが有効なJSONであり、versionスキーマに準拠していることを確認してください。
分かりやすい名前を使用する：ノートブックの名前は組織内で一意である必要があるため、目的を明確に示す名前を選択してください（たとえば、notebook-1ではなくprod-checkout-investigation）。
更新時にすべてのタグを含める: タグの更新により、タグセット全体が置き換えられます。変更する前に、常に既存のタグを読み取ります。
迅速に復元する: バージョン履歴は1日のみ保持されます。長期的な履歴が必要な場合は、更新のたびにノートブックのコンテンツを独自のストレージにアーカイブしてください。
APIキーを保護する:ユーザーAPIキーをクライアント側のコードやパブリックリポジトリで公開しないでください。
HTTPステータスコードを確認してください。APIは、操作が成功した場合は2xx、見つからない場合は404、エラーの場合はその他のステータスコードを返します。

よくあるエラーへの対応

ステータスコード	説明	解決
`400 Bad Request`	無効なリクエストパラメーター、本文または `NewRelic-Entity` ヘッダーの不正なJSON、またはこの組織にノートブック名がすでに存在しています	リクエストの形式、ヘッダー値、およびノートブック名が組織内で一意であることを確認します
`401 Unauthorized`	APIキーが欠落しているか無効です	ユーザーAPIキーが有効であり、 `Api-Key` ヘッダーに含まれていることを確認してください。
`404 Not Found`	ノートブックまたはバージョンが見つかりません	エンティティのGUIDが正しいことを確認してください。
`415 Unsupported Media Type`	不正な `Content-Type` ヘッダー	使用する `Content-Type: application/json`

追加リソース

ノートブックの概要 — New RelicUIでのノートブックの使用方法
NerdGraphの概要 — GraphQL APIリファレンス
エージェント設定用のBlob Storage API — 次によって使用される姉妹API Fleet Control
New Relic APIキー — キーの種類と管理

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

ノートブックでのBlob Storage APIの使用

公開プレビュー

重要

前提条件 .css-21sua1{background:none;border:none;width:0;padding:0;}

認証

ヒント

ベースエンドポイント

ノートブックのコンテンツ操作

ノートブックのコンテンツを読み取る

ノートブックのコンテンツを更新

ノートブックを削除する

以前のバージョンを取得する

エンティティ操作（NerdGraph）

すべてのノートブックを一覧表示する

ヒント

ノートブックの名前を変更する

ノートブックのタグを更新する

重要

組織IDを取得する

ベストプラクティス

よくあるエラーへの対応

追加リソース

前提条件