Adobe Workfront Planning API 기본 사항

Adobe Workfront Planning API의 목표는 HTTP를 통해 작동하는 RESTful 아키텍처를 도입하여 Planning과의 통합 빌드를 간소화하는 것입니다. 이 문서에서는 사용자가 REST 및 JSON 응답에 익숙하다고 가정합니다.

전체 끝점 참조, 요청/응답 스키마 및 버전별 세부 정보는 Workfront Planning API 개발자 설명서를 참조하십시오.

인증

Workfront Planning API는 인증에 OAuth 2.0을 사용합니다. 자격 증명은 Adobe Developer Console을 통해 설정됩니다.

통합 유형에 따라 다음 두 가지 흐름이 지원됩니다.

시작하려면 Adobe Developer Console에서 프로젝트를 만들고 Workfront Planning API를 추가하여 자격 증명을 획득합니다.

자격 증명을 설정하려면 Workfront에서 OAuth2 애플리케이션을 만드십시오.

자세한 내용은 Workfront 통합을 위한 OAuth2 애플리케이션 만들기를 참조하십시오.

API 버전 관리

Planning API는 URL 경로를 통해 버전이 지정됩니다.

다음은 현재 지원되는 버전입니다.

현재 지원되는 버전에 대한 자세한 내용은 문서 Workfront Planning API 개발자 설명서를 참조하십시오.

모든 통합에서 버전을 명시적으로 타깃팅하는 것이 좋습니다.

https://{customer-domain}/maestro/api/v2/...

새로운 주요 버전이 출시되면 사용 중단 날짜가 전달될 때까지 이전 버전을 계속 사용할 수 있습니다.

API 변경 사항을 계속 알려면 Workfront 릴리스 노트를 따르십시오.

URL 구조 및 작업

개체는 고유한 URI에 HTTP 요청을 전송하여 조작됩니다. 작업은 HTTP 메서드에서 지정합니다.

전체 끝점 경로 및 요청/응답 예제는 developer.adobe.com/wf-planning의 API 참조​를 참조하십시오.

HTTP 상태 코드

Planning API는 표준 HTTP 상태 코드를 반환합니다.

오류 처리

Planning API는 일관된 형식으로 오류를 반환합니다. 각 오류 응답에는 사람이 읽을 수 있는 메시지, 기계가 읽을 수 있는 오류 코드 및 지원 에스컬레이션을 위한 요청 ID가 포함됩니다.

오류 응답 예:

json
{
  "title": "Validation failed",
  "status": 400,
  "detail": "Request validation failed. See 'errors' for details.",
  "errorCode": "VALIDATION_FAILED",
  "requestId": "req-123",
  "errors": [
    { "field": "name", "message": "must not be blank" }
  ]
}

프로그래밍 방식의 오류 처리를 수행하려면 status이(가) 아닌 errorCode을(를) 사용하십시오. 가장 구체적인 장애 분류 방법을 제공합니다.

레코드 필터링

특정 기준과 일치하는 레코드만 반환하려면 레코드 검색 요청에 filter 매개 변수를 사용하십시오. POST 요청의 경우 filter은(는) 요청 본문의 JSON 속성입니다. GET 요청의 경우 filter은(는) JSON으로 인코딩된 필터 그룹이 포함된 쿼리 매개 변수입니다. 필터는 명시적 논리 연산자가 있는 형식화된 복합 구조를 사용합니다.

json
{
  "filter": {
    "operator": "AND",
    "conditions": [
      { "fieldId": "<fieldId>", "condition": "IS", "value": "Active" },
      { "fieldId": "<fieldId>", "condition": "CONTAINS", "value": "marketing" }
    ]
  }
}

필터를 AND/OR 연산자를 사용하여 중첩하여 복합 조건을 만들 수 있습니다.

json
{
  "filter": {
    "operator": "OR",
    "conditions": [
      {
        "operator": "AND",
        "conditions": [
          { "fieldId": "<fieldId>", "condition": "BETWEEN", "value": ["2024-03-31T20:00:00.000Z", "2024-04-01T20:00:00.000Z"] },
          { "fieldId": "<fieldId>", "condition": "IS", "value": "active" }
        ]
      },
      {
        "operator": "AND",
        "conditions": [
          { "fieldId": "<fieldId>", "condition": "IS_BETWEEN", "value": ["2024-04-15T00:00:00.000Z", "2024-04-16T00:00:00.000Z"] },
          { "fieldId": "<fieldId>", "condition": "IS", "value": "planned" }
        ]
      }
    ]
  }
}

필드 유형 및 검색 수정자

필드가 있는 수정자 및 필터를 사용하여 결과에 반환될 데이터를 제어할 수 있습니다.

예를 들어 Workfront Planning API 개발자 설명서를 참조하십시오.

검색 수정자 사용

Workfront Planning은 다음 검색 수정자를 지원합니다.

필드 유형별 지원되는 필터 조건

사람 필드별 필터링

사람 필드 필터(user, created-by, updated-by, approved-by)는 Adobe IMS 사용자 ID와 Workfront 사용자 ID를 모두 허용합니다. 일반 문자열 값은 Adobe IMS 사용자 ID로 해석됩니다.

식별자 유형을 설정하여 Workfront 사용자 ID를 확인하려면 id 및 idType 매개 변수를 명시적으로 전달해야 합니다. idType에 지원되는 값은 Workfront 사용자 ID의 경우 "WF"이고, Adobe IMS 사용자 ID의 경우 "IMS"입니다.

