설명서Experience Platform쿼리 서비스 안내서

쿼리 끝점

Last update: Thu Oct 30 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

작성 대상:

  • 개발자

샘플 API 호출

다음 섹션은 /queries API에서 Query Service 끝점을 사용하여 수행할 수 있는 호출을 안내합니다. 각 호출에는 일반 API 형식, 필요한 헤더를 보여주는 샘플 요청 및 샘플 응답이 포함됩니다.

쿼리 목록 검색

/queries 끝점에 대한 GET 요청을 수행하여 조직에 대한 모든 쿼리 목록을 검색할 수 있습니다.

API 형식

GET /queries
GET /queries?{QUERY_PARAMETERS}
  • {QUERY_PARAMETERS}: (선택적) 매개 변수가 응답에 반환된 결과를 구성하는 요청 경로에 추가되었습니다. 여러 매개 변수를 포함할 수 있으며 앰퍼샌드(&)로 구분됩니다. 사용 가능한 매개 변수는 아래에 나와 있습니다.

쿼리 매개 변수

다음은 쿼리를 나열하는 데 사용할 수 있는 쿼리 매개 변수의 목록입니다. 이러한 매개 변수는 모두 선택 사항입니다. 매개 변수 없이 이 끝점을 호출하면 조직에서 사용할 수 있는 모든 쿼리를 검색합니다.

매개변수
설명
orderby
결과를 정렬하는 데 사용할 필드를 지정합니다. 지원되는 필드는 created 및 updated입니다. 예를 들어 orderby=created은(는) 만들어진 항목별로 오름차순으로 결과를 정렬합니다. 만들기 전에 -을(를) 추가하면(orderby=-created) 내림차순으로 만들어진 항목별로 정렬됩니다.
limit
페이지에 포함된 결과 수를 제어할 페이지 크기 제한을 지정합니다. (기본값: 20)
start
ISO 형식 타임스탬프를 지정하여 결과 순서를 지정합니다. 시작 날짜가 지정되지 않은 경우 API 호출은 가장 오래 전에 생성된 쿼리를 먼저 반환한 다음 더 최근 결과를 계속 나열합니다.
ISO 타임스탬프를 사용하면 날짜 및 시간에 서로 다른 수준의 세부기간을 사용할 수 있습니다. 기본 ISO 타임스탬프는 2020-09-07 형식을 사용하여 2020년 9월 7일의 날짜를 나타냅니다. 보다 복잡한 예제는 2022-11-05T08:15:30-05:00(으)로 작성되며 2022년 11월 5일 오전 8:15:30(미국 동부 표준시)에 해당합니다. 시간대는 UTC 오프셋을 사용하여 제공될 수 있으며 접미사 "Z"(2020-01-01T01:01:01Z)로 표시됩니다. 시간대가 제공되지 않으면 기본값은 0입니다.
property
필드를 기반으로 결과를 필터링합니다. must 필터는 HTML 이스케이프되어야 합니다. 쉼표는 여러 필터 세트를 결합하는 데 사용됩니다. 지원되는 필드는 created, updated, state 및 id입니다. 지원되는 연산자 목록은 >(보다 큼), <(보다 작음), >=(보다 크거나 같음), <=(보다 작거나 같음), ==(과 같음), !=(과 같지 않음) 및 ~(포함)입니다. 예를 들어 id==6ebd9c2d-494d-425a-aa91-24033f3abeec은(는) 지정된 ID를 가진 모든 쿼리를 반환합니다.
excludeSoftDeleted
소프트 삭제된 쿼리를 포함해야 하는지 여부를 나타냅니다. 예를 들어 excludeSoftDeleted=false은(는) 일시 삭제된 쿼리를 포함​합니다. (부울, 기본값: true)
excludeHidden
비사용자 정의 쿼리를 표시할지 여부를 나타냅니다. 이 값을 false로 설정하면 CURSOR 정의, FETCH 또는 메타데이터 쿼리와 같은 비사용자 정의 쿼리가 포함​됩니다. (부울, 기본값: true)
isPrevLink
isPrevLink 쿼리 매개 변수는 페이지 매김에 사용됩니다. API 호출 결과는 해당 created 타임스탬프 및 orderby 속성을 사용하여 정렬됩니다. 결과 페이지를 탐색할 때 뒤로 페이징할 때 isPrevLink이(가) true로 설정됩니다. 쿼리의 순서를 반대로 합니다. 예제로 "다음" 및 "이전" 링크를 참조하십시오.

요청

다음 요청은 조직에 대해 생성된 최신 쿼리를 검색합니다.

curl -X GET https://platform.adobe.io/data/foundation/query/queries?limit=1 \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'

응답

