가상 머신용 제품 수집 API
제품 수집 API는 모든 상업용 Marketplace 제품에서 모든 기존 제출 API를 통합하는 현대화된 API입니다. API를 사용하면 파트너 센터 계정 내에서 제품 및 계획과 연결된 리소스를 만들고 게시하고 관리할 수 있습니다. 이 API는 선언적 패턴을 사용하여 요청을 제출하며, 제출에서 원하는 상태에 도달하기 위한 개별 단계를 지정하는 것이 아니라 원하는 상태가 표시됩니다.
이 문서에서는 상업용 Marketplace 제품 유형에 대한 API를 시작하는 방법에 대한 지침을 제공합니다. 제품 수집 API는 현재 SaaS, VM, 프라이빗 제품 및 컨테이너 제품 유형에 대해 지원되며 미리 보기로 제공됩니다. 본인의 제품과 관련된 지침은 제품 유형별 API 지침을 검토하세요.
Important
Azure AD(Azure Active Directory) Graph는 2023년 6월 30일부터 더 이상 사용되지 않습니다. 앞으로 Azure AD Graph에 더 이상 투자하지 않습니다. Azure AD Graph API에는 보안 관련 수정 외에 SLA 또는 유지 관리 약정이 없습니다. 새로운 기능에 대한 투자는 Microsoft Graph에서만 이루어집니다.
애플리케이션을 Microsoft Graph API로 마이그레이션하는 데 충분한 시간이 있도록 증분 단계에서 Azure AD Graph를 사용 중지합니다. 나중에 발표할 예정이며, Azure AD Graph를 사용하여 새 애플리케이션 만들기를 차단합니다.
자세한 내용은 중요: Azure AD Graph 사용 중지 및 Powershell 모듈 사용 중단을 참조 하세요.
시작
제품 수집 API는 워크로드 이름 "product-ingestion"에서 MSGraph API를 사용하여 액세스할 수 있습니다. 기준 URL은 https://graph.microsoft.com/rp/product-ingestion입니다.
제품 수집 API를 사용하려면 다음 필수 구성 요소가 있어야 합니다.
- Microsoft Entra ID 및 디렉터리에 대한 전역 관리자 권한이 있는지 확인합니다.
- Microsoft Entra 애플리케이션
- Microsoft Entra 액세스 토큰
다음 온보딩 지침에 따라 시작합니다. 이 설정이 한 번 설정되면 Microsoft Entra 액세스 토큰을 가져와서 각 API 메서드에 대한 권한 부여 헤더를 사용하여 API를 호출할 수 있습니다.
개념
시작하기 전에 몇 가지 기본 개념을 이해해야 합니다.
리소스
API는 리소스 유형을 중심으로 구성되며 각 형식은 "$schema" 속성에서 참조하는 전용 스키마 정의를 사용하여 설명됩니다. 스키마는 해당 리소스의 구성 속성으로 이루어집니다. 리소스는 주어진 제품의 다양한 측면에 대한 구성을 만들고 업데이트하는 데 필수적입니다. 리소스 종류 및 해당 스키마의 전체 목록은 리소스 API 참조를 확인하세요.
지속성 ID
지속성 ID는 모든 리소스를 고유하게 식별하는 데 사용되는 시스템 생성 전역 식별자입니다. 모든 리소스에는 연결된 "ID" 속성이 있으며, 이 속성은 리소스 유형 이름과 결합될 때 리소스의 지속성 ID를 구성합니다. 지속성 ID는 리소스를 참조하여 검색하거나 수정할 때 사용됩니다.
형식:
\<resource-type>/\<id>
예제:
{
"$schema": "https://schema.mp.microsoft.com/schema/product/2022-03-01-preview3",
"id": "product/12345678-abcd-efgh-1234-12345678901", // durable ID
"identity": {
"externalID": "ds-contoso-image-resize-demo"
},
"type": "softwareAsAService", // Product types that can be specified include azureContainer, azureVirtualMachine, softwareAsAService
"alias": "Contoso Image Resizing Service"
}
외부 ID
외부 ID는 특정 제품 또는 플랜을 참조하는 데 사용할 수 있는 또 다른 고유 식별자입니다. 지속성 ID를 사용하는 대신 이러한 리소스를 참조하는 다른 방법입니다. 제품의 외부 ID는 "offerID"로 변환되고 계획의 외부 ID는 "ID" 속성 아래에 생성 시 정의된 대로 "planID"로 변환됩니다.
예시:
{
"$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2",
"id": "plan/12345678-abcd-efgh-1234-12345678901/4e0bfefa-b993-4b79-a426-871c3bf236a5",
"identity": {
"externalID": "gold-annual"
},
"azureRegions": [
"azureGlobal"
],
"alias": "Gold - Annual payment",
"product": "product/12345678-abcd-efgh-1234-12345678901",
}
API 메서드
기존 리소스 쿼리, 구성 업데이트 및 요청 상태 확인과 같은 다양한 작업을 수행하는 데 사용할 수 있는 네 가지 관리 API가 있습니다.
참고 항목
모든 요청을 수행하려면 응답의 일부로 원하는 스키마 버전($version 쿼리 매개 변수)을 설정해야 합니다.
| API 형식 | 설명 | HTTP 메서드 및 경로 |
|---|---|---|
| 쿼리 | 다음을 사용하여 기존 리소스를 검색합니다. -메서드 1: "resource-tree" 리소스 종류 -메서드 2: durable-id -메서드 3: 쿼리 문자열 매개 변수 |
-메서드 1: GET resource-tree/<product-durableID>-메서드 2: GET <resource-durableID>-메서드 3: GET <resourceType>?<query parameters> |
| 제출 구성 | 요청을 제출하여 하나 이상의 리소스를 만들거나 업데이트합니다. 처리가 성공하면 요청 상태를 검색하는 데 사용할 수 있는 jobID가 반환됩니다. 이 API 유형을 사용하여 초안 상태를 업데이트하고 변경 내용을 게시하고, 개인 대상 그룹을 동기화하고, 리소스 수명 주기 상태를 수정할 수 있습니다. | POST configure |
| 상태 구성 | jobID를 통해 보류 중인 요청의 상태를 검색합니다. | GET configure/<jobID>/status |
| 상태 세부 정보 구성 | jobID를 통해 업데이트된 리소스를 포함하여 완료된 요청에 대한 자세한 요약을 검색합니다. | GET configure/<jobID> |
| 구성 취소 | 지정된 구성 작업을 취소합니다. | POST configure/<jobID>/cancel |
일반적인 워크플로
기존 리소스를 업데이트하는 일반적인 워크플로는 다음과 같습니다.
- 기존 리소스 구성 검색(API 유형: 리소스 트리를 통한 쿼리)*
- 필요한 업데이트를 수행하고 구성 요청을 제출합니다(API 유형: 제출 구성).
- 요청 상태 확인(API 유형: 상태 구성 및 상태 세부 정보 구성)
* 새 리소스를 만들 때 이 워크플로를 똑같이 적용할 수 있지만, 리소스를 검색(1단계)하는 대신 리소스 API 참조 테이블을 사용하여 만들고 있는 리소스 종류에 현재 스키마를 사용하고 있는지 확인합니다.
요약하자면, 이 이미지는 새 리소스를 만들거나 기존 리소스를 수정하는지에 관계없이 구성 요청을 제출하는 데 사용되는 일반적인 호출 패턴을 보여 줍니다.
참고 항목
제품 유형별 API 지침을 참조하여 관리 중인 제품 유형과 관련된 추가 필수 구성 요소를 검토해야 합니다.
기존 리소스 구성 검색
기존 리소스를 업데이트하기 전에 먼저 리소스를 검색하여 최신 구성이 있는지 확인해야 합니다. GET 호출을 통해 리소스를 검색하는 여러 가지 방법이 있습니다. API 호출 한 번으로 특정 제품 내의 모든 리소스를 검색하려면 아래에 자세히 설명된 메서드 1을 참조하세요.
메서드 1: resource-tree
Schema: https://``schema.mp.microsoft.com``/schema/resource-tree/2022-03-01-preview2
GET resource-tree/<product-durableID>?$version=<schema-version>
제품의 지속성 ID와 함께 "리소스 트리" 리소스 유형을 사용하여 특정 제품 내의 모든 리소스 구성을 검색할 수 있습니다.
사용 가능한 최신 스키마 버전은 리소스마다 다를 수 있습니다. 리소스 트리 요청을 수행할 때 지정된 스키마 버전은 제품의 각 리소스에 대해 반환되는 버전을 결정합니다. 지정된 버전은 동일하거나 낮은 버전의 모든 리소스에 사용할 수 있는 최신 스키마 버전을 반환한다는 측면에서 "max" 버전 제한으로 사용됩니다. 예를 들어 사용 가능한 최신 계획 목록 버전이 "2022-03-01-preview3"인 경우 resource-tree GET 요청에서 "2022-03-01-preview5"를 지정하려는 경우 응답이 이 버전에 표시됩니다. 그러나 리소스 트리 버전으로 "2022-03-01-preview2"를 요청하는 경우 사용 가능한 최신 버전이 "2022-03-01-preview3"인 경우에도 리소스를 나열하는 "2022-03-01-preview2" 계획 목록이 반환됩니다. 각 리소스의 사용 가능한 최신 버전을 사용하여 새로 지원되는 기능으로 업데이트된 스키마를 사용하는 것이 좋습니다.
참고 항목
제품의 지속성 ID를 모르는 경우 제품의 외부 ID 를 사용하여 실행 GET product?externalID=<product-externalID>&$version=<product-schema-version>하여 제품 리소스를 검색할 수 있습니다. 이 요청은 아래의 메서드 3에 자세히 설명된 쿼리 문자열 매개 변수를 활용합니다. 응답에는 향후 요청에 사용할 수 있는 제품의 지속성 ID가 포함됩니다.
기본적으로 "resource-tree"를 사용하여 GET 호출을 실행하면 리소스의 초안 버전을 다시 가져옵니다. 그러나 "targetType" 쿼리 매개 변수를 전달하여 원하는 대상을 지정하여 "미리 보기" 또는 "라이브" 데이터를 검색할 수 있습니다. 다음 예제에서 GET 호출은 "12345678-abcd-efgh-1234-12345678901" 제품 아래의 모든 리소스에 대한 미리 보기 환경의 구성을 반환합니다.
샘플 GET 호출:
GET https://graph.microsoft.com/rp/product-ingestion/resource-tree/product/12345678-abcd-efgh-1234-12345678901?targetType="preview"&$version=2022-03-01-preview5
샘플 응답:
{
"$schema": "https://schema.mp.microsoft.com/schema/resource-tree/2022-03-01-preview2",
"root": "product/12345678-abcd-efgh-1234-12345678901",
"target": {
"targetType": "preview"
},
"resources": [
{
"$schema": "https://schema.mp.microsoft.com/schema/product/2022-03-01-preview3",
"id": "product/12345678-abcd-efgh-1234-12345678901",
"identity": {
"externalID": "ds-contoso-image-resize-demo"
},
"type": "softwareAsAService",
"alias": "Contoso Image Resizing Service"
},
{
"$schema": "https://schema.mp.microsoft.com/schema/property/2022-03-01-preview3",
"id": "property/12345678-abcd-efgh-1234-12345678901/public/main",
"product": "product/12345678-abcd-efgh-1234-12345678901",
"kind": "azureSaaS",
"termsConditions": "false",
"categories": {
"developer-tools-saas": [
"devService"
]
}
},
{
"$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2",
"id": "plan/12345678-abcd-efgh-1234-12345678901/4e0bfefa-b993-4b79-a426-871c3bf236a5",
"product": "product/071b135e-9faf-4ff7-b113-a3f25bb0f468",
...
},
// The response would include all existing resources within this product.
{
...
}]
}
메서드 2: 지속성 ID
GET <resource-durableID>?$version=<schema-version>
지속성 ID를 사용하여 특정 리소스를 검색합니다. 리소스가 만들어지면 지속성 ID는 항상 동일하게 유지되며 GET 메서드를 호출하여 해당 리소스의 최신 초안 변경 내용을 검색하는 데 사용할 수 있습니다. 예를 들어 다음 요청은 "2022-03-01-preview3" 스키마 버전을 사용하여 이 특정 제품의 초안 구성을 반환합니다.
GET product/12345678-abcd-efgh-1234-12345678901?$version=2022-03-01-preview3
Important
이 메서드는 초안 구성을 검색하는 데만 사용됩니다. 미리 보기 또는 라이브 데이터를 검색하려면 위에서 설명한 대로 "resource-tree" 메서드를 사용합니다.
리소스의 지속성 ID를 찾으려면 다음 중 하나를 수행할 수 있습니다.
- "resource-tree" 메서드를 사용하여 각 지속성 ID와 함께 제품 내의 모든 리소스를 가져오거나
- 요청의 일부로 생성되거나 업데이트된 모든 리소스에 대한 지속성 ID를 포함하는 완료된 리소스 구성 요청의 세부 정보를 검색합니다.
"ID" 속성은 해당 리소스의 durable-id입니다.
메서드 3: 쿼리 문자열 매개 변수
GET <resourceType>?<query parameters>&$version=<schema-version>
이 메서드는 특정 계정과 연결된 특정 리소스 종류를 쿼리하는 데 사용됩니다. 예를 들어 단일 GET 호출을 사용하여 특정 제품 유형의 모든 제품을 검색할 수 있습니다. 쿼리 문자열 매개 변수는 제품, 계획 또는 제출과 관련된 세부 정보를 쿼리하는 데 사용됩니다.
다음 표에는 지원되는 각 리소스 종류에 대해 지원되는 쿼리 매개 변수가 정리되어 있습니다. 모든 리소스 종류가 각 쿼리 매개 변수를 지원하는 것은 아닙니다. 현재 지원되는 쿼리 문자열의 전체 목록은 이 표를 참조하세요.
| 리소스 종류 | 매개 변수 | 쿼리 문자열 예제 |
|---|---|---|
| 계획 | 제품*externalID $maxpagesize continuationToken$version * |
GET plan?product=<product-durableID>&$version=<schema-version>GET plan?product=<product-durableID>&externalID=<plan-externalID>&$version=<schema-version>GET plan?product=<product-durableID>&$maxpagesize=<#>&$version=<schema-version>GET plan?product=<product-durableID>&continuationToken=<token>&$version=<schema-version> |
| product | externalID type $maxpagesize continuationToken$version * |
GET product?externalID=<product-externalID>&$version=<schema-version>GET product?type=<product-type>&$version=<schema-version>GET product?$maxpagesize=<#>&$version=<schema-version>GET product?continuationToken=<token>&$version=<schema-version> |
| submission | targetType $maxpagesize continuationToken$version * |
GET submission/<product-durableID>?targetType=<environment>&$version=<schema-version>GET submission/<product-id>?$maxpagesize=<#>&continuationToken=<token>&$version=<schema-version> |
| resource-tree | targetType$version* |
GET resource-tree/<product-durableID>?targetType=<environment>&$version=<schema-version> |
* 제품 및 $version 매개 변수는 항상 필요합니다.
지원되는 각 쿼리 매개 변수의 기능은 다음과 같습니다.
- product – "plan" 리소스 유형의 컨텍스트에서 "product" 매개 변수를 전달할 때 해당 특정 제품 내의 모든 계획을 반환합니다.
- externalID – 제품 또는 계획의 컨텍스트에서 "externalID" 매개 변수를 전달하는 경우 해당 제품 또는 계획의 구성을 반환합니다. "resource-tree" 메서드와 달리 이 쿼리 문자열 매개 변수는 해당 리소스의 세부 정보만 반환하고 그 안에 있는 모든 리소스는 반환하지 않습니다.
- type – "product" 리소스 유형의 컨텍스트에서 "type" 매개 변수를 전달할 때 계정에 연결된 해당 유형의 모든 제품을 반환합니다. 예를 들어 "type=softwareAsAService"를 지정하면 모든 SaaS 제품이 반환됩니다.
- targetType – 사용되는 리소스 유형의 컨텍스트에서 특정 환경의 데이터를 반환합니다. 지원되는 "targetType" 값은 "초안", "미리 보기" 또는 "라이브"입니다.
- $maxpagesize – 최대 페이지 크기를 양의 정수 형식으로 지정하면 이 매개 변수는 이전 제출을 쿼리할 때 검색 결과를 제한하는 데 사용됩니다.
- continuationToken – 이 매개 변수를 "$maxpagesize" 매개 변수와 함께 사용하여 검색에서 사용할 수 있는 다른 결과 집합을 쿼리할 수 있습니다. "continuationToken" 값은 이전 페이지의 응답에서 제공됩니다.
- $version – 모든 호출에 필요한 매개 변수이며, 요청의 응답에 원하는 스키마 버전을 지정합니다. 사용 가능한 최신 스키마 버전은 각 리소스에 대해 다를 수 있으며 지정된 버전은 "max" 버전 제한으로 사용됩니다. 시스템은 사용 가능한 경우 정확한 스키마 버전 또는 요청된 버전보다 오래된 가장 가까운 버전을 반환합니다. 이렇게 하면 최신 스키마 변경 내용이 있더라도 코드 작동을 유지할 수 있지만 최신 기능을 활용하려면 사용 가능한 최신 버전의 각 스키마를 사용하는 것이 좋습니다.
제출 쿼리
GET submission/<product-durableID>를 수행하여 기존 제품 제출을 검색할 수 있습니다. 기본적으로 초안 참조를 포함하여 모든 활성 제출을 다시 가져올 수 있지만 "targetType" 쿼리 매개 변수((GET submission/<product-durableID>?targetType=<environment>&$version=<version>)를 사용하여 특정 환경을 추가로 쿼리할 수 있습니다.
Important
"미리 보기" 제출이 "라이브"로 푸시되면 미리 보기 제출이 이전 "라이브" 제출을 대체합니다. 이 경우 데이터는 이제 새 제출이 "미리 보기"에 게시될 때까지 "미리 보기" 및 "라이브" 환경을 모두 나타냅니다.
샘플 요청:
GET https://graph.microsoft.com/rp/product-ingestion/submission/12345678-abcd-efgh-1234-12345678901?$version=2022-03-01-preview2
샘플 응답:
이 예제에서는 제품 ID "12345678-abcd-efgh-1234-12345678901"에 연결된 활성 제출에 대한 GET 요청을 보여 줍니다. 활성 "라이브" 제출(제출/12345678-abcd-efgh-12334-12345678901/1152921515689847470)은 먼저 미리 보기로 게시된 후 나중에 라이브로 게시되었습니다. 이 제출이 2022년 1월 25일에 라이브로 푸시되었을 때 새 미리 보기 제출(제출/12345678-abcd-efgh-12345678901/1152921515689848683)이 2022년 2월 4일에 생성될 때까지 미리 보기와 라이브를 모두 나타냅니다.
{
"value": [
{
"$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2",
"id": "submission/12345678-abcd-efgh-1234-12345688901/0",
"product": "product/12345678-abcd-efgh-1234-12345678901",
"target": {
"targetType": "draft"
}
},
{
"$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2",
"id": "submission/12345678-abcd-efgh-1234-12345678901/1152921515689847470",
"product": "product/12345678-abcd-efgh-1234-12345678901",
"target": {
"targetType": "live"
},
"status": "completed",
"result": "succeeded",
"created": "2022-01-25T07:13:06.4408032Z"
},
{
"$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2",
"id": "submission/12345678-abcd-efgh-1234-12345678901/1152921515689848683",
"product": "product/12345678-abcd-efgh-1234-12345678901",
"target": {
"targetType": "preview"
},
"status": "completed",
"result": "succeeded",
"created": "2022-02-04T20:07:22.4220588Z"
}
]
}
새 제품 및 리소스 만들기
단일 구성 요청의 일부로 새 제품을 비롯한 새 리소스를 만들 수 있습니다. 리소스 API 참조 테이블을 사용하여 만들려는 리소스 종류에 대한 스키마를 검색할 수 있습니다. 이렇게 하면 최신 스키마를 사용하게 되므로 리소스를 만드는 데 필요한 모든 속성이 구성됩니다.
새 제품을 만드는 경우 요구 사항은 제품 유형에 따라 다릅니다. 따라서 다른 리소스를 제공해야 합니다. 해당 제품 유형에 대한 해당 상업용 Marketplace 설명서를 참조하여 요청에서 기본 요구 사항을 구성하고 있는지 확인할 수 있습니다. 또는 제품 리소스만 사용하여 구성 요청을 만들 수 있습니다. 제품을 만든 후 구성 상태 세부 정보 API를 호출하여 생성된 제품 리소스를 검색하고 지속성 ID를 찾아 리소스 트리 쿼리 API를 호출합니다. 응답은 사용자가 만든 제품 유형에 대해 지원되는 해당 리소스를 반환합니다.
마찬가지로 기존 제품 내에서 새 리소스를 만들려면 해당 특정 리소스 유형의 최신 스키마도 검색해야 합니다. 리소스 종속성을 검토하여 구성 요청의 일부로 종속 리소스를 제공해야 합니다.
스키마를 사용하여 리소스를 구성한 후 구성 요청을 만드는 방법을 알아봅니다.
기존 제품 및 리소스 수정
구성 페이로드를 사용하여 업데이트를 제출할 수 있습니다. 이 페이로드는 하나 이상의 리소스 종류로 구성되며 "$schema" 속성은 참조되는 리소스 종류를 나타냅니다.
팁
최신 구성을 활용할 수 있도록, 업데이트를 게시하기 전에 기존 리소스를 검색하는 것이 좋습니다.
리소스를 수정한 후 구성 요청을 만드는 방법을 알아봅니다.
구성 요청
동일한 페이로드에서 편집하고 게시할 수 있습니다. 구성 요청을 제출하려면 구성 API의 HTTP POST 메서드를 사용합니다. 구성 페이로드는 원하는 변경 내용을 나타내는 리소스 배열로 구성됩니다. 모든 편집 내용은 초안 변경 내용을 게시하기 위해 제출 리소스를 명시적으로 제출할 때까지 초안 버전에만 영향을 줍니다. 미리 보기 또는 라이브로 게시할 때 제출 리소스를 포함하고 대상 환경을 지정합니다. 요청을 제출하기 전에 리소스를 참조하고 해당 종속성을 이해하는 방법을 알아야 합니다.
Schema:https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2
구성 요청을 제출하면 요청의 진행률 및 결과를 추적하는 데 사용할 수 있는 jobID를 사용하여 구성 상태 개체를 다시 가져옵니다.
Schema: <https://``schema.mp.microsoft.com``/schema/configure-status/2022-03-01-preview2>
리소스 참조 및 종속성
참조
구성 요청에서 기존 리소스를 참조하려면 리소스의 지속성 ID와 함께 리소스의 "$schema" 형식을 제공합니다. 제품 및 플랜의 경우 외부 ID를 통해 이러한 리소스를 참조할 수도 있습니다.
지속성 ID는 "ID" 속성에서 찾을 수 있습니다. 예를 들어 다른 리소스에서 참조하려는 제품 리소스인 경우
{
"$schema": "https://schema.mp.microsoft.com/schema/product/2022-03-01-preview3",
"id": "product/12345678-abcd-efgh-1234-12345678901",
"identity": {
"externalID": "ds-contoso-image-resize-demo"
},
"type": "softwareAsAService",
"alias": "Contoso Image Resizing Service"
}
지속성 ID는 "product/071b135e-9faf-4ff7-b113-a3f25bb0f468"입니다.
그런 다음 다음과 같이 "product" 리소스 스키마 속성에서 설정하여 아래 목록 리소스 예제에서 지속성 ID를 사용할 수 있습니다.
{
"$schema": "https://schema.mp.microsoft.com/schema/listing/2022-03-01-preview5",
"product": "product/071b135e-9faf-4ff7-b113-a3f25bb0f468", // product durable ID
...
}
제품 및 계획 리소스의 외부 ID는 "ID" 속성 내에 정의됩니다.
{
"$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2",
"alias": "Gold - Annual payment",
"identity": {"externalID": "gold-annual"},
"product": "product/071b135e-9faf-4ff7-b113-a3f25bb0f468",
...
}
계획 외부 ID "gold-annual"는 다음 형식으로 다른 후속 리소스에서 참조할 수 있습니다.
{
"$schema": "https://schema.mp.microsoft.com/schema/plan-listing/2022-03-01-preview5",
"product": "product/071b135e-9faf-4ff7-b113-a3f25bb0f468"}
"plan": {"externalID": "gold-annual"}
...
}
샘플 요청:
이 예제에서는 구성 페이로드를 사용하여 외부 ID가 "ds-contoso-image-resize-demo"인 새 SaaS 제품을 만듭니다. 이 제품을 만들 때 나중에 지속성 ID 또는 외부 ID를 사용하여 이 제품을 참조할 수 있습니다.
POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2
{
"$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
"resources": [
{
"$schema": "https://schema.mp.microsoft.com/schema/product/2022-03-01-preview3",
"identity": {
"externalID": "ds-contoso-image-resize-demo"
},
"type": "softwareAsAService",
"alias": " Contoso Image Resizing Service"
}
]
}
샘플 응답:
{
"$schema": "https://schema.mp.microsoft.com/schema/configure-status/2022-03-01-preview2",
"jobID": "071b135e-9faf-4ff7-b113-a3f25bb0f468",
"jobStatus": "running",
"jobResult": "pending",
"jobStart": "2022-08-18T16:35:56.5917185Z",
"jobEnd": "0001-01-01T00:00:00",
"errors": []
}
그런 다음 상태 구성 API를 통해 jobID를 사용하여 요청 상태를 확인할 수 있습니다.
종속성
어떤 리소스는 사전 요구 사항으로 또 다른 리소스를 만들어야 하는 종속성이 있습니다. 이 경우 동일한 페이로드 내의 "resourceName" 속성을 사용하여 동일한 요청에서 둘 다 만들 때 계획 리소스에서 제품 리소스의 종속성을 나타냅니다.
"resourceName"은 수행 중인 구성 요청의 일부로 각 리소스를 식별하는 데만 사용됩니다. 값은 리소스 데이터의 일부가 아니며 저장되지도 않고 고객에게도 노출되지 않습니다. 또한 구성 요청의 일부로 오류가 있는 경우 "resourceName"을 사용하여 오류가 속한 리소스를 호출합니다.
샘플 요청:
이 예제에서는 계획 전에 제품을 만들어야 하므로 "resourceName" 속성이 사용됩니다. 생성되는 제품인 "myNewProduct"는 "resourceName"에 사용되고 종속 계획 리소스 내에서 참조되는 값입니다.
POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2
{
"$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
"resources": [
{
"$schema": "https://schema.mp.microsoft.com/schema/product/2022-03-01-preview3",
"resourceName": "myNewProduct",
"alias": "Contoso Image Resizing Service",
...
},
{
"$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2",
"alias": " Gold - Annual payment",
"product": {"resourceName": "myNewProduct"}
...
},
}]
}
제출 리소스
"미리 보기" 또는 "라이브"에 게시하는 경우 다음을 포함하는 제출 리소스를 요청에 포함합니다.
- 지속성 ID 또는 외부 ID에서 참조하는 대로 업데이트되는 제품을 나타내는 "product" 속성입니다.
- 대상 환경을 나타내는 "targetType" 속성
라이브로 게시할 때 게시하려는 미리 보기 제출의 "ID"는 다음과 같습니다.
{
"$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2",
"id": "submission/12345678-abcd-efgh-1234-12345678901/11521167929065",
"product": "product/12345678-abcd-efgh-1234-12345678901",
"target": { "targetType": "live" }
}
참고 항목
제출 리소스를 포함하지 않으면 초안 상태만 변경됩니다.
미리 보기에 게시
상용 제품 유형은 미리 보기 환경을 지원하며, 각 업데이트는 라이브로 전환하기 전에 미리 보기에 먼저 게시되어야 합니다. 라이브에 바로 게시할 수 없습니다.
Important
플랜의 비공개 대상 그룹을 변경하는 경우는 예외입니다. 특히 개인 대상 그룹에 업데이트를 동기화할 때 이러한 변경 내용은 미리 보기와 라이브 모두에 동시에 전파됩니다.
미리 보기 환경에 리소스를 게시하는 두 가지 방법이 있습니다. 미리 보기 제출을 변경해야 하는 경우 다른 GET 요청을 수행하고, 필요한 변경을 수행하고, 변경 내용을 다시 푸시합니다. 초기 변경 내용을 사용하여 먼저 라이브로 전환할 필요가 없습니다.
방법 1: 모든 초안 리소스 게시
변경한 모든 초안을 게시하려는 경우 미리 보기 환경을 "targetType"으로 설정하는 제출 리소스를 사용하여 구성 요청을 보낼 수 있습니다. 아래 예제와 같이 이 메서드가 대상 환경에 대한 모든 변경 내용을 게시하므로 업데이트가 필요한 모든 리소스를 명시적으로 제공할 필요는 없습니다. 이 경우 미리 보기입니다. 구성 API 엔드포인트 및 제출 리소스만 제공하면 됩니다.
샘플 요청:
POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2
{
"$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
"resources": [
{
// Below is the submission resource to publish to preview
"$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2",
"product": "product/12345678-abcd-efgh-1234-12345678901", // This is the product durable ID
"target": { "targetType": "preview" }
}
]
}
방법 2: 특정 초안 리소스 게시(모듈식 게시라고도 함)
또는 아직 다양한 리소스의 모든 초안 변경 내용을 게시할 준비가 되지 않은 경우 제출 리소스와 함께 게시할 리소스를 제공하여 모듈형 게시를 트리거합니다. 이 방법을 사용하면 방법 1에서 하는 것처럼 대량 업데이트의 일부가 아니라 리소스를 변경하는 동시에 게시할 수도 있습니다. 모듈식 게시의 경우 제품 유형에 해당하는 제품 수준 세부 정보(예: 목록, 가용성, 패키지, 재판매인)를 제외한 모든 리소스가 필요합니다.
샘플 요청:
이 예제에서는 제품의 리소스가 모듈형 게시의 일부로 명시적으로 제공되고 그 후 제출 리소스가 제공됩니다.
POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2
{
"$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
"resources": [
{
"$schema": "https://schema.mp.microsoft.com/schema/product/2022-03-01-preview2",
"id": "product/12345678-abcd-efgh-1234-12345678901",
...
},
{
"$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2",
...
},
// additional resources
{
...
},
// Below is the submission resource to publish to preview
{
"$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2",
"product": "product/12345678-abcd-efgh-1234-12345678901", // This is the product durable ID
"target": { "targetType": "preview" }
}
]
}
라이브에 게시
미리 보기의 변경 내용을 테스트하고 확인한 후에는 미리 보기 제출의 "ID"와 "targetType"이 "라이브"로 설정된 구성 요청을 전송하여 변경 내용을 라이브로 푸시할 수 있습니다. 구성 요청 내에 통합할 미리 보기 제출의 "ID"를 찾으려면 제출 쿼리를 참조 하세요.
Important
미리 보기에 게시할 때와는 다르게, 라이브에 게시할 때에는 모듈형 게시를 수행하는 옵션이 없습니다. 따라서 변경 내용이 라이브로 전환되기 전에 미리 보기 제출을 확인했는지 확인해야 합니다.
샘플 요청:
POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2
{
"$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
"resources": [
// Below is the submission resource, including the preview submission id, to publish to live.
{
"$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2",
"id": "submission/12345678-abcd-efgh-1234-12345678901/11521167929065",
"product": "product/12345678-abcd-efgh-1234-12345678901", // This is the product durable ID
"target": { "targetType": "live" }
}
]
}
요청 상태 확인
구성 요청에 포함된 리소스 또는 변경 내용에 관계없이 성공적으로 처리된 후 요청을 제출한 직후 응답에서 구성 상태 개체를 다시 받게 됩니다. "jobID"는 나중에 요청 상태를 확인하는 데 사용할 수 있으므로 중요합니다.
Schema: <https://schema.mp.microsoft.com/schema/configure-status/2022-03-01-preview2>
제출된 요청에 대한 샘플 응답:
{
"$schema": "https://schema.mp.microsoft.com/schema/configure-status/2022-03-01-preview2",
"jobID": "d4261631-c583-4949-a612-5150882632e9",
"jobStatus": "notStarted",
"jobResult": "pending",
"jobStart": "2022-03-01T13:32:43.123456Z",
"jobEnd": "0001-01-01T00:00:00",
"errors": []
}
보류 중인 요청의 상태
다음 호출을 사용하고 요청의 "jobID"를 입력하여 작업이 완료될 때까지 상태를 검색할 수 있습니다. 요청에 문제가 있는 경우 개체에 오류 목록이 포함될 수도 있습니다.
GET https://graph.microsoft.com/rp/product-ingestion/configure/<jobID>/status?$version=2022-03-01-preview2
완료 시간은 요청의 복잡성에 따라 달라질 수 있습니다.
완료된 요청의 요약 정보
구성 요청 작업이 성공적으로 또는 실패하면 "jobID"를 사용하여 만들거나 업데이트한 리소스 목록을 가져올 수 있습니다.
참고 항목
작업이 완료되기 전에 이 호출을 수행하면 호출이 실패합니다. 또한 성공적으로 완료된 리소스만 반환하거나 취소 시 취소 전에 완료된 리소스만 반환합니다.
Schema: <https://schema.mp.microsoft.com/schema/configure-detail/2022-03-01-preview2>
GET https://graph.microsoft.com/rp/product-ingestion/configure/<jobID>?$version=2022-03-01-preview2
샘플 요청:
아래 예제에서 GET 요청은 새 SaaS 제품을 만든 이전 예제에서 사용된 구성 요청의 요약 세부 정보를 검색하는 데 사용됩니다. 응답은 지속성 ID와 함께 생성된 제품 리소스를 포함하는 리소스 배열이 있는 구성 세부 개체입니다.
GET https://graph.microsoft.com/rp/product-ingestion/configure/071b135e-9faf-4ff7-b113-a3f25bb0f468?$version=2022-03-01-preview2
샘플 응답:
{
"$schema": "https://schema.mp.microsoft.com/schema/configure-detail/2022-03-01-preview2",
"resources": [
{
"$schema": "https://schema.mp.microsoft.com/schema/product/2022-03-01-preview2",
"id": "product/12345678-abcd-efgh-1234-12345678901",
"identity": {
"externalID": "ds-contoso-image-resize-demo "
},
"type": "softwareAsAService",
"alias": "Contoso Image Resizing Service"
}
]
}
구성 요청 취소
작업이 완료되기 전에 필요한 경우 취소를 시도할 수 있습니다. "미리 보기" 또는 "라이브"에 게시하는 것과 같은 장기 실행 요청의 경우 작업이 완전히 처리되는 데 충분한 경우 취소 요청이 거부될 수 있습니다.
작업을 취소하려면 취소 엔드포인트에 POST를 호출하고 취소하려는 요청의 작업 ID를 제공합니다.
POST https://graph.microsoft.com/rp/product-ingestion/configure<jobID>/cancel?$version=2022-03-01-preview2
샘플 요청:
POST <https://graph.microsoft.com/rp/product-ingestion/configure/d4261631-c583-4949-a612-5150882632e9/cancel?$version=2022-03-01-preview2>
성공적인 취소 요청에 대한 샘플 응답:
{
"$schema": "https://schema.mp.microsoft.com/schema/configure-status/2022-03-01-preview2",
"jobID": "d4261631-c583-4949-a612-5150882632e9",
"jobStatus": "completed",
"jobResult": "cancelled",
"jobStart": "2022-03-01-T13:32:43.123456Z",
"jobEnd": "2022-03-01T17:34:21.5225132Z",
"errors": []
}
취소가 허용되지 않는 경우 샘플 응답: HTTP Status code: 400
콘텐츠:
{
"error": {
"code": "badRequest",
"message": "Cannot cancel job, job has already completed.",
"details": []
}
}
Important
취소는 아직 처리되지 않은 리소스에만 적용됩니다. 일부 리소스는 이미 처리를 완료했으며 요청 취소에도 불구하고 최신 구성 업데이트를 반영합니다.
취소 후 구성 요청 의 요약을 가져와서 취소 전에 이미 처리된 리소스(있는 경우)를 확인할 수 있습니다.
비공개 대상 그룹 동기화
라이브 제품의 경우 초안, 미리 보기 및 라이브 환경에서 개인 대상 그룹에 대한 업데이트는 게시 없이 동시에 수행할 수 있습니다. 특정 계획에서 추가하거나 제거할 대상 그룹을 지정하여 "price-and-availability-update-private-audiences" 리소스를 사용하여 개인 대상 그룹을 동기화할 수 있습니다. 이렇게 하면 초안, 미리 보기 및 라이브 환경이 동기화되어 개인 대상 그룹 값이 동일합니다. 비공개 대상 그룹을 동기화할 때 제출 리소스를 제공할 필요가 없습니다.
초안 대상 그룹을 편집하려면 "가격 및 가용성 계획" 리소스 및 "privateAudiences" 속성을 사용합니다. 미리 보기 및 라이브로 설정되는 값에 대한 일반 게시 흐름을 거쳐야 합니다.
Important
제품이 비공개 대상 그룹을 구성하는 데 여러 식별자 유형을 지원하는 경우(예: 테넌트 ID와 구독 ID 지원) 새로운 식별자 유형을 처음으로 제공할 때에는 전체 게시를 수행해야 합니다. 이 경우 개인 대상 그룹을 동기화할 수 없습니다. 비공개 대상 그룹 구성을 동기화하는 요청 샘플:
POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2
{
"$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
"resources": [
{
"$schema": "https://schema.mp.microsoft.com/schema/price-and-availability-update-private-audiences/2022-03-01-preview2",
"product": "product/12345678-abcd-efgh-1234-12345678901", // product durable ID
"plan": "plan/12345678-abcd-efgh-1234-12345678901/7e70b11f-809e-4c45-ae2f-1fb3ceaca33b", //plan durable ID
"privateAudiences":
{
"add ":
[
{
"type": "tenant",
"id": "4c2bdcdc-f10e-468d-8a2a-0832e089215b",
"label": "test 1"
}
],
"remove ":
[
{
"type": "subscription",
"id": "412c45bf-c99a-4e96-b683-77b0aa2dd09e",
"label": "test 2"
}
]
}
}
]
}
잠재 고객 관리 구성
고객이 관심을 표시하거나 제품을 배포할 때 고객 연락처 정보를 받을 수 있도록 CRM(고객 관계 관리) 시스템을 상업용 Marketplace 제품에 연결합니다. 제품을 만드는 동안 또는 이후에 언제든지 이 연결을 수정할 수 있습니다. 자세한 내용은 고객 잠재 고객 가져오기를 참조하세요.
잠재 고객 관리를 구성하는 샘플 요청:
POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2
{
"$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
"resources": [
{
"$schema": "https://schema.mp.microsoft.com/schema/customer-leads/2022-03-01-preview3",
"id": "customer-leads/a0c6484f-b4fb-4129-ac6b-35f2b5628089",
"product": "product/a0c6484f-b4fb-4129-ac6b-35f2b5628089",
"leadDestination": "httpsEndpoint",
"httpsEndpointLeadConfiguration": {
"httpsEndpointUrl": "https://www.your-crm.com/triggers/invoke"
}
}
]
}
리소스 수명 주기 상태
리소스의 수명 주기 상태에 매핑을 수행할 수 있는 다양한 작업이 있습니다. 모든 리소스가 수명 주기 상태를 갖고 있는 것은 아니며, 모든 리소스가 모든 수명 주기 상태를 지원하는 것도 아닙니다. 리소스에 수명 주기 상태와 지원되는 값이 있는지 확인하려면 리소스 스키마에서 "lifecycleState" 속성이 있는지 확인할 수 있습니다. 지원되는 다양한 수명 주기 상태가 아래에 자세히 설명되어 있습니다.
삭제됨
"lifecycleState" 속성을 "deleted"로 업데이트하여 특정 리소스를 삭제할 수 있습니다. 이전에 게시되지 않은 초안 리소스만 삭제할 수 있습니다. 이 작업은 취소할 수 없습니다.
샘플 요청:
아래 예제에서는 "기본" 초안 계획이 삭제됩니다.
POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2
{
"$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
"resources": [
{
"$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2",
"id": "plan/9f8af57f-ab07-461b-8404-50e10e5e80fb/7e70b11f-809e-4c45-ae2f-1fb3ceaca33b",
"product": "product/9f8af57f-ab07-461b-8404-50e10e5e80fb",
"identity": { "externalID": "basic" },
"alias": "basic plan"
"lifecycleState": "deleted"
}
]
}
더 이상 사용되지 않음
사용 중단하면 상업용 Marketplace에서 리소스가 제거됩니다. 사용 중단하려면 해당 속성을 지원하는 리소스에서 "lifecycleState" 속성을 "사용되지 않음"으로 설정합니다. 다양한 수준의 사용 중단이 있습니다. 모든 제품 유형은 전체 제품 및 제품 내 개별 플랜의 사용 중단을 지원합니다. 나중에 사용되지 않는 리소스를 복원하려면 "generallyAvailable" 수명 주기 상태를 참조하세요.
제품 사용 중단에 대한 샘플 요청:
아래 예제에서는 제품의 라이브 제출이 사용되지 않음으로 설정됩니다. 이 변경 내용이 적용되면 라이브로 자동으로 게시되어 적용됩니다.
POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2
{
"$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
"resources": [
{
"$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2 ",
"id": "submission/9f8af57f-ab07-461b-8404-50e10e5e80fb/1152921515689848683",
"product": "product/9f8af57f-ab07-461b-8404-50e10e5e80fb",
"target": {
"targetType": "live"
},
"lifecycleState": "deprecated"
}
]
}
계획을 더 이상 사용하지 않는 경우 "lifecycleState" 속성을 "사용되지 않음"으로 변경한 다음, 사용 중단이 적용되려면 변경 내용을 "미리 보기"에 게시한 다음 "라이브"로 게시해야 합니다. 이는 사용 중단이 라이브 환경에서 자동으로 구성되는 제품 수준 사용 중단과 다릅니다.
계획 사용 중단의 샘플 요청:
아래 예제에서는 SaaS 제품 내의 계획이 더 이상 사용되지 않는 것으로 설정됩니다. 이 변경 내용을 적용하려면 나중에 제출 리소스를 사용하여 게시할 수 있습니다.
POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2
{
"$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
"resources": [
{
"$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2 ",
"id": "plan/9f8af57f-ab07-461b-8404-50e10e5e80fb/7e70b11f-809e-4c45-ae2f-1fb3ceaca33b",
"product": "product/9f8af57f-ab07-461b-8404-50e10e5e80fb",
"identity": { "externalID": "basic" },
"alias": "basic plan"
"lifecycleState": "deprecated"
}
]
}
제품 유형에 따라 다른 형태의 사용 중단이 있습니다. SaaS, 가상 머신 및 컨테이너의 사용 중단에 대해 자세히 알아봅니다.
일반적으로 사용 가능
generallyAvailable 는 모든 리소스의 기본 수명 주기 상태입니다. 리소스가 더 이상 사용되지 않으면 "lifecycleState" 속성을 다시 "generallyAvailable"로 변경하여 복원할 수 있습니다. 사용되지 않는 제품을 복원하려면 미리 보기로 제품을 게시한 다음 라이브로 게시해야 합니다. 해당 문서에서 SaaS, VM 및 컨테이너에 대한 예제를 찾을 수 있습니다.
계획 복원의 샘플 요청:
아래 예제에서는 계획을 복원합니다. 이 변경 내용을 적용하려면 나중에 제출 리소스를 사용하여 라이브로 모든 방법을 게시해야 합니다.
POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2
{
"$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
"resources": [
{
"$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2 ",
"id": "plan/9f8af57f-ab07-461b-8404-50e10e5e80fb/7e70b11f-809e-4c45-ae2f-1fb3ceaca33b",
"product": "product/9f8af57f-ab07-461b-8404-50e10e5e80fb",
"identity": { "externalID": "basic" },
"alias": "basic plan"
"lifecycleState": "generallyAvailable"
}
]
}
리소스 API 참조
아래 스키마 버전은 미리 보기에만 적용되며 API가 일반 공급되면 변경됩니다.
참고 항목
사용 가능한 기존 리소스 및 해당 버전은 resources-index에서 볼 수 있습니다.
제품 유형별 API 지침
제품 수집 API는 나중에 다른 제품 유형에서 사용할 수 있게 됩니다. 더 많은 제품 유형이 지원됨에 따라 각 제품 유형과 관련된 더 많은 지침을 사용할 수 있게 됩니다.
| 제품 유형 | 제품 유형별 리소스 |
|---|---|
| 프라이빗 제품 | 제품 수집 API를 통해 프라이빗 제품 만들기 및 관리 |
| SaaS | 제품 수집 API를 통해 SaaS 제품 만들기 및 관리 |
| 가상 머신 | 제품 수집 API를 통해 가상 머신 제품 만들기 및 관리 |
| 컨테이너 | Product Ingestion API를 통해 컨테이너 제품 만들기 및 관리 |
API 버전 및 업데이트
| Update | 무엇이 변경되었나요? |
|---|---|
| 12-2024 | 모든 스키마 엔드포인트가 product-ingestion.azureedge.net schema.mp.microsoft.com 업데이트되었습니다. |
| 12-2022 | 고객 잠재 고객을 구성하는 동안 clientID 및 clientSecret을 수락하고 serverID 및 연락처 전자 메일 필드 캡처를 중지하는 새로운 스키마 버전 2022-03-01-preview3 고객 잠재 고객용 PC 수집 API를 사용할 수 있습니다. 새 버전으로 전환하고 clientID 및 clientSecret을 제공하여 마켓플레이스 제품에 대한 Marketo 커넥터를 계속 구성합니다. 새 스키마 URL: https://schema.mp.microsoft.com/schema/customer-leads/2022-03-01-preview3 |
| 09-2022 | 컨테이너 미리 보기 지원은 버전 2022-03-01-preview4로 릴리스됩니다. |
| 08-2022 | Software as a Service Preview 지원은 버전 2022-03-01-preview3으로 릴리스됩니다. |
| 08-2022 | 버전 2022-07-01로 프라이빗 제품 공개 릴리스 |
| 05-2022 | 가상 머신 미리 보기 지원은 버전 2022-03-01-preview2로 릴리스됩니다. |