다른 앱의 레코드 참조하기
공개 식별자를 저장하고 SDK로 현재 사용자에게 허용된 레코드를 해석합니다.
다른 앱의 레코드 참조하기
명세 화면에서 시작한다면 리소스 명세에서 소유 앱과 리소스를 찾고 리소스 키, 검색 조건, 선언된 권한을 확인하세요. 아래 예제의 workshop.note를 해당 키로 바꾸고 소유 앱과 사용자에게 필요한 권한을 준비합니다. 명세 공개는 참조 검색 지원이나 레코드 접근 권한을 보장하지 않습니다. Resource 계약을 함께 참고하세요.
다른 앱의 모델이나 DB 테이블에 접근하지 않고 공개 Resource를 참조합니다. 이 예제는 Planner의 법인 소유 Task에 Workshop의 Note를 연결합니다. 두 앱을 같은 프로젝트에서 개발하고 Resource 만들기로 planner.task와 workshop.note를 준비하세요. 테이블 접두사는 각각 pln, wsp로 가정합니다.
소유 앱과 권한 준비
두 앱이 같은 샌드박스에서 준비돼야 합니다. 현재 사용자에게 Task 수정 권한과 Note 조회 권한 및 각각 필요한 법인 범위를 부여하세요. 선행 앱 선언이나 앱 설치 자체는 데이터 권한을 부여하지 않습니다.
현재 표준 생성 리소스는 공개 descriptor와 기존 viewAny·view Policy를 사용하는 기본 참조 resolver를 제공합니다. 추가 resolver를 먼저 만들 필요는 없습니다. 비공개 필드나 내부 전용 리소스를 노출하지 말고, 리소스의 공개 연동 여부와 descriptor를 검토하세요. 사용자 정의 resolver·과거 시점 조회는 별도 계약 구현이 필요합니다.
제공자 조회 범위 유지
제공자의 search()는 기존 상한까지 권한·검색 조건·안정적인 정렬을 적용해
조회하고, 반환하지 않는 페이지 총건수를 계산하지 않도록 구현합니다.
searchPage()와 쿼리·직렬화 규칙을 공유하되, 페이지 조회의 정확한 총건수는
유지하세요. 상한 보정과 사용자·조직·날짜·목적 검사를 보존하고 반환 필드에
필요한 관계만 읽습니다. 필드 축소는 이미 명시적으로 제한된 응답 계약에서만
적용하세요. 빈 결과·권한 거부를 포함해 두 메서드의 결과와 SQL 횟수를 비교합니다.
참조 식별자 저장
Planner에 새 migration을 추가합니다. 아래는 up() 내부이며 필요한 import·down()·적용 절차는 데이터 모델과 마이그레이션을 따릅니다. 예제의 복합 인덱스 이름을 유지하고 되돌릴 때 인덱스와 세 컬럼을 제거합니다.
Schema::table('pln_tasks', function (Blueprint $table): void {
$table->string('note_app_key', 64)->nullable();
$table->string('note_resource_key', 128)->nullable();
$table->string('note_public_id', 128)->nullable();
$table->index(['note_app_key', 'note_resource_key', 'note_public_id'], 'pln_task_note_ref');
});다른 앱 숫자 PK로 FK를 만들지 않습니다. 공개 식별자·App 키·Resource 키가 관계의 정체성이며 저장한 표시명은 현재 조회 결과를 대신하지 않습니다. 허용된 Core 식별자의 FK는 Core 식별자를 외래키로 참조하기와 구분합니다.
보호된 API에서 해석
생성된 Planner TaskController에 아래 import를 추가하고 클래스 안에 linkNote()를 추가합니다. 기존 보호 Route 그룹과 Policy를 유지하세요.
use DateTimeImmutable;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Nexia\Organization\Contracts\OrganizationDirectory;
use Nexia\ResourceReference\Contracts\ResourceReferences;
use Nexia\ResourceReference\ResourceReferenceResolutionContext;public function linkNote(Request $request, string $task): JsonResponse
{
$record = $this->resolveTask($request, $task, 'planner.task.update');
$this->authorize('update', $record);
$data = $request->validate(['note_public_id' => ['required', 'uuid']]);
$legalEntity = app(OrganizationDirectory::class)
->requireLegalEntityByKey($record->legal_entity_id);
$context = new ResourceReferenceResolutionContext(
legalEntity: $legalEntity,
actor: $request->user(),
asOf: new DateTimeImmutable(),
purpose: 'planner.task.note',
);
$references = app(ResourceReferences::class);
abort_unless($references->hasProvider('workshop.note'), 422);
$note = $references->resolve('workshop.note', $data['note_public_id'], $context);
abort_if($note === null, 422);
$record->note_app_key = $note->appKey;
$record->note_resource_key = $note->resourceKey;
$record->note_public_id = $note->resourceId;
$record->save();
return response()->json(['note_reference' => [
'app_key' => $note->appKey,
'resource_key' => $note->resourceKey,
'public_id' => $note->resourceId,
]]);
}생성된 TaskController import를 사용하는 기존 인증된 App API Route 그룹 안에 다음 Route를 추가합니다:
Route::post('/tasks/{task}/note', [TaskController::class, 'linkNote'])
->whereUuid('task');요청에서 App 키·Resource 키·숫자 법인 ID를 자유롭게 받지 않습니다. 수정할 Task의 저장 소유자로 문맥을 만들고 Note 소유 앱이 조회를 다시 인가합니다. null·provider 부재·권한 오류를 임의 표시값으로 바꿔 저장하지 않습니다. 외부 참조 해석과 앱 저장은 분산 트랜잭션이 아니므로 확정 업무 시점에는 다시 검증해야 합니다.
선택 후보가 필요하면 같은 인가 문맥으로 searchPage('workshop.note', $query, $context, page: 1, perPage: 25)를 호출하고 반환된 공개 식별자로 위 저장 경로를 사용합니다. 사용자가 고른 ID도 저장 전에 다시 해석합니다. 검색은 지원되는 소유자 계약 안에서만 동작하며 임의 테이블 검색이 아닙니다.
확인과 실패 처리
두 앱의 nexia dev 준비 완료 후 허용된 Task·Note를 연결하고 새로고침합니다. 표시할 때 저장된 식별자를 같은 SDK로 다시 해석해 현재 허용된 이름만 보여 주세요. 다음을 함께 확인합니다.
- 다른 법인·권한 없는 Note·없는 UUID는 연결되지 않습니다.
- Note 조회 권한 회수 또는 소유 앱 사용 불가 시 기존 참조를 정상 데이터처럼 표시하지 않습니다.
- Task 수정 권한이 없으면 직접 API 호출도 거절합니다.
- 예전 이름을 저장해도 현재 이름이나 현재 권한의 근거로 사용하지 않습니다.
기본 resolver는 현재 상태를 조회합니다. 과거 시점·기간 해석을 지원한다고 가정하지 마세요. 데이터 전체를 복사해 권한 검사를 우회하거나 소유 앱의 코드를 가져오는 방식은 사용하지 않습니다. App 테스트하기에서 권한별 결과를 기록하세요.
보호정보가 필요한 ID 조회
ResourceReferenceResolutionContext에 includeProtectedValues: true를 지정하고 resolve() 또는 resolveMany(), 또는 표준 query()나 queryBatch()의 ID 조건으로 조회하세요. 소유 앱이 사용 목적과 사용자·조직 권한을 확인하고 허용한 값만 protectedValues()로 반환합니다. 옵션은 권한을 부여하지 않으며, 제공자가 지원하지 않거나 허용하지 않으면 값이 없거나 요청이 거부될 수 있습니다. 검색·페이지·기간 조회, 초기화 및 셀프서비스 경로에서는 지원하지 않습니다. 공개 snapshot()과 직렬화에는 포함되지 않으므로 값이 필요한 곳에서만 사용하고 로그에 남기지 마세요. 대응 SDK·Core·Manager가 모두 적용되어야 합니다. 기존 일반 조회의 동작은 유지됩니다. 구형 환경에서는 보호정보 없이 재시도하지 마세요.
참조 제공자 내부의 추가 조회
Core와 Manager 런타임을 함께 업데이트하면 일반 사용자 권한으로 실행되는 참조 제공자도 기존 ResourceReferences 메서드로 다른 공개 리소스를 검증할 수 있습니다. 개발 샌드박스와 설치된 공유 런타임에 모두 적용됩니다. 다른 앱의 Eloquent 모델이나 DB join을 노출하는 기능은 아니며 새 SDK 메서드는 필요하지 않습니다.
Core는 사용자·테넌트·법인·운영 조직 범위를 유지하고 각 소유 앱의 권한을 다시 확인합니다. 참조 제공자는 한 호출 경로에서 최대 세 단계까지 실행하며, 중첩 단계마다 시간을 새로 부여하지 않고 원래 콜백 기한을 공유합니다. 동일한 유효 조회 요청 안에서 제공자 존재 여부와 검증된 단건·배치 결과를 재사용합니다. 표준 조회가 제공되면 query()의 ids로 목록을 묶어 조회하고, 구형 호스트에서는 resolveMany()를 사용하세요. hasProvider()는 제공자 존재 확인이며 레코드 조회 권한을 보장하지 않습니다.
순환·깊이 초과·기한 초과는 각각 RUNTIME_REFERENCE_CYCLE, RUNTIME_REFERENCE_DEPTH_EXCEEDED, RUNTIME_REFERENCE_DEADLINE_EXCEEDED 코드로 구분됩니다. Agent 위임과 셀프서비스·프로필 조회는 기존 제한 계약을 유지합니다. 일반 의존 조회 권한으로 해당 제한을 우회하거나 데이터를 변경할 수 없습니다.
운영자는 Core 서명 기능 적용 전에 대응하는 런타임 이미지·ingress·콜백 워커 설정을 먼저 적용해야 합니다. 소스 수정만으로 런타임 지원이나 실제 앱 업무 성공이 검증되는 것은 아닙니다.
PHP SDK 0.10.12는 제공자를 위한 선택 계약 ResourceReferenceGroupedResolutionContribution을 추가합니다. 각 그룹의 키·정확한 기준 시각·필터와 사용자·조직 권한을 유지하고 거부된 참조는 제외하세요. 기존 일괄 조회 제공자는 그룹별 대체 경로를 유지합니다. 대응 런타임 적용 후 사용하세요. 공개 SDK 구현 예제를 참고하세요.
본인 전용 참조
인가된 셀프서비스 화면에서 일반 디렉터리 조회 권한 없이 현재 사용자의 레코드가 필요하면 provider가 ResourceReferenceSelfServiceContribution을 구현할 수 있습니다. authorizesSelfService(context)는 명시한 용도만 허용하고 사용자와 필요한 조직을 확인해야 합니다. 지원하는 단건·일괄·페이지·기간 조회 모두 필터나 페이지네이션 전에 해당 사용자와 조직으로 범위를 제한해야 합니다. 일반 권한을 우회하는 기능이 아니라 데이터 소유 앱이 보장하는 본인 전용 계약입니다.
Core 업데이트 후에는 전자결재 양식을 포함한 일반 App 요청에서도 이 계약을 사용할 수 있습니다. 사용자는 해당 법인의 활성 참여자이고 호출 App에 법인 범위의 본인 권한이 있어야 합니다. 데이터 소유 App이 호출 목적을 명시적으로 허용해야 하며, 소유 App의 일반 권한이나 추가 참조 조회 권한은 부여되지 않습니다. 호출 App은 자체 작업 권한도 검사해야 합니다.
Core가 원본 셀프서비스 권한을 복원하고 정확한 범위에 서명합니다. 요청 본문의 플래그로 활성화할 수 없으며, 계약을 구현하지 않은 provider·쓰기 설명·리포트 조합 작업은 이 경로로 허용되지 않습니다. 변조한 ID·필터·날짜, 다른 사용자·조직, 미등록 용도, 원본 권한 회수와 요청 문맥 정리를 선택된 앱 런타임에서 검증하세요. 대응하는 Core·SDK·런타임을 함께 반영한 뒤 적용 앱의 아티팩트를 다시 빌드해야 합니다.
공개 참조 조회 필드 계약
ResourceReferenceQuerySchemaContribution::querySchema()의 filterable, sortable,
searchable에 넣는 모든 키는 같은 리소스의 ResourceDescriptor::fieldSchema에도
선언해야 합니다. public_id, created_at, name도 자동으로 추가되지 않습니다.
이 제약은 다른 앱에 공개하는 참조 조회 계약입니다. 일반 목록의
resourceListFields()에 선언했다는 이유만으로 공개 참조 필드가 되지는 않습니다.
예를 들어 sortable: ['public_id', 'created_at'], searchable: ['name']을
제공한다면 descriptor에는 세 필드의 스키마가 있어야 하고, 제공자는 그 조건을
실제로 처리해야 합니다. 공개해도 되는 필드만 추가하세요. 내부 전용 필드라면
공개 querySchema()에서 제거하고 앱 내부 목록 쿼리에서만 사용합니다.
- 각 목록에 중복 키를 넣지 않습니다.
- 조회 조건은
ResourceReferencePagedSearchContribution을 구현한 제공자만 공개합니다. - 페이지 조회 제공자는 개별 레코드 조회도 지원해야 합니다.
- 스키마 선언은 접근 권한을 주지 않습니다. 제공자는 행·필드 권한을 계속 검사해야 합니다.
대응하는 SDK·Core·Manager·CLI를 적용하면 누락 필드는 query_field_undeclared와
contracts.<리소스 키>.query.sortable.<필드 키> 같은 경로로 표시됩니다.
query_duplicate, query_requires_paged, query_requires_resolve, query_invalid는
각각 중복·페이지 조회 지원·개별 조회 지원·형식 문제입니다.
파일·줄은 실제 예외 위치가 있을 때 표시하며 선언 경로에서 추측하지 않습니다.
nexia check는 앱 PHP를 실행하지 않는 소스 검사입니다. PHP로 동적으로 만드는
카탈로그가 Core에 승인되었다는 뜻이 아닙니다. nexia dev의 격리 카탈로그 검증을
확인하거나, SDK 테스트에서 실제 카탈로그 배열을
StandardCatalogPolicy::validate($catalog)에 전달하세요. 세부 오류는
CatalogValidationException::$issues로 확인할 수 있습니다.
CLI 명령과 옵션은 공개 CLI 문서에서도 확인할 수 있습니다.
표준 리소스 참조 조회
대응하는 SDK·Core·앱 런타임에서 선택적 ResourceReferenceQueries 계약을 사용합니다. query()로 조회를 준비하고 서로 다른 조회는 queryBatch()로 묶습니다. get()을 호출할 때 실제 조회하며, 결과에는 status, data, page, error가 들어갑니다.
use Nexia\ResourceReference\Contracts\ResourceReferenceQueries;
if ($references instanceof ResourceReferenceQueries) {
$result = $references->query('workshop.note', $context)->whereIn('id', $ids)->get();
if ($result['status'] !== 'success') {
// $result['error']['code']를 처리합니다. 오류를 빈 결과로 간주하지 마세요.
} else {
$resolved = $result['data'];
}
} else {
$resolved = array_values($references->resolveMany('workshop.note', $ids, $context));
}query()의 data는 항상 ResolvedResourceReference 객체 목록입니다. ID 하나는 0개 또는 1개, ID 목록·검색·기간 조회는 여러 개가 반환될 수 있습니다. 존재하지 않는 ID와 권한이 없는 ID가 모두 빠질 수 있으므로, 빈 결과만으로 데이터가 없다고 단정하지 마세요. 페이지 조회가 아니면 page는 null이고, 페이지 조회에는 number, last, perPage, total, hasMore가 들어갑니다. 호스트가 마지막 페이지나 전체 건수를 제공할 수 없으면 해당 값은 null입니다. 기존 계약에서 페이지를 받을 수 없다면 PAGE_UNAVAILABLE을 반환하며, 미지원·권한 거부 등 원인을 추측하지 않습니다.
지원하는 조회 메서드로 ID·검색어·기간을 지정합니다. 검색에는 건수 제한 또는 페이지를 쓰되 함께 지정하지 않습니다. 날짜·필터·정렬·검색은 소유 제공자가 지원하는 범위와 전달한 권한 문맥을 따릅니다. 기간 검색의 limit 기본값은 10,000이며, 최대 100,000을 명시하려면 해당 한도를 지원하는 SDK·Core·앱 런타임이 모두 필요합니다. 구형 또는 환경별 제한에 따라 10,000까지만 허용될 수 있습니다. 빈 검색어나 앞뒤 공백을 포함한 검색어의 정규화는 해당 호스트의 기존 처리에 따르므로 모든 환경에서 같다고 가정하지 마세요. 요청 건수가 허용 범위여도 응답 크기가 제한을 넘으면 HTTP 413(TOO_LARGE)으로 실패할 수 있습니다.
| 기존 조회 | 지원 호스트에서의 표준 조회 |
|---|---|
resolve() / resolveMany() | query(...)->where('id', $id)->get() / query(...)->whereIn('id', $ids)->get() |
search() | query(...)->search($text)->limit($limit)->get() |
searchPage() | query(...)->search($text)->page($page, $perPage)->get() |
searchEffectiveRange() | query(...)->searches($terms)->effectiveRange($from, $until)->limit($limit)->get() |
searchEffectiveRangePage() | query(...)->effectiveRange($from, $until)->page($page, $perPage)->get() |
searchCompleteEffectiveRange() | query(...)->searches($terms)->effectiveRange($from, $until)->complete()->get() |
resolveManyGrouped() | 그룹별 ID 조회에 문맥과 날짜를 유지하고, 기존처럼 그룹 전체 실패를 허용할 때 queryBatch()->allowSharedFailure()->get() 사용 |
searchBatch() | 독립 검색 조회를 각각 준비한 후 queryBatch()로 묶음 |
표의 query(...)에는 위 예제처럼 리소스 키와 인가된 문맥을 전달합니다. 기존 문맥의 필터·정렬과 빌더에 새로 지정한 조건은 기본적으로 제공자의 조회 스키마를 검증합니다. 페이지 검색에는 조회 스키마를 선언하고 페이지 검색을 지원하는 제공자가 필요합니다. ID 조회에 이런 조건을 결합하려면 문맥 또는 조회에서 effectiveThrough를 명시하고, 그룹 조회와 스키마 검증을 모두 지원하는 제공자를 사용해야 합니다. 이 경로는 보호정보를 지원하지 않으며 빈 문자열 ID를 전송 전에 INVALID_ARGUMENT로 거부합니다. 종료일이 없는 ID 조회, 기간 검색 또는 페이지 없는 건수 제한 검색에는 스키마 검증 조건을 결합할 수 없습니다.
기존 resolve() 호출의 문맥 필터나 정렬 처리를 그대로 유지해야 하면 표준 조회에 allowLegacyContextFilters()를 호출하세요. 제공자가 이 기존 문맥 값을 무시할 수 있으므로 권한 보장 수단으로 사용하면 안 됩니다. 이 옵션은 빌더의 where나 orderBy로 새로 지정한 조건에 대한 스키마 검증을 우회하지 않습니다. 기존 그룹 조회를 전환할 때는 필터가 있는 각 조회에 이 옵션을 따로 지정하고 그룹별 문맥과 날짜를 유지하세요.
예를 들어 $legacyContext가 기존 필터를 포함한 인가된 문맥이라면 다음과 같이 전달합니다.
$legacyResult = $references->query('workshop.note', $legacyContext)
->whereIn('id', $ids)
->allowLegacyContextFilters()
->get();완전 기간 조회는 빈 값이 아니고 각 160자 이하인 정확 검색어 1~100개를 받으며 완전한 응답은 최대 1,000건입니다. limit()이나 page()는 함께 사용할 수 없고, 대응하는 SDK·Core·앱 런타임과 제공자가 필요합니다. 제공자가 null을 반환하면 미지원 또는 완전성 확인 불가를 뜻하며 표준 결과에는 COMPLETE_RANGE_UNAVAILABLE이 들어갑니다. 완전한 빈 결과는 빈 data의 성공입니다. 구형 Core나 런타임이 새 동작을 HTTP 422로 거부하면 INVALID_QUERY가 반환될 수 있어 이 코드만으로 원인을 구분할 수 없습니다. 두 오류 모두 완전한 빈 결과로 처리하지 마세요.
SDK에서 실행할 수 없는 조건 조합이나 표준 처리를 지원하지 않는 맞춤 호스트는 전송 전에 UNSUPPORTED_IMPLEMENTATION을 반환합니다. 제공자가 스키마나 필드를 지원하지 않아 HTTP 422로 거부하면 표준 결과에는 INVALID_QUERY가 들어갈 수 있습니다. 반환된 오류 코드를 확인하고 어느 경우든 빈 성공 결과로 처리하거나 더 넓은 권한으로 자동 재시도하지 마세요.
$batch = $references->queryBatch([
$references->query('workshop.note', $context)->whereIn('id', $firstIds),
$references->query('workshop.note', $context)->whereIn('id', $secondIds),
])->get();
if ($batch['error'] !== null) {
// 묶음 요청 자체의 오류 코드를 처리합니다.
} else {
foreach ($batch['data'] as $item) {
// 각 항목은 query()와 같은 status/data/page/error 구조입니다.
if ($item['status'] !== 'success') {
// 항목별 오류를 처리하고 data를 정상 결과로 사용하지 마세요.
}
}
}배치 전체 status는 success, partial, error 중 하나입니다. 묶음 요청 자체가 잘못되면 바깥쪽 error에 INVALID_BATCH가 들어가고, 개별 실패는 각 항목에 남습니다. 오류에는 안정적인 code와 선택적 httpStatus만 담으며 상위 응답 본문이나 메시지는 담지 않습니다. 공유 전송의 실패는 여러 항목에 영향을 줄 수 있습니다. 프로그래밍 오류는 예외로 전파될 수 있습니다. 빈 배치는 전송 없이 성공합니다.
ID와 범위의 검증·보정은 선택한 조회 방식과 호스트의 기존 처리에 따릅니다. 일부 입력은 전송 전에 검증하고 다른 입력은 호스트에서 검사하거나 보정하므로, 빈 ID·앞뒤 공백이 있는 ID·한도·역순 날짜가 모두 전송 전에 거부된다고 가정하지 마세요. 보호정보는 id 또는 ids 조건에서만 조회하며 다른 조건에서는 PROTECTED_VALUES_UNAVAILABLE을 반환합니다. 로컬 인증 실패는 HTTP 상태 401인 UNAUTHENTICATED입니다. HTTP 상태 502인 UPSTREAM_AUTHENTICATION_FAILED는 콜백 인증 실패이며, 브라우저 사용자가 다시 로그인해야 한다는 뜻이 아닙니다.
기존 전송 메서드를 재정의한 맞춤 호스트는 해당 표준 처리를 명시적으로 지원해야 합니다. 그렇지 않으면 해당 조회를 전송하기 전에 UNSUPPORTED_IMPLEMENTATION을 반환하므로 그 호스트에서는 대응하는 기존 메서드를 사용하세요. 오류를 빈 성공 결과로 처리하면 안 됩니다. SDK 구현 소유자는 기존 재정의의 권한과 동작을 보존한 경우에만 지원을 선언해야 합니다.
resolveManyGrouped()에서 effective_through를 생략한 그룹을 전환할 때는 각 조회의 effectiveThrough()에 해당 그룹의 asOf를 명시하세요. 기존 그룹 조회의 기본값과 같아집니다. 기본적으로 날짜·필터가 다른 그룹은 한 번의 전송에 여러 조회가 담겨도 소유 앱에서 독립 실행됩니다. 지원 호스트에서 기존 묶음 처리 방식을 사용하려면 get() 전에 배치에 allowSharedFailure()를 호출하세요. 그러면 소유 앱의 그룹 조회가 허용되므로 그룹 단위 권한 거부나 실행 실패가 그 그룹의 모든 항목에 영향을 줄 수 있습니다. 호출자가 이 실패 범위를 허용하는 경우에만 사용하고, 어느 경우든 항목별 결과를 확인하세요. ID 목록과 기준일·종료일·필터가 같은 연속 조회는 하나의 조회를 공유할 수 있습니다. 사용자·조직·목적·정렬도 일치해야 묶이며, 요청 간 캐시는 추가하지 않습니다.
예를 들어 각 문맥과 날짜로 $queryA, $queryB를 준비한 뒤 다음과 같이 조회합니다.
$batch = $references->queryBatch([$queryA, $queryB])->allowSharedFailure()->get();기존 resolve, resolveMany, search, searchPage, searchEffectiveRange, searchEffectiveRangePage, searchCompleteEffectiveRange, resolveManyGrouped, searchBatch는 지원 호스트에서 표준 조회로 전환하도록 deprecated 안내하지만, 전환 기간에 계속 지원합니다. 기존 반환 형식과 예외 처리는 바뀌지 않습니다. 구형 호스트에서는 해당 기존 메서드를 유지하고, 제공자 인터페이스는 수정할 필요가 없습니다. 제거 날짜는 정하지 않았습니다. 누락된 ID를 더 넓은 권한으로 재조회하지 마세요.
Party·사용자·사람 프로필 조회
PHP SDK에서 IdentityQueries는 deprecated입니다. 새 코드는 Party·User 디렉터리 모델을 사용하고, 프로필은 PersonProfileDirectory로 읽습니다. 기존 호출의 status, data, page, error 응답은 유지됩니다. 호출 순서, 항목별 결과 또는 부분 실패가 필요한 기존 queryBatch() 호출은 유지합니다.
SDK 조회 API 전환표에서 기존 호출별 대체 코드를 확인하세요.
아래는 기존 코드의 호환용 예제입니다. 각 항목의 status와 error를 확인한 뒤 data를 사용하세요. 지원하지 않는 조건은 UNSUPPORTED_IMPLEMENTATION을 반환합니다.
use Nexia\Identity\IdentityQueries;
$identities = app(IdentityQueries::class);
$batch = $identities->queryBatch([
$identities->query('user')->where('public_id', $userPublicId),
$identities->query('profile')->whereIn('party_key', $partyKeys),
])->get();기준 날짜와 필터별 묶음 조회
지원 호스트의 새 코드는 ResourceReferenceQueries::queryBatch()를 우선 사용하세요. 아래 기존 메서드는 호환 기간과 구형 호스트를 위해 계속 제공됩니다.
PHP SDK 0.10.12에서 선택적 GroupedResourceReferences 계약을 지원합니다. 대응하는 Core와 App 런타임이 필요합니다. 기존 ResourceReferences 계약은 그대로 사용할 수 있으며, 모든 제공자가 과거 시점이나 임의 필터를 지원하는 것은 아닙니다.
앞에서 만든 인가된 $context와 소유 App이 공개한 Resource를 사용합니다. 아래 resource_ids에는 현재 작업에서 선택하고 검증한 공개 ID 목록을 전달합니다.
use Nexia\ResourceReference\Contracts\GroupedResourceReferences;
$references = app(ResourceReferences::class);
$groups = [
'current' => ['resource_ids' => $notePublicIds, 'as_of' => new DateTimeImmutable()],
'previous' => ['resource_ids' => $notePublicIds, 'as_of' => $previousDate],
];
if ($references instanceof GroupedResourceReferences) {
$resolved = $references->resolveManyGrouped('workshop.note', $groups, $context);
} else {
$resolved = [];
foreach ($groups as $key => $group) {
$groupContext = new \Nexia\ResourceReference\ResourceReferenceResolutionContext(
legalEntity: $context->legalEntity,
actor: $context->actor,
asOf: $group['as_of'],
purpose: $context->purpose,
operatingUnit: $context->operatingUnit,
includeProtectedValues: $context->includeProtectedValues,
effectiveThrough: $group['effective_through'] ?? $group['as_of'],
filters: $group['filters'] ?? $context->filters,
sort: $context->sort,
);
$resolved[$key] = $references->resolveMany(
'workshop.note', array_values(array_unique($group['resource_ids'])), $groupContext,
);
}
}반환값은 묶음 키 → 공개 ID → 해석 결과입니다. previousDate는 업무에서 검증한 DateTimeImmutable이며, 과거 시점을 지원하는 제공자에만 사용합니다. 각 묶음의 선택적 filters는 소유 App이 허용한 필드와 문자열 또는 문자열 목록만 사용합니다. 필터는 권한 검사를 대신하지 않습니다. 없는 항목과 접근할 수 없는 항목은 결과에서 빠질 수 있으므로, 입력과 결과를 대조하고 필수 항목 누락을 명시적으로 처리하세요.
전송 요청은 최대 31개 묶음과 400개 선택자, 묶음 조각당 고유 ID 100개로 나뉩니다. 전체 입력 범위도 제한하세요. 그룹 전송만으로 소유 앱의 SQL이 일괄 처리된다고 판단하지 말고 실제 규모에서 호출 수와 쿼리를 확인합니다. 누락된 ID를 더 넓은 범위로 재조회하지 마세요.
확인
허용된 두 기준 날짜의 결과를 비교하고, 접근 권한이 없는 ID와 미지원 필터가 정상 레코드로 처리되지 않는지 확인합니다. 단일 기준의 일괄 조회는 기존 resolveMany()를 사용하면 됩니다. SDK 0.10.2 이상은 해당 요청의 ID를 검증·중복 제거한 뒤 최대 100개씩 나누어 처리합니다.
카탈로그 검증 오류 확인
PHP SDK 0.10.7 이상에서 공개 참조 조회 선언이 잘못되면 CatalogValidationException::$issues에 field, rule, limit, actual 형식의 항목이 제공됩니다. query_field_undeclared는 공개 descriptor의 필드 누락, query_duplicate는 중복 키, query_requires_paged·query_requires_resolve는 조회 방식 선언의 불일치를 뜻합니다. 앱의 선언을 수정하고 다시 준비한 뒤 같은 조회를 확인하세요. ResourceQueryDiagnostics::issues()는 같은 계약 검사를 제공하며 일반 모델 목록의 필드를 자동 공개하지 않습니다.
참조 제공 결과의 링크
참조 제공자는 OpaqueResourceRefs::seal()로 자기 App이 소유한 리소스의 링크를 현재 사용자에게 발급할 수 있습니다. 핸들은 식별 정보만 전달하며, 링크를 열 때는 대상 리소스의 조회 권한을 별도로 검사합니다. 이 경로로 핸들을 해석하거나 다른 App을 재귀 조회할 수는 없습니다. 영향을 받은 조회를 재시도하기 전에 대응하는 Core와 Manager 런타임 수정을 함께 적용해야 합니다. DB 초기화나 App SDK API 변경은 필요하지 않습니다.
권한이 있는 여러 조직을 통합해 페이지 조회하기
대응하는 Core·Sandbox Runtime에서는 ResourceReferenceResolutionContext에
filters: ['organization_permission' => 'your-app.resource.read']를 지정해
호출 앱 소유의 운영 조직 권한으로 searchPage를 요청할 수 있습니다.
법인은 하나를 선택하고 운영 조직은 지정하지 않습니다. 이 키는 예약된
전송 필터이며, 호출 앱이 조직 목록을 임의로 전달하는 방식이 아닙니다.
Core가 현재 권한과 운영 조직 대상 범위를 확인해 최대 100개 조직을 서명합니다.
상한을 넘으면 일부만 반환하지 않고 요청을 거부합니다.
제공 앱은 기존 OrganizationTargetResolver::resolveListTargets로 해당 권한의
조직을 읽고 SubjectPermissionAuthorizer로 각 조직을 확인합니다. 참조 콜백에서는
서명된 조직과 법인만 허용하며 쓰기 권한은 부여하지 않습니다. 제공 앱은
대상 조건·검색·정렬·중복 제거를 SQL에서 적용한 뒤 페이지를 나누고, 해당
페이지의 표시 정보만 보강해야 합니다. 본인 대상 권한은 별도의 본인 필터가 필요합니다.
앱에서 이 필터를 사용하기 전에 Core 서명기와 Runtime을 함께 반영하세요. 이전 Runtime은 통합 조직 조회를 지원하지 않습니다. SDK 인터페이스 변경은 없으며, 변경 작업을 실행할 때는 현재 권한을 다시 확인해야 합니다.
독립 검색 일괄 요청
지원 호스트의 새 코드는 ResourceReferenceQueries::queryBatch()를 우선 사용하세요. 아래 기존 메서드는 호환 기간과 구형 호스트를 위해 계속 제공됩니다.
Laravel SDK 0.10.29와 대응하는 Core 및 앱 런타임에서 ResourceReferences가 BatchSearchResourceReferences를 구현하는지 확인한 후 searchBatch를 호출합니다. 검색마다 resource_key, query, context와 선택적 limit을 지정합니다. 결과는 입력 순서를 유지하며 상태 200에는 결과 목록이 있고 다른 상태는 개별 실패를 나타냅니다. 모든 상태를 확인하세요. 각 검색의 사용자, 조직, 목적, 기준 시각과 권한은 독립적으로 적용됩니다. 빈 입력은 요청을 보내지 않으며 전송 실패 시 개별 결과 전체를 받지 못할 수 있습니다. 선택적 계약이 없으면 search를 개별 호출하세요. 중첩 또는 제한된 런타임 문맥에서는 개별 조회로 전환될 수 있습니다.
Agent SQL에서 참조 선언하기
리소스를 가리키는 값은 실제 저장 컬럼에 기록하고, fieldSchema의 resource_reference에 대상 리소스를 선언하세요. 기존 UUID 필드를 유지해야 한다면 별도 참조 필드의 column으로 같은 컬럼을 지정할 수 있습니다.
'employment_public_id' => ['type' => 'string', 'format' => 'uuid'],
'employment_reference' => [
'type' => 'resource_reference',
'column' => 'employment_public_id',
'accepted_resource_keys' => ['people.employment'],
'selector_purpose' => 'your-app.employment',
'selector_permissions' => ['your-app.record.read'],
'nullable' => true,
],기존 문자열 필드에 관계 정보만 추가하려면 ['type' => 'string', 'format' => 'uuid', 'reference_resource_key' => 'people.employment']를 사용할 수 있습니다. 이 메타데이터는 선택기나 조회 권한을 추가하지 않습니다. 이 방식은 대응하는 Core와 SDK가 필요합니다.
필드 이름만으로 대상을 확정하지 마세요. 예를 들어 employment_public_id에 고용뿐 아니라 다른 종류의 공통 관계 ID가 들어갈 수 있다면 people.employment로 고정 선언하면 안 됩니다. 실제 생성·가져오기·조회 코드에서 값의 종류를 확인하세요. 계산된 필드는 선언만으로 SQL 컬럼이 되지 않으며, 리소스가 SQL에서 그 값을 제공해야 합니다.
선택기를 추가하지 않고 여러 대상을 선언할 때는 ID 문자열 필드에 accepted_resource_keys와 target_resource_key_field를 지정하고, 타입 컬럼도 문자열 필드로 선언합니다. 이 메타데이터가 기존 권한을 변경하지는 않습니다.
'context_resource_key' => ['type' => 'string'],
'context_public_id' => [
'type' => 'string',
'format' => 'uuid',
'accepted_resource_keys' => ['example.request', 'example.case'],
'target_resource_key_field' => 'context_resource_key',
],고정 대상에는 리소스 키 컬럼이 필요하지 않습니다. 한 컬럼이 여러 리소스를 가리킨다면 대상 키도 행에 저장하고 target_resource_key_field로 선언하세요. JOIN 시 ID뿐 아니라 대상 리소스 키도 일치해야 합니다. 실제 NULL이나 누락된 참조는 JOIN되지 않으므로 생성·가져오기·수정 경로와 기존 데이터의 상태를 함께 확인하세요.
SQL 조회는 각 리소스의 읽기 권한과 행 범위를 따로 적용합니다. 참조 선언은 권한이나 행 소유자를 부여하지 않습니다. 허용된 행의 물리 컬럼은 fieldSchema에 모두 열거하지 않아도 조회할 수 있고, 선언되지 않은 컬럼으로 JOIN하는 것도 가능합니다. 다만 확인되지 않은 관계를 이용한 JOIN은 결과의 의미와 정확성을 따로 검증해야 합니다.
에이전트는 sql_schema 결과의 sql_reference_targets를 참고하고, 대상 리소스를 다시 조회해 여러 단계를 따라갈 수 있습니다. 같은 앱의 단일 컬럼 FK가 한 리소스에 명확하게 대응하면 FK도 참조 후보로 제공합니다. 선언끼리 또는 선언과 FK가 충돌하는 컬럼은 sql_reference_conflicts에 표시하고, 해당 컬럼의 확정된 관계는 제공하지 않습니다. 충돌이 있어도 컬럼 조회와 SQL 실행은 가능합니다. 대상 리소스의 읽기 권한은 별도로 필요하며, 런타임과 등록된 앱 카탈로그에 해당 지원과 선언이 반영되어야 합니다.
컬럼과 선언을 정하는 방법
| 관계 | 테이블에 저장할 값 | fieldSchema | JOIN 조건 |
|---|---|---|---|
| 대상 리소스가 하나 | 대상의 공개 ID. 예: employment_public_id | 문자열 필드에 reference_resource_key | 원본 ID = 대상 public_id |
| 대상이 여러 종류 | 대상 리소스 키와 공개 ID | 문자열 또는 resource_reference 필드의 accepted_resource_keys와 target_resource_key_field | ID와 리소스 키를 모두 비교 |
| 같은 앱의 실제 FK | FK 컬럼. 예: grade_id | 해당 필드의 설명을 추가할 수 있음 | FK 컬럼 = FK가 가리키는 대상 컬럼 |
앱 간 관계를 위해 DB 외래 키를 만들 필요는 없습니다. 기존 컬럼이 가리키는 대상이 고정이라면 리소스 키를 행마다 중복 저장할 필요도 없습니다. 다만 ID는 앱의 생성·수정·가져오기 경로에서 일관되게 저장해야 합니다. 과거 행이 비어 있으면 의미를 확인하고 복구할 수 있는 값만 별도 마이그레이션으로 채우세요.
리소스의 public_id가 다른 모델의 ID를 통해 제공된다면 앱 소유자가 제공한 권한 적용 조회와 식별자 연결이 필요합니다. 단순히 이름이 같은 컬럼을 조합해 행 권한이나 관계를 만들어서는 안 됩니다. 없는 관계는 선언하지 말고, 오래된 앱과 호스트가 새 메타데이터를 무시할 수 있도록 기존 필드 타입을 유지하세요.