뉴렐릭 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 키를 생성하세요(브라우저 키 또는 라이선스 키가 아닙니다)
요청 헤더에 포함하세요:
$Api-Key: NRAK-YOUR-USER-API-KEY팁
Blob Storage API 도 로그인 컨텍스트를 지원하므로 New Relic 사용자로 인증된 UI에서 API를 호출할 때 Api-Key 헤더가 필요하지 않습니다.
기본 엔드포인트
https://blob-api.service.newrelic.com/v1/eEU 지역 계정의 경우 다음을 사용하세요.
https://blob-api.service.eu.newrelic.com/v1/eNotebook 콘텐츠 작업
엔티티 작업(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, 그리고 오류가 발생하면 다른 상태 코드를 반환합니다.
일반적인 오류 응답
상태 코드 | 설명 | 해결책 |
|---|---|---|
| 잘못된 요청 파라미터, 본문 또는 | 요청 형식, 헤더 값 및 notebook 이름이 조직 내에서 고유한지 확인합니다. |
| API 키가 없거나 유효하지 않습니다. | 사용자 API 키가 유효하고 |
| Notebook 또는 버전을 찾을 수 없음 | 엔티티 GUID가 올바른지 확인하십시오. |
| 잘못된 | 사용 |
추가 리소스
- 노트북 개요 ― New Relic UI에서 노트북을 사용하는 방법
- NerdGraph 소개 ― GraphQL API 참조
- 에이전트 설정을 위한 Blob Storage API ― 다음에서 사용하는 자매 API Fleet Control
- 뉴렐릭 API 키 ― 키 유형 및 관리