성공적인 응답은 지정된 조직에 대한 쿼리 목록을 JSON으로 포함하는 HTTP 상태 200을 반환합니다. 다음 응답은 조직에 대해 생성된 최신 쿼리를 반환합니다.

{
    "queries": [
        {
            "isInsertInto": false,
            "request": {
                "dbName": "prod:all",
                "sql": "SELECT *\nFROM\n  accounts\nLIMIT 10\n"
            },
            "state": "SUCCESS",
            "rowCount": 0,
            "errors": [],
            "isCTAS": false,
            "version": 1,
            "id": "9957bd7f-2244-4fd5-91bc-077d7df1d8e5",
            "elapsedTime": 28,
            "updated": "2019-12-06T22:00:17.390Z",
            "client": "Adobe Query Service UI",
            "userId": "{USER_ID}",
            "created": "2019-12-06T22:00:17.362Z",
            "_links": {
                "self": {
                    "href": "https://platform.adobe.io/data/foundation/query/queries/9957bd7f-2244-4fd5-91bc-077d7df1d8e5",
                    "method": "GET"
                },
                "soft_delete": {
                    "href": "https://platform.adobe.io/data/foundation/query/queries/9957bd7f-2244-4fd5-91bc-077d7df1d8e5",
                    "method": "PATCH",
                    "body": "{ \"op\": \"soft_delete\"}"
                },
                "referenced_datasets": [
                    {
                        "id": "5b2bdd32230d4401de87397c",
                        "href": "https://platform.adobe.io/data/foundation/catalog/dataSets/5b2bdd32230d4401de87397c"
                    }
                ]
            }
        }
    ],
    "_page": {
        "orderby": "-created",
        "start": "2019-12-06T22:00:17.362Z",
        "next": "2019-08-01T00:14:21.748Z",
        "count": 1
    },
    "_links": {
        "next": {
            "href": "https://platform.adobe.io/data/foundation/query/queries?orderby=-created&start=2019-08-01T00:14:21.748Z"
        },
        "prev": {
            "href": "https://platform.adobe.io/data/foundation/query/queries?orderby=-created&start=2019-12-06T22:00:17.362Z&isPrevLink=true"
        }
    },
    "version": 1
}

쿼리 만들기

/queries 끝점에 대한 POST 요청을 수행하여 새 쿼리를 만들 수 있습니다.

API 형식

POST /queries

요청

다음 요청은 페이로드에 제공된 SQL 문으로 새 쿼리를 만듭니다.

curl -X POST https://platform.adobe.io/data/foundation/query/queries \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}' \
 -d '{
        "dbName": "prod:all",
        "sql": "SELECT account_balance FROM user_data WHERE user_id='$user_id';",
        "queryParameters": {
            user_id : {USER_ID}
            }
        "name": "Sample Query",
        "description": "Sample Description"
    }

아래 요청 예제에서는 기존 쿼리 템플릿 ID를 사용하여 새 쿼리를 만듭니다.

curl -X POST https://platform.adobe.io/data/foundation/query/queries \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}' \
 -d '{
        "dbName": "prod:all",
        "templateID": "f7cb5155-29da-4b95-8131-8c5deadfbe7f",
        "name": "Sample Query",
        "description": "Sample Description"
    }
속성
설명
dbName
SQL 쿼리를 만드는 데이터베이스의 이름입니다.
sql
만들려는 SQL 쿼리입니다.
name
SQL 쿼리의 이름입니다.
description
SQL 쿼리에 대한 설명입니다.
queryParameters
SQL 문의 매개 변수가 있는 값을 대체할 키 값 쌍입니다. 입력한 SQL 내에서 매개 변수 대체 요소를 사용하는 경우 if​만 필요합니다. 이 키 값 쌍에 대해서는 값 유형 검사가 수행되지 않습니다.
templateId
기존 쿼리의 고유 식별자입니다. SQL 문 대신 이를 제공할 수 있습니다.
insertIntoParameters
(선택 사항) 이 속성이 정의된 경우 이 쿼리는 INSERT INTO 쿼리로 변환됩니다.
ctasParameters
(선택 사항) 이 속성이 정의된 경우 이 쿼리는 CTAS 쿼리로 변환됩니다.

응답

성공한 응답은 새로 만든 쿼리의 세부 정보와 함께 HTTP 상태 202(허용됨)를 반환합니다. 쿼리가 활성화되고 성공적으로 실행되면 state이(가) SUBMITTED에서 SUCCESS(으)로 변경됩니다.

