노트북용 Blob Storage API 사용

공개 미리보기

notebooks용 Blob Storage API 은(는) 현재 공개 미리 보기 상태입니다. 이 기능은 출시 전 정책에 따라 제공됩니다.

뉴렐릭 Notebooks API를 사용하면 전체 블록 콘텐츠(NRQL 쿼리, 텍스트)를 포함하여 프로그래밍 방식으로 노트북을 생성, 읽기, 업데이트 및 삭제할 수 있습니다. 노트북은 버전이 지정된 blob으로 저장되므로, 저장할 때마다 나중에 검색할 수 있는 새로운 불변의 리비전이 생성됩니다.

이 API를 사용하여 다음을 수행합니다:

인시던트 템플릿, 런북 또는 CI/CD 파이프라인에서 노트북 생성 자동화
버전 제어 또는 외부 작성 도구에서 notebook 콘텐츠 동기화
조사 중 프로그래밍 방식으로 노트북을 채우는 통합 구축

중요

Notebooks 여러 API 사용

Notebooks API 표면은 두 시스템으로 나뉩니다:

Blob Storage API 은(는) 노트북 콘텐츠(블록, 버전 기록)를 처리합니다.
NerdGraph 은(는) 엔티티 수준 작업(목록, 이름 바꾸기, 태그, 조직 메타데이터)을 처리합니다.
이러한 분리는 의도된 것입니다. Blob Storage API 은(는) 파일 콘텐츠 전송 및 버전 관리에 최적화되어 있으며, NerdGraph 은(는) 구조화된 엔티티 쿼리 및 변형에 최적화되어 있습니다.

전제 조건

사용자 API 키가 있는 New Relic 계정
귀하의 New Relic 조직 ID
notebooks를 관리하기 위한 적절한 권한

입증

모든 Notebooks API requests New Relic 사용자 API 키를 사용한 인증이 필요합니다.

API 키를 생성하세요:

one.newrelic.com으로 이동하세요.
오른쪽 상단 코너에 있는 이름을 클릭합니다.
선택하다 API Keys
User 키를 생성하세요(브라우저 키 또는 라이선스 키가 아닙니다)

요청 헤더에 포함하세요:

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

Notebook 콘텐츠 작업

초기 blob 콘텐츠가 있는 새 노트북 엔티티를 생성합니다.

끝점

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

요청 매개변수 [#create-params]

매개변수	위치	데이터 형식	설명
`orgId`	길	문자열	필수의. 귀하의 New Relic 조직 ID입니다.
`Api-Key`	머리글	문자열	필수의. 귀하의 사용자 API 키입니다.
`Content-Type`	머리글	문자열	필수의. `application/json` 이어야 합니다.
`NewRelic-Entity`	머리글	JSON 문자열	필수의. notebook 엔티티 메타데이터가 포함된 JSON 객체입니다(아래 참조).
요청 본문	몸	JSON	필수의. JSON 형식의 노트북 콘텐츠(버전+블록).

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

들	데이터 형식	설명
`name`	문자열	필수의. notebook 이름입니다. 조직 범위 내에서 고유해야 합니다.

Notebook 본문 형식 [#create-body-format]

들	데이터 형식	설명
`version`	문자열	notebook 페이로드의 스키마 버전입니다. `"1"` 을 사용하세요.
`blocks`	정렬	notebook 블록( NRQL , 텍스트 등)의 정렬된 목록입니다. 빈 어레이는 빈 notebook을 생성합니다.

들

데이터 형식

설명

version

문자열

notebook 페이로드의 스키마 버전입니다.

"1"

을 사용하세요.

blocks

정렬

notebook 블록(

NRQL

, 텍스트 등)의 정렬된 목록입니다. 빈 어레이는 빈 notebook을 생성합니다.

선언적 UI 콘텐츠 예 [#create-declarative-ui]

다음 예는 선언적 UI 형식을 사용하여 노트북 위젯 콘텐츠를 구성하는 방법을 보여줍니다.

마크다운 위젯

차트와 함께 정적 텍스트, 레이블 또는 임계값 범례를 렌더링하려면 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 을(를) 저장합니다. notebook을 읽고, 업데이트하고, 삭제하는 데 필요합니다.

노트북의 최신 콘텐츠를 가져옵니다.

끝점

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]
                }
              ]
            }
          }
        }
      ]
    }
  ]
}

콘텐츠를 덮어써서 기존 notebook의 새 버전을 만듭니다. 이전 버전은 최대 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 을(를) 사용합니다.

모든 notebooks 나열

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

팁

엔티티 생성은 완전히 트랜잭션 방식이므로 API를 통해 notebook을 즉시 사용할 수 있습니다. 하지만 구형 actor.entitySearch 쿼리를 통해 notebook을 나열하는 경우, 생성과 목록 결과에 notebook이 나타나는 사이에 짧은 전파 지연이 있을 수 있습니다.

notebook 이름 바꾸기

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 형식이거나 이 조직에 노트북 이름이 이미 존재합니다.	요청 형식, 헤더 값 및 notebook 이름이 조직 내에서 고유한지 확인합니다.
`401 Unauthorized`	API 키가 없거나 유효하지 않습니다.	사용자 API 키가 유효하고 `Api-Key` 헤더에 포함되어 있는지 확인하세요
`404 Not Found`	Notebook 또는 버전을 찾을 수 없음	엔티티 GUID가 올바른지 확인하십시오.
`415 Unsupported Media Type`	잘못된 `Content-Type` 헤더	사용 `Content-Type: application/json`

추가 리소스

노트북 개요 ― New Relic UI에서 노트북을 사용하는 방법
NerdGraph 소개 ― GraphQL API 참조
에이전트 설정을 위한 Blob Storage API ― 다음에서 사용하는 자매 API Fleet Control
뉴렐릭 API 키 ― 키 유형 및 관리

사용자의 편의를 위해 제공되는 기계 번역입니다.

공개 미리보기

중요

전제 조건 .css-21sua1{background:none;border:none;width:0;padding:0;}

입증

팁

기본 엔드포인트

Notebook 콘텐츠 작업

노트북 콘텐츠 읽기

노트북 콘텐츠 업데이트

notebook 삭제

이전 버전 검색

엔티티 작업(NerdGraph)

모든 notebooks 나열

팁

notebook 이름 바꾸기

노트북 태그 업데이트

중요

귀하의 조직 ID를 검색하세요

모범 사례

일반적인 오류 응답

추가 리소스

전제 조건