> For the complete documentation index, see [llms.txt](https://docs.panther.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.panther.com/ko/panther/api/graphql.md). # GraphQL API ## 개요 Panther는 공개 GraphQL-over-HTTP API를 제공합니다. 즉, 일반적인 HTTP 요청을 사용해 GraphQL 쿼리를 작성하고 API를 호출할 수 있습니다. GraphQL에 대한 자세한 내용은 다음을 참조하세요. [GraphQL 문서](https://graphql.org/learn/). 현재 GraphQL API를 통해 다음 엔터티와 상호 작용할 수 있습니다: * [알러트 및 오류](/ko/panther/api/graphql/alerts-and-errors.md) * [클라우드 계정](/ko/panther/api/graphql/cloud-account.md) * [데이터 레이크 쿼리](/ko/panther/api/graphql/data-lake-queries.md) * [로그 소스](/ko/panther/api/graphql/log-source.md) * [메트릭](/ko/panther/api/graphql/metrics.md) * [스키마](/ko/panther/api/graphql/schemas.md) * [API 토큰](/ko/panther/api/graphql/token-rotation.md) * [사용자 및 역할](/ko/panther/api/graphql/user-management.md) 추가 작업은 다음에서 사용할 수 있습니다. [REST API](/ko/panther/api/rest.md). ### GraphQL 쿼리 이해하기
클릭하여 GraphQL 쿼리 예시 펼치기 아래 예시 쿼리의 이름은 `ListAlerts`. 이 쿼리는 각 알러트의 `id`, `제목`, `심각도` 그리고 `상태` 를 포함한 알러트 목록을 제공된 시간 범위를 기준으로 반환합니다. * 해당 `input` 유형의 변수 `AlertsInput` 는 다음과 같은 특정 조건을 기준으로 알러트를 필터링하는 데 사용됩니다: `createdAtAfter` 그리고 `createdAtBefore`. 이러한 조건은 쿼리에 대한 시간 범위를 제공합니다. * 해당 `알림` 필드는 다음이 포함된 객체를 반환합니다: `edges` 그리고 `pageInfo`. 각 edge에는 `node` 실제 알러트 데이터를 포함하는 필드가 있습니다. 예: `id`, `제목`, `심각도` 그리고 `상태`. * 해당 `pageInfo` 필드에는 다음과 같은 페이지네이션 정보가 포함됩니다. 예: `hasNextPage` 그리고 `endCursor`, 이를 통해 사용자는 알러트의 모든 페이지를 순회할 수 있습니다. 한 번 `hasNextPage` 가 되면 `false`. ```graphql query ListAlerts($input: AlertsInput!) { alerts(input: $input) { edges { node { id 제목 심각도 상태 } } pageInfo { hasNextPage endCursor } } } ```
### Panther GraphQL 스키마 알아보기 GraphQL 스키마를 확인하는 방법은 세 가지입니다: * 옵션 1(가장 빠름): 공개적으로 제공되는 GraphQL 스키마 파일 다운로드 * 옵션 2(가장 사용하기 쉬움): 사용 [Panther의 API Playground](/ko/panther/api/api-playground.md) * 옵션 3(도구 및 서비스에 가장 적합): 다음을 수행 [인트로스펙션 쿼리](https://graphql.org/learn/introspection/) GraphQL 엔드포인트에 대해 {% tabs %} {% tab title="GraphQL 파일 다운로드" %} **옵션 1: 공개적으로 제공되는 GraphQL 스키마 파일 다운로드** 최신 버전의 GraphQL 스키마 파일을 다운로드할 수 있습니다 [여기에서](https://panther-community-us-east-1.s3.amazonaws.com/latest/graphql/schema.public.graphql). {% endtab %} {% tab title="Panther API Playground" %} **옵션 2: GraphQL Playground 사용** Panther의 API Playground는 API에서 지원되는 기능을 탐색하고 알아보기 위한 사용자 친화적인 방법입니다. 다음을 참조하세요: [API Playground 문서](https://docs.runpanther.io/api-beta/api-playground) 이를 탐색 수단으로 사용하는 방법에 대한 정보입니다. {% endtab %} {% tab title="인트로스펙션 쿼리" %} **옵션 3: 인트로스펙션 쿼리 수행하기** 인트로스펙션 쿼리는 대부분의 타사 라이브러리가 구문 분석할 수 있는 형식으로 GraphQL API의 모든 엔터티를 반환합니다. 이 탐색 옵션은 다른 라이브러리나 서비스가 Panther API의 지원 작업과 유형을 인식하게 하려는 경우 유용합니다. 이러한 라이브러리는 일반적으로 자체 인트로스펙션 쿼리 버전을 실행하므로, API URL만 지정하면 됩니다. 보안상의 이유로 인트로스펙션 쿼리는 권한이 필요한 작업입니다. 즉, 다음을 추가해야 합니다: `X-API-Key` 헤더를 HTTP 호출에 추가하고, 값은 [API 토큰](https://docs.runpanther.io/api-beta/generating-an-api-token) API 키여야 인트로스펙션이 작동합니다. ``` $ curl -H "X-API-Key: " -d ``` 인트로스펙션 쿼리의 실제 형태는 사용자 지정할 수 있습니다. 제한된 엔터티 집합이나 스키마에 대한 가능한 모든 정보를 요청할 수 있습니다. 예를 들어, 다음과 같은 쿼리는 스키마 정보의 모든 항목을 반환합니다: ```graphql query IntrospectionQuery { __schema { queryType { name } mutationType { name } types { ...FullType } directives { 이름 설명 locations args { ...InputValue } } } } fragment FullType on __Type { kind 이름 설명 fields(includeDeprecated: true) { 이름 설명 args { ...InputValue } type { ...TypeRef } isDeprecated deprecationReason } inputFields { ...InputValue } interfaces { ...TypeRef } enumValues(includeDeprecated: true) { 이름 설명 isDeprecated deprecationReason } possibleTypes { ...TypeRef } } fragment InputValue on __InputValue { 이름 설명 type { ...TypeRef } defaultValue } fragment TypeRef on __Type { kind 이름 ofType { kind 이름 ofType { kind 이름 ofType { kind 이름 ofType { kind 이름 ofType { kind 이름 ofType { kind 이름 ofType { kind 이름 } } } } } } } } ``` {% endtab %} {% endtabs %} ## Panther GraphQL API 사용 방법 ### 1단계: Panther GraphQL API URL 확인 GraphQL API URL을 찾으려면: * Panther 콘솔의 오른쪽 상단에서 톱니바퀴 아이콘을 클릭하여 설정을 연 다음 **개발자 도구** > **API 토큰**. * 페이지 상단에서 다음을 확인하세요: **API URL**. * GraphQL API URL 구조는 Panther 배포 모델에 따라 다릅니다: * [SaaS](/ko/system-configuration/panther-deployment-types.md) 배포: `https://api.{YOUR_PANTHER_DOMAIN}.runpanther.net/public/graphql` * [Cloud Connected](/ko/system-configuration/panther-deployment-types.md) 그리고 [자가 호스팅](/ko/system-configuration/panther-deployment-types.md) 배포: `https://{YOUR_PANTHER_DOMAIN}/v1/public/graphql`
### 2단계: API 토큰 생성 * 참조 [API 토큰을 만드는 방법에 대한 이 지침](/ko/panther/api.md#how-to-create-a-panther-api-token). ### 3단계: Panther GraphQL API 호출 다음을 사용하여 테스트하는 것 외에도 [API 플레이그라운드](/ko/panther/api/api-playground.md)GraphQL-over-HTTP API를 호출하는 방법은 두 가지입니다: * 옵션 1(권장): 전송 관련 복잡성을 추상화하기 위해 GraphQL 클라이언트를 설치하고 사용하세요 * 옵션 2: HTTP 호출을 수동으로 구성하세요 {% tabs %} {% tab title="GraphQL 클라이언트" %} **옵션 1: GraphQL 클라이언트 설치 및 사용 *****(권장)*** 모든 GraphQL 작업은 본질적으로 단순한 HTTP 호출이지만, GraphQL 클라이언트를 사용하면 더 사용자 친화적이라는 장점이 있습니다. 다음을 사용하는 것을 권장합니다: * [`graphql-request`](https://github.com/prisma-labs/graphql-request) NodeJS 프로젝트에 * [`gql`](https://github.com/graphql-python/gql) Python 프로젝트에 * [`go-graphql-client`](https://github.com/hasura/go-graphql-client) Go 프로젝트에 시스템의 알러트 첫 페이지를 가져오기 위해 GraphQL 쿼리를 구성하는 방법의 예시는 다음과 같습니다: {% tabs %} {% tab title="NodeJS" %} ```javascript // npm install graphql graphql-request import { GraphQLClient, gql } from 'graphql-request'; const client = new GraphQLClient( 'YOUR_PANTHER_API_URL', { headers: { 'X-API-Key': 'YOUR_API_KEY' } }); // `PaginateAlerts`는 작업의 별칭입니다 const query = gql` query PaginateAlerts { alerts( input: { createdAtAfter: "2023-06-14T21:00:00Z", createdAtBefore: "2023-06-21T21:59:59Z" }) { edges { node { id 제목 심각도 상태 } } pageInfo { hasNextPage endCursor } } } `; client.request(query).then((data) => console.log(data)); ``` {% endtab %} {% tab title="Python" %} ```python # pip install gql aiohttp from gql import gql, Client from gql.transport.aiohttp import AIOHTTPTransport transport = AIOHTTPTransport( url="YOUR_PANTHER_API_URL", headers={"X-API-Key": "YOUR_API_KEY"} ) client = Client(transport=transport, fetch_schema_from_transport=True) # `PaginateAlerts`는 작업의 별칭입니다 query = gql( """ query PaginateAlerts { alerts( input: { createdAtAfter: "2023-06-14T21:00:00Z", createdAtBefore: "2023-06-21T21:59:59Z" }) { edges { node { id 제목 심각도 상태 } } pageInfo { hasNextPage endCursor } } } """ ) result = client.execute(query) print(result) ``` {% endtab %} {% tab title="Go" %} ```go // go get -u github.com/hasura/go-graphql-client package main import ( "context" "encoding/json" "fmt" "net/http" "github.com/hasura/go-graphql-client" ) // 정적 타입 언어는 GraphQL과 잘 맞지 않습니다 var query struct { Alerts struct { Edges []struct { Node struct { Id graphql.String Title graphql.String Severity graphql.String Status graphql.String } } PageInfo struct { HasNextPage graphql.Boolean EndCursor graphql.String } } `graphql:"alerts(input: { createdAtAfter: \"2023-06-14T21:00:00Z\", createdAtBefore: \"2023-06-21T21:59:59Z\" })"` } func main() { client := graphql. NewClient("YOUR_PANTHER_API_URL", nil). WithRequestModifier(func(req *http.Request) { req.Header.Set("X-API-KEY", "YOUR_API_KEY") }) if err := client.Query(context.Background(), &query, nil); err != nil { panic(err) } formattedResult, _ := json.MarshalIndent(query.Alerts, "", "\t") fmt.Println(string(formattedResult)) fmt.Println(query.Alerts.PageInfo.HasNextPage) } ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="HTTP 호출 구성" %} **옵션 2: HTTP 호출 수동 구성** 예시 요청: ```bash curl 'YOUR_PANTHER_GRAPHQL_API_URL' \ -H 'Content-Type: application/json' \\ -H 'X-API-Key: {YOUR_API_KEY}' \ -d '{"query":"\n query Foo {\n alerts {\n edges {\n node {\n id\n }\n }\n }\n }","variables":{}}' ``` 위 쿼리는 Panther 알러트의 첫 페이지를 모두 반환합니다. GraphQL을 처음 사용하는 경우 다음 사항을 참고하세요: * 엔드포인트는 하나뿐입니다. * HTTP 작업은 항상 `POST입니다.` * API 작업은 `POST`본문에 정의됩니다. * 다음 작업의 `POST` 본문에는 **항상** 다음 키가 포함됩니다: * `query` - 실행할 GraphQL 작업을 정의하는 GraphQL 문자열 * `variables` - 쿼리에 전달될 수 있는 선택적 변수 집합 * `operationName` - 이 작업에 대한 선택적 "별칭" * 작업이 데이터를 반환하는 경우에는 항상 반환할 필드 집합을 선택해야 합니다. 참고: 한 GraphQL 작업에서 다른 작업으로 바뀌는 유일한 것은 HTTP의 본문입니다 `POST`. {% endtab %} {% endtabs %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.panther.com/ko/panther/api/graphql.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.