퍼시스티드 쿼리 생성하기

퍼시스티드 쿼리는 GraphQL과 REST API를 결합한 것입니다. 일반적인 GraphQL 쿼리를 사이트에 게시하고, REST 엔드포인트처럼 고유한 URL로 접근할 수 있습니다.

예를 들어, 다음과 같은 퍼시스티드 쿼리를 통해 웹사이트 데이터를 제공할 수 있습니다.

• /graphql-query/homepage-posts
• /graphql-query/user-widget
• /graphql-query/post-content（게시물 ID를 전달하여 실행: ?post=1）
• /graphql-query/post-content/es（게시물 내용을 스페인어로 번역）
• 기타

​

퍼시스티드 쿼리 실행하기

퍼시스티드 쿼리를 게시하면 해당 퍼마링크를 통해 실행할 수 있습니다.

퍼시스티드 쿼리는 GET 방식으로 접근하기 때문에 브라우저에서 직접 실행할 수 있으며, 요청한 데이터를 JSON 형식으로 얻을 수 있습니다.

​

애플리케이션에서 퍼시스티드 쿼리 실행하기

가이드 「클라이언트에서 GraphQL 서버에 연결하기」의 안내를 따라 주세요.

​

모든 퍼시스티드 쿼리에 접근하기

플러그인 메뉴에서 「Persisted Queries」를 클릭하면 생성된 퍼시스티드 쿼리 목록이 표시됩니다.

​

새 퍼시스티드 쿼리 생성하기

「Add New GraphQL persisted query」 버튼을 클릭하여 WordPress 에디터를 엽니다.

제목을 입력하고 퍼마링크가 예상한 대로인지 확인한 후, GraphQL 쿼리를 입력하고 스키마 구성을 선택하여 옵션을 조정합니다. 준비가 되면 Publish 버튼을 클릭하면 퍼마링크가 퍼시스티드 쿼리의 엔드포인트가 됩니다.

엔드포인트（및 소스）로의 링크는 「Persisted Query Endpoint Overview」 사이드바 패널에 표시됩니다.

기본적으로 퍼시스티드 쿼리의 엔드포인트 경로는 /graphql-query/이며, 이 값은 설정에서 변경할 수 있습니다.

​

쿼리 에디터

에디터 내의 GraphiQL 클라이언트는 GraphQL 퍼시스티드 쿼리를 입력하는 곳입니다.

에디터에는 Explorer 애드온이 포함되어 있어, 왼쪽 패널의 필드를 클릭하여 쿼리를 구성할 수 있습니다. 「Run」 버튼을 클릭하면 쿼리가 실행되어 응답을 미리 볼 수 있습니다.

​

스키마 구성

퍼시스티드 쿼리에서 요청된 필드에 대한 접근 권한은 스키마 구성에서 정의합니다.

따라서 스키마 구성을 생성한 후 드롭다운에서 선택해야 합니다（또는 없음이나 기본값을 사용할 수 있습니다）.

​

비공개 퍼시스티드 쿼리

퍼시스티드 쿼리의 상태를 private으로 설정하면 관리자 사용자만 엔드포인트에 접근할 수 있습니다. 이를 통해 데이터에 접근 권한이 없는 사용자에게 데이터가 의도치 않게 공유되는 것을 방지할 수 있습니다.

예를 들어, 지표 보고서 작성을 위한 데이터 조회 등 애플리케이션 관리에 도움이 되는 비공개 퍼시스티드 쿼리를 생성할 수 있습니다.

​

비밀번호로 보호된 퍼시스티드 쿼리

특정 클라이언트를 위해 퍼시스티드 쿼리를 생성하는 경우, 비밀번호를 설정하여 해당 클라이언트만 엔드포인트에 접근할 수 있도록 추가 보안 수준을 제공할 수 있습니다.

비밀번호로 보호된 퍼시스티드 쿼리에 처음 접근하면 비밀번호를 요청하는 화면이 표시됩니다.

비밀번호가 입력되고 검증되면, 사용자는 원하는 엔드포인트에 접근할 수 있습니다.

​

URL 파라미터를 통한 퍼시스티드 쿼리의 동적화

퍼시스티드 쿼리를 실행할 때 각 변수의 값을 URL 파라미터（변수 이름 사용）로 설정할 수 있습니다. 「Do URL params override variables?」 옵션이 활성화되어 있으면 URL 파라미터가 우선합니다. 비활성화된 경우, 변수 딕셔너리에 정의된 값이 우선됩니다（있는 경우）.

예를 들어, 이 쿼리에서는 결과 수를 변수 $limit으로 제어하며, 기본값은 3입니다.

이 퍼시스티드 쿼리를 실행할 때 ?limit=5를 전달하면 대신 5개의 결과를 반환하는 쿼리가 실행됩니다.

​

퍼시스티드 쿼리 계층 생성하기

API 계층 생성하기의 안내를 읽어 주세요.

​

퍼시스티드 쿼리 비활성화하기

옵션에서 「Enabled」를 false로 설정하면 퍼시스티드 쿼리를 비활성화할 수 있습니다.

이 기능은 퍼시스티드 쿼리를 API 계층의 일부로 사용하여 자식 퍼시스티드 쿼리에 공통 동작을 제공하되, 자신은 실행할 필요가 없을 때 유용합니다.

​

퍼시스티드 쿼리 설명 추가하기

문서 설정 패널의 「Excerpt」 필드를 사용하여 퍼시스티드 쿼리에 설명을 추가합니다.

자세한 내용은 가이드 「API에 설명 추가하기」를 참고해 주세요.

​

온라인 게시 전 퍼시스티드 쿼리 테스트하기

상태가 draft 또는 pending인 퍼시스티드 쿼리는 스키마 에디터 사용자만 이용할 수 있습니다.

퍼시스티드 쿼리를 생성하고 스키마 구성을 할당한 후, draft 또는 pending으로 게시하여 테스트할 수 있습니다（예: 액세스 제어 규칙이 적절한지 확인）.

승인 후에만 상태를 publish로 설정하여 모든 사용자에게 퍼시스티드 쿼리를 공개합니다.

​

소스 보기

엔드포인트에 ?view=source를 추가하면 퍼시스티드 쿼리의 구성이 표시됩니다（사용자가 로그인되어 있고 사용자 역할에 접근 권한이 있는 경우）.

​

WordPress 에디터에서의 설정

에디터 본문의 입력 항목은 다음과 같습니다.

문서 설정의 입력 항목은 다음과 같습니다.