설명서

Adobe Experience Manager의 GraphQL 응답 구조 및 Markdown 출력의 차이점

Last update: Mon May 11 2026 00:00:00 GMT+0000 (Coordinated Universal Time)

AEM 6.5.23+ 또는 6.5 LTS로 업그레이드한 후 AEM 6.5.20과 같은 이전 버전과 비교하여 컨텐츠 조각에 대한 GraphQL 응답 구조와 Markdown 출력 형식 면에서 차이가 관찰됩니다. 이러한 변경 사항은 유니온 유형 쿼리에서 빈 개체를 처리하는 방법과 Markdown 필드에 공백을 렌더링하는 방법에 영향을 줍니다. 이 문제를 해결하려면 응답에서 빈 개체를 처리하고 Markdown 처리를 조정하고 일관된 지속 쿼리 인코딩을 따릅니다.

설명 description

환경

  • 제품: Adobe Experience Manager(AEM) Managed Services, AEM Sites
  • 버전: 6.5.23+/ 6.5 LTS(SP1/SP2 포함), 이전 버전 참조: 6.5.20

문제 및 증상

  • GraphQL 응답에서 다중 필드 조각 참조에 쿼리에 나열된 허용된 모델과 일치하지 않는 콘텐츠 조각이 포함된 경우 AEM 6.5.23+ 및 6.5 LTS는 해당 항목에 대해 빈 JSON 개체를 반환하지만, 이전 버전에서는 해당 개체가 완전히 생략됩니다.
  • 서식 있는 텍스트 필드의 Markdown 출력에는 단락이나 블록 사이에 공백이나 빈 줄이 추가되는 것과 같은 공백 처리 차이가 나타납니다.
  • AEM 6.5.23+ 및 6.5 LTS의 지속 쿼리 끝점은 인코딩되지 않은 특수 문자에 더 자유롭지만, 일관된 동작을 위해서는 URL 인코딩이 여전히 필요합니다.

해결 방법 resolution

이 문제를 해결하려면 다음 단계를 수행합니다.

  1. 유니온 유형 쿼리에서 반환된 빈 JSON 개체 처리:

    • GraphQL 응답을 처리할 때 클라이언트측에서 빈 개체(속성이 없는 개체)를 필터링합니다.
    • 또는 가능한 모든 참조 모델에 대한 조각을 포함하도록 지속 쿼리를 업데이트하여 각 유형에 대한 관련 데이터가 반환되도록 합니다.

  2. Markdown 공백 및 서식의 차이점:

    • 정확한 공백 또는 서식이 중요한 경우 Markdown 대신 필드의 HTML 또는 JSON 표현식을 사용하는 것이 좋습니다.
    • 필요한 경우 렌더링하기 전에 반복되는 공백 또는 빈 줄을 축소하여 사후 처리 중에 공백을 정규화합니다.

  3. 지속 쿼리 인코딩:

    • 지속 쿼리 접미사 및 변수에서 항상 세미콜론, 공백 및 콜론과 같은 특수 문자를 문서화된 패턴에 따라 URL로 인코딩하십시오.
    • 이 동작은 향후 업데이트에서 보장되지 않으므로 최신 버전에 도입된 인코딩되지 않은 문자에 대해 증가된 허용치를 사용하지 마십시오.

  4. 다음을 확인합니다.

    • 필요한 경우 클라이언트 애플리케이션은 GraphQL 응답에서 빈 개체를 올바르게 필터링합니다.
    • Markdown 출력에 표준화 단계를 적용하면 렌더링된 컨텐츠가 예상대로 표시됩니다.
    • 지속 쿼리는 인코딩 요구 사항을 준수하여 환경 간에 일관되게 작동합니다.

참고

  • AEM 6.5.23+ / 6.5 LTS 및 업데이트된 GraphQL 엔진에 도입된 의도적인 변경으로 인해 설명된 동작이 예상됩니다.
  • 의미 체계 일관성(올바른 구조 및 콘텐츠)은 유지되지만 버전 간의 바이트별 동일한 Markdown 출력은 보장되지 않습니다.
  • 내용 누락이나 잘못된 구조 등과 같은 의미론적 문제가 관찰되는 경우, 예상되는 행동 변화보다는 결함을 나타낼 수 있으므로 추가 조사가 필요할 수 있습니다.

관련 읽기

recommendation-more-help
3d58f420-19b5-47a0-a122-5c9dab55ec7f