- 조회 엔드포인트에는
context-targeting:read권한이, 쓰기 엔드포인트에는context-targeting:write권한이 필요합니다. 사전 준비를 참고하세요. - API 키로 프로젝트가 정해지므로 경로에는 프로젝트 ID가 들어가지 않습니다.
- 각 엔드포인트에는 그 엔드포인트에서만 발생하는 오류를 적었습니다. 모든 엔드포인트에 공통으로 적용되는 오류는 오류 코드를 참고하세요.
타겟팅 객체
타겟팅 목록 조회, 타겟팅 조회, 생성, 이름 변경 엔드포인트는 다음 형식으로 타겟팅을 반환합니다. 삭제 엔드포인트는_id만 반환합니다. API 필드에서는 옵션을 categories라고 부릅니다.
categories와 syncedAt은 응답에 따라 포함 여부가 다릅니다.
syncedAt은 타겟팅의 첫 로드가 끝날 때까지 생략됩니다. 컨텍스트 ID를 변경하거나 옵션을 추가·이동·분리한 뒤에도 보통 다음 로드가 끝날 때까지 생략됩니다.
변경 사항이 로드됐는지 확인하려면 변경에 성공한 시각과
syncedAt을 비교하세요. syncedAt이 있는지 없는지로 판단하지 마세요. 변경 반영 시점을 참고하세요.타겟팅 목록 조회
프로젝트의 모든 문맥 타겟팅을 페이지 나눔 없이 한 번에 반환합니다. 오디언스 타겟팅은 포함되지 않습니다.요청
context-targeting:read 권한이 필요합니다.
쿼리 파라미터
요청 예시
응답 예시
200 응답으로 타겟팅 객체 배열을 반환합니다.
타겟팅 조회
문맥 타겟팅 하나를 반환합니다.요청
context-targeting:read 권한이 필요합니다.
경로 파라미터
쿼리 파라미터
요청 예시
응답 예시
200 응답으로 타겟팅 객체를 반환합니다.
타겟팅 생성
문맥 타겟팅을 생성합니다. 같은 요청에서 옵션도 함께 만들 수 있습니다.요청
context-targeting:write 권한이 필요합니다.
요청 본문
categories의 각 항목에는 다음 필드를 씁니다.
- 한 요청에 넣을 수 있는 컨텍스트 ID는 하위 옵션의 컨텍스트 ID를 포함해 모두 합쳐 최대 10,000개입니다.
- 모든 ID는 서버가 생성합니다.
_id를 넣은 요청은400으로 실패합니다. categories의 항목에는parent를 넣을 수 없습니다. 넣으면 요청이400으로 실패합니다. 기존 옵션 그룹에 옵션을 추가하려면 옵션 그룹에 옵션 추가를 참고하세요.- 옵션을 100개보다 많이 만들려면 먼저 타겟팅을 만든 뒤 옵션 일괄 추가를 사용하세요.
요청 예시
응답 예시
201 응답으로 옵션이 포함된 새 타겟팅 객체를 반환합니다.
_id를 저장해 두세요. 나중에 타겟팅을 변경할 때 필요합니다.
오류
이름이 이미 사용 중이면 다음과 같이 응답합니다.
타겟팅 이름 변경
타겟팅의 이름을 변경합니다. 옵션과 컨텍스트 ID는 바뀌지 않습니다.요청
context-targeting:write 권한이 필요합니다.
경로 파라미터
요청 본문
요청 예시
응답 예시
200 응답으로 이름이 바뀐 타겟팅 객체를 categories 없이 반환합니다. 옵션을 읽으려면 타겟팅 조회나 옵션 목록 조회를 사용하세요.
타겟팅 삭제
타겟팅과 그 안의 모든 옵션(옵션 그룹과 하위 옵션 포함)을 삭제합니다.요청
context-targeting:write 권한이 필요합니다.
경로 파라미터
요청 예시
응답 예시
200 응답으로 삭제된 타겟팅의 ID만 반환합니다.
일괄 작업
요청 한 번으로 타겟팅을 최대 100개까지 생성, 이름 변경, 삭제할 수 있습니다.- 먼저 요청 전체를 검사합니다. 항목 수(1~100개), 각 필드의 형식, 요청당 합계를 확인합니다. 검사를 통과하지 못하면 요청 전체가
400으로 실패하고 아무것도 적용되지 않습니다. - 프로젝트의 다른 API 쓰기 요청이 처리 중이면 요청 전체가
409 CONTEXT_TARGETING_WRITE_IN_PROGRESS로 실패할 수 있으며, 이때 아무것도 적용되지 않습니다. 동시 쓰기를 참고하세요. - 그 밖의 경우에는 모든 항목이 실패하더라도
200응답으로 항목별 결과를 반환합니다. 일부 항목만 성공하고 나머지는 실패할 수 있으므로 항목마다success를 확인하세요.
생성과 삭제 요청은 검사를 통과한 항목을 한꺼번에 적용합니다. 예기치 않은 오류가 발생하면 요청의 어떤 항목도 적용되지 않습니다. 이때 검사에서 실패한 항목은 원래 오류를 그대로 받고, 나머지 항목은
500 UNCATCHED로 실패합니다. 같은 요청을 다시 보내세요. 이름 변경 요청은 항목을 요청 순서대로 하나씩 따로 적용합니다. 자세한 내용은 일괄 작업 응답을 참고하세요.
타겟팅 일괄 생성
타겟팅을 최대 100개까지 생성하며, 타겟팅마다 옵션은 함께 만들어도 되고 만들지 않아도 됩니다.요청
context-targeting:write 권한이 필요합니다.
요청 본문
한 요청의 모든 항목을 합쳐 옵션은 하위 옵션을 포함해 최대 100개, 컨텍스트 ID는 최대 10,000개까지 넣을 수 있습니다.
요청 예시
응답 예시
성공한 항목의data는 옵션이 포함된 새 타겟팅 객체입니다. 이 예시에서 세 번째 항목은 “News Sections”라는 이름의 타겟팅이 이미 있어서 실패합니다.
TARGETING_NAME_DUPLICATE에는 detail.existingId 대신 그 항목의 인덱스인 detail.duplicateOfIndex가 들어 있습니다.
타겟팅 이름 일괄 변경
타겟팅 최대 100개의 이름을 변경합니다.요청
context-targeting:write 권한이 필요합니다.
요청 본문
요청 예시
응답 예시
성공한 항목의data는 이름이 바뀐 타겟팅 객체이며, categories는 들어 있지 않습니다.
타겟팅 일괄 삭제
타겟팅 최대 100개와 그 안의 모든 옵션을 삭제합니다.요청
context-targeting:write 권한이 필요합니다.
요청 본문
요청 예시
응답 예시
성공한 항목의data에는 삭제된 타겟팅의 _id만 들어 있습니다. 이 예시에서는 승인되었고 아직 종료되지 않은 캠페인이 타겟팅의 옵션 하나를 포함하고 있어 타겟팅이 삭제되지 않습니다.