{
    "isInsertInto": false,
    "request": {
        "dbName": "prod:all",
        "sql": "SELECT * FROM accounts;",
        "name": "Sample Query",
        "description": "Sample Description"
    },
    "state": "SUBMITTED",
    "rowCount": 0,
    "errors": [],
    "isCTAS": false,
    "version": 1,
    "id": "4d64cd49-cf8f-463a-a182-54bccb9954fc",
    "elapsedTime": 0,
    "updated": "2020-01-08T21:47:46.865Z",
    "client": "API",
    "userId": "{USER_ID}",
    "created": "2020-01-08T21:47:46.865Z",
    "_links": {
        "self": {
            "href": "https://platform.adobe.io/data/foundation/query/queries/4d64cd49-cf8f-463a-a182-54bccb9954fc",
            "method": "GET"
        },
        "soft_delete": {
            "href": "https://platform.adobe.io/data/foundation/query/queries/4d64cd49-cf8f-463a-a182-54bccb9954fc",
            "method": "PATCH",
            "body": "{ \"op\": \"soft_delete\"}"
        },
        "cancel": {
            "href": "https://platform.adobe.io/data/foundation/query/queries/4d64cd49-cf8f-463a-a182-54bccb9954fc",
            "method": "PATCH",
            "body": "{ \"op\": \"cancel\"}"
        }
    }
}
NOTE
_links.cancel의 값을 사용하여 만들어진 쿼리를 취소할 수 있습니다.

ID로 쿼리 검색

/queries 끝점에 대한 GET 요청을 만들고 요청 경로에 쿼리의 id 값을 제공하여 특정 쿼리에 대한 자세한 정보를 검색할 수 있습니다.

API 형식

GET /queries/{QUERY_ID}
속성
설명
{QUERY_ID}
검색할 쿼리의 id 값입니다.

요청

curl -X GET https://platform.adobe.io/data/foundation/query/queries/4d64cd49-cf8f-463a-a182-54bccb9954fc \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'

응답

성공한 응답은 지정된 쿼리에 대한 자세한 정보와 함께 HTTP 상태 200을 반환합니다.

{
    "isInsertInto": false,
    "request": {
        "dbName": "prod:all",
        "sql": "SELECT * FROM accounts;",
        "name": "Sample Query",
        "description": "Sample Description"
    },
    "state": "SUBMITTED",
    "rowCount": 0,
    "errors": [],
    "isCTAS": false,
    "version": 1,
    "id": "4d64cd49-cf8f-463a-a182-54bccb9954fc",
    "elapsedTime": 0,
    "updated": "2020-01-08T21:47:46.865Z",
    "client": "API",
    "userId": "{USER_ID}",
    "created": "2020-01-08T21:47:46.865Z",
    "_links": {
        "self": {
            "href": "https://platform.adobe.io/data/foundation/query/queries/4d64cd49-cf8f-463a-a182-54bccb9954fc",
            "method": "GET"
        },
        "soft_delete": {
            "href": "https://platform.adobe.io/data/foundation/query/queries/4d64cd49-cf8f-463a-a182-54bccb9954fc",
            "method": "PATCH",
            "body": "{ \"op\": \"soft_delete\"}"
        },
        "cancel": {
            "href": "https://platform.adobe.io/data/foundation/query/queries/4d64cd49-cf8f-463a-a182-54bccb9954fc",
            "method": "PATCH",
            "body": "{ \"op\": \"cancel\"}"
        }
    }
}
NOTE
_links.cancel의 값을 사용하여 만들어진 쿼리를 취소할 수 있습니다.

쿼리 취소 또는 일시 삭제

/queries 끝점에 PATCH 요청을 하고 요청 경로에 쿼리의 id 값을 제공하여 지정된 쿼리를 취소하거나 일시 삭제하도록 요청할 수 있습니다.

API 형식

PATCH /queries/{QUERY_ID}
매개변수
설명
{QUERY_ID}
작업을 수행할 쿼리의 id 값입니다.

요청

이 API 요청은 페이로드에 JSON 패치 구문을 사용합니다. JSON 패치의 작동 방식에 대한 자세한 내용은 API 기본 사항 문서를 참조하십시오.

curl -X PATCH https://platform.adobe.io/data/foundation/query/queries/4d64cd49-cf8f-463a-a182-54bccb9954fc \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json',
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'
 -d '{
   "op": "cancel"
 }'
속성
설명
op
리소스에 대해 수행할 작업의 유형입니다. 허용되는 값은 cancel 및 soft_delete입니다. 쿼리를 취소하려면 값이 cancel인 op 매개 변수를 설정해야 합니다. 일시 삭제 작업은 GET 요청에 대해 쿼리가 반환되는 것을 중지하지만 시스템에서 쿼리가 삭제되지는 않습니다.

응답

성공적인 응답은 다음 메시지와 함께 HTTP 상태 202(허용됨)를 반환합니다.

{
    "message": "Query cancel request received",
    "statusCode": 202
}
recommendation-more-help
ccf2b369-4031-483f-af63-a93b5ae5e3fb