{
  "filter": {
   "operator": "AND",
    "conditions": [
      {
        "fieldId": "<userFieldId>",
        "condition": "HAS_ANY_OF",
        "value": [
          { "id": "63e3b13000078c1795146248182d15dc", "idType": "WF" }
        ]
      }
    ]
  }
}

외부 ID별 외부 참조 필드 필터링

외부 참조 필드는 레코드를 다른 Adobe 시스템(예: Workfront 프로젝트 또는 AEM Assets)의 개체에 연결합니다. 내부적으로 Planning은 이러한 객체에 Planning 레코드 ID를 지정합니다. 원본 개체 ID로 이러한 필드를 직접 필터링하려면 필터 조건에 "matchExternalId": true을(를) 추가하십시오.

이 플래그는 referenceOptions.isExternal이(가) true인 참조 필드에만 유효하며 외부 참조 필드가 아닌 필드에는 무시됩니다. 단일 문자열 값을 확인할 수 없으면 요청이 400 Bad Request(으)로 실패합니다. 목록 값이 제공되면 해결되지 않은 항목은 변경되지 않은 상태로 전달되고 단순히 일치하지 않습니다.

{
  "filter": {
    "operator": "AND",
    "conditions": [
      {
        "fieldId": "<externalReferenceFieldId>",
        "condition": "IS_ANY_OF",
        "value": [
          "5f6a4f6e00000123456789abcdef0123",
          "/content/dam/wknd/en/adventures/bali-surf-camp"
        ],
        "matchExternalId": true
      }
    ]
  }
}

외부 연결 필드

Planning 레코드 유형은 다른 Planning 레코드 유형 대신 다른 Adobe 시스템의 객체에 레코드를 연결하는 외부 참조 필드를 호스팅할 수 있습니다.

API를 통해 외부 참조 필드를 만들려면 새 REFERENCE 필드에 대한 referenceOptions.recordTypeId을(를) 원하는 외부 레코드 종류의 ID로 설정하십시오. 서버가 대상 레코드 형식에서 referenceOptions.isExternal=true 및 연결 메타데이터(connectionName, objectName)를 자동으로 파생합니다.

지원되는 외부 오브젝트 유형에는 Workfront 오브젝트(프로젝트, 작업, 프로그램, 포트폴리오, 회사, 그룹, 팀, 사용자) 및 AEM Assets(에셋, 콘텐츠 조각)가 포함됩니다.

정렬

요청에 sort 배열을 포함하여 모든 필드별로 결과를 정렬합니다.

json
{
  "sort": [
    { "fieldId": "F6527ecb25df57c441d92b9fc", "direction": "asc" },
    { "fieldId": "F658afcbd4a0273c67c346fd5", "direction": "desc" }
  ]
}

여러 정렬 필드는 순서대로 평가됩니다. 페이지 매김할 때 항상 정렬을 적용하여 페이지 간에 일관된 순서를 유지합니다.

결과를 그룹화하려면 정렬과 함께 그룹 배열을 포함합니다.

{
  "sort": [{ "fieldId": "F001", "direction": "asc" }],
  "group": [{ "fieldId": "F002", "direction": "asc" }]
}

필드 도법

응답에서 반환되는 필드를 제한하려면 fieldIds 또는 fieldAliases 쿼리 매개 변수를 쉼표로 구분된 목록으로 사용하십시오. 이렇게 하면 응답 페이로드 크기가 줄어들며 대량 또는 지연 시간에 민감한 통합에 권장됩니다.

쪽 매기기

Planning API는 큰 데이터 세트를 관리하기 위해 페이지 매김된 응답을 지원합니다.

예를 들어 다음 요청을 사용하여 레코드 검색에서 500개의 레코드 중 두 번째 페이지를 검색합니다.

POST /v2/record-types/{recordTypeId}/records/search?page=1&size=500
{
  "sort": [{ "fieldId": "F6527ecb25df57c441d92b9fc", "direction": "asc" }],
  "filter": { "operator": "AND", "conditions": [
    { "fieldId": "<fieldId>", "condition": "IS", "value": "active" }
  ] }
}

모든 페이지가 매겨진 응답에는 더 많은 결과를 사용할 수 있는지 여부를 나타내는 구조화된 포락선이 포함됩니다. 페이지 매김할 때 항상 정렬을 적용하여 페이지 간에 일관된 순서를 유지합니다.

대량 작업

Planning API는 단일 요청에서 레코드의 벌크 만들기, 업데이트, 패치 및 삭제를 지원합니다. 끝점 경로, 요청 형식 및 작업당 레코드 제한에 대해서는 developer.adobe.com/wf-planning의 API 참조​을(를) 참조하십시오.

권한

엔티티에 대한 권한은 리소스 엔드포인트 자체와 별개로 전용 권한 API를 통해 관리됩니다. 이를 통해 현재 권한을 읽고, 공유 목록을 관리하고, 데이터 작업과 독립적으로 액세스 요청을 처리할 수 있습니다. 자세한 내용은 문서 Workfront 계획 API의 “API 참조” 섹션을 참조하십시오.

Workfront 사용자 정의 양식에서 Planning API 사용

Workfront 사용자 정의 양식의 외부 조회 필드에서 Planning API를 호출하여 Workfront 개체 내에서 직접 Planning 데이터를 표시할 수 있습니다. 자세한 내용은 사용자 지정 양식의 외부 조회 필드 예제를 참조하십시오.

관련 리소스

API 관련 추가 설명서는 다음 문서를 참조하십시오.