Microsoft 상업용 Marketplace의 SaaS 처리 작업 API v2
참고 항목
SaaS 처리 작업 API를 호출하려면 올바른 리소스 ID를 사용하여 게시자의 권한 부여 토큰을 만들어야 합니다. 게시자의 권한 부여 토큰을 가져오는 방법 알아보기
이 문서에서는 SaaS 처리 작업 API 버전 2에 대해 설명합니다.
작업은 ChangePlan, ChangeQuantity 및 복구 작업의 일부로 웹후크를 통해 들어오는 모든 요청에 응답하는 데 유용합니다. 이렇게 하면 아래 API를 사용하여 성공 또는 실패로 웹후크 작업을 패치하여 요청을 수락하거나 거부할 수 있습니다.
이는 ACK가 필요한 ChangePlan, ChangeQuantity 및 복구와 같은 웹후크 이벤트에만 적용됩니다. ISV(독립 소프트웨어 공급업체)는 알림 전용 이벤트이므로 갱신, 일시 중단 및 구독 취소 이벤트에 대한 조치가 필요하지 않습니다.
미해결 작업 나열
지정된 SaaS 구독에 대한 보류 중인 작업 목록을 가져옵니다. 게시자는 작업 패치 API를 호출하여 반환된 작업을 승인해야 합니다.
Get https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations?api-version=<ApiVersion>
쿼리 매개 변수:
| 매개 변수 | 값 |
|---|---|
ApiVersion |
2018-08-31을 사용합니다. |
subscriptionId |
구매한 SaaS 구독의 고유 식별자입니다. 이 ID는 확인 API를 사용하여 상업용 Marketplace 권한 부여 토큰을 확인한 후에 가져옵니다. |
요청 헤더:
| 매개 변수 | 값 |
|---|---|
content-type |
application/json |
x-ms-requestid |
클라이언트의 요청을 추적하기 위한 고유 문자열 값(GUID)입니다. 이 값이 제공되지 않으면 응답 헤더에 값이 생성되고 제공됩니다. |
x-ms-correlationid |
클라이언트의 작업에 대한 고유한 문자열 값입니다. 이 매개 변수는 클라이언트 작업의 모든 이벤트를 서버 쪽의 이벤트와 상호 연결합니다. 이 값이 제공되지 않으면 응답 헤더에 값이 생성되고 제공됩니다. |
authorization |
형식은 "Bearer <access_token>" Microsoft Entra 앱을 기반으로 토큰 가져오기에 설명된 대로 게시자가 토큰 값을 검색하는 경우입니다. |
응답 코드:
코드: 200 지정된 SaaS 구독에서 보류 중인 작업을 반환합니다.
응답 페이로드 예제:
{
"operations": [
{
"id": "<guid>", //Operation ID, should be provided in the operations patch API call
"activityId": "<guid>", //not relevant
"subscriptionId": "<guid>", // subscriptionId of the SaaS subscription that is being reinstated
"offerId": "offer1", // purchased offer ID
"publisherId": "contoso",
"planId": "silver", // purchased plan ID
"quantity": 20, // purchased amount of seats, will be empty is not relevant
"action": "Reinstate",
"timeStamp": "2018-12-01T00:00:00", // UTC
"status": "InProgress" // the only status that can be returned in this case
}
]
}
보류 중인 작업이 없는 경우 빈 json을 반환합니다.
코드: 400 잘못된 요청: 유효성 검사 실패.
코드: 403 사용할 수 없음. 권한 부여 토큰이 잘못되었거나 만료되었거나 제공되지 않았습니다. 요청이 권한 부여 토큰을 만드는 데 사용된 것과 다른 Microsoft Entra 앱 ID로 게시된 제품에 대한 SaaS 구독에 액세스하려고 시도합니다.
이 오류는 종종 SaaS 등록을 제대로 수행하지 않았을 때 발생하는 증상입니다.
코드: 404를 찾을 수 없음. SaaS 구독을 subscriptionId 찾을 수 없습니다.
코드: 500 내부 서버 오류. API 호출을 다시 시도합니다. 오류가 지속되면 Microsoft 지원에 문의하세요.
작업 상태 가져오기
이 API를 통해 게시자는 지정된 비동기 작업(Unsubscribe, ChangePlan 또는 ChangeQuantity)의 상태를 추적할 수 있습니다.
이 API 호출의 operationId 경우 Operation-Location에서 반환된 값, 보류 중인 Operations API 호출 가져오기 또는 <id> 웹후크 호출에서 받은 매개 변수 값에서 검색할 수 있습니다.
Get https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=<ApiVersion>
쿼리 매개 변수:
| 매개 변수 | 값 |
|---|---|
ApiVersion |
2018-08-31을 사용합니다. |
subscriptionId |
구매한 SaaS 구독의 고유 식별자입니다. 이 ID는 확인 API를 사용하여 상업용 Marketplace 권한 부여 토큰을 확인한 후에 가져옵니다. |
operationId |
검색되는 작업의 고유 식별자입니다. |
요청 헤더:
| 매개 변수 | 값 |
|---|---|
content-type |
application/json |
x-ms-requestid |
클라이언트의 요청을 추적하기 위한 고유 문자열 값(GUID)입니다. 이 값이 제공되지 않으면 응답 헤더에 값이 생성되고 제공됩니다. |
x-ms-correlationid |
클라이언트의 작업에 대한 고유한 문자열 값입니다. 이 매개 변수는 클라이언트 작업의 모든 이벤트를 서버 쪽의 이벤트와 상호 연결합니다. 이 값이 제공되지 않으면 응답 헤더에 값이 생성되고 제공됩니다. |
authorization |
이 API 호출을 만드는 게시자를 식별하는 고유한 액세스 토큰입니다. 형식은 "Bearer <access_token>" Microsoft Entra 앱을 기반으로 토큰 가져오기에 설명된 대로 게시자가 토큰 값을 검색하는 경우입니다. |
응답 코드:
코드: 200 지정된 SaaS 작업에 대한 세부 정보를 가져옵니다.
응답 페이로드 예제:
Response body:
{
"id ": "<guid>", //Operation ID, should be provided in the patch operation API call
"activityId": "<guid>", //not relevant
"subscriptionId": "<guid>", // subscriptionId of the SaaS subscription for which this operation is relevant
"offerId": "offer1", // purchased offer ID
"publisherId": "contoso",
"planId": "silver", // purchased plan ID
"quantity": 20, // purchased amount of seats
"action": "ChangePlan", // Can be ChangePlan, ChangeQuantity or Reinstate
"timeStamp": "2018-12-01T00:00:00", // UTC
"status": "InProgress", // Possible values: NotStarted, InProgress, Failed, Succeeded, Conflict (new quantity / plan is the same as existing)
"errorStatusCode": "",
"errorMessage": ""
}
코드: 403 사용할 수 없음. 권한 부여 토큰이 잘못되었거나 만료되었거나 제공되지 않았습니다. 요청이 권한 부여 토큰을 만드는 데 사용된 것과 다른 Microsoft Entra 앱 ID로 게시된 제품에 대한 SaaS 구독에 액세스하려고 시도합니다.
이 오류는 종종 SaaS 등록을 제대로 수행하지 않았을 때 발생하는 증상입니다.
코드: 404를 찾을 수 없음.
- 구독을
subscriptionId찾을 수 없습니다. operationId작업을 찾을 수 없습니다.
코드: 500 내부 서버 오류. API 호출을 다시 시도합니다. 오류가 지속되면 Microsoft 지원에 문의하세요.
작업 상태 업데이트
이 API를 사용하여 보류 중인 작업의 상태를 업데이트하여 게시자 쪽에서 작업의 성공 또는 실패를 나타냅니다.
이 API 호출의 operationId 경우 Operation-Location에서 반환된 값, 보류 중인 Operations API 호출 가져오기 또는 <id> 웹후크 호출에서 받은 매개 변수 값에서 검색할 수 있습니다.
Patch https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=<ApiVersion>
쿼리 매개 변수:
| 매개 변수 | 값 |
|---|---|
ApiVersion |
2018-08-31을 사용합니다. |
subscriptionId |
구매한 SaaS 구독의 고유 식별자입니다. 이 ID는 확인 API를 사용하여 상업용 Marketplace 권한 부여 토큰을 확인한 후에 가져옵니다. |
operationId |
완료되는 작업의 고유 식별자입니다. |
요청 헤더:
| 매개 변수 | 값 |
|---|---|
content-type |
application/json |
x-ms-requestid |
클라이언트의 요청을 추적하기 위한 고유 문자열 값(GUID)입니다. 이 값이 제공되지 않으면 응답 헤더에 값이 생성되고 제공됩니다. |
x-ms-correlationid |
클라이언트의 작업에 대한 고유한 문자열 값입니다. 이 매개 변수는 클라이언트 작업의 모든 이벤트를 서버 쪽의 이벤트와 상호 연결합니다. 이 값이 제공되지 않으면 응답 헤더에 값이 생성되고 제공됩니다. |
authorization |
이 API 호출을 수행하는 게시자를 식별하는 고유한 액세스 토큰입니다. 형식은 "Bearer <access_token>" Microsoft Entra 앱을 기반으로 토큰 가져오기에 설명된 대로 게시자가 토큰 값을 검색하는 경우입니다. |
요청 페이로드 예제:
{
"status": "Success" // Allowed Values: Success/Failure. Indicates the status of the operation on ISV side.
}
응답 코드:
코드: 200 파트너 쪽에서 작업이 완료되었음을 알리기 위한 호출입니다. 예를 들어 이 응답은 게시자 쪽에서 사용자 또는 계획의 변경이 완료되었음을 알릴 수 있습니다.
코드: 403
- 금지됩니다. 권한 부여 토큰을 사용할 수 없거나, 유효하지 않거나, 만료되었습니다. 요청이 현재 게시자에 속하지 않는 구독에 액세스하려고 할 수 있습니다.
- 금지됩니다. 권한 부여 토큰이 잘못되었거나 만료되었거나 제공되지 않았습니다. 요청이 권한 부여 토큰을 만드는 데 사용된 것과 다른 Microsoft Entra 앱 ID로 게시된 제품에 대한 SaaS 구독에 액세스하려고 시도합니다.
이 오류는 종종 SaaS 등록을 제대로 수행하지 않았을 때 발생하는 증상입니다.
코드: 404를 찾을 수 없음.
- 구독을
subscriptionId찾을 수 없습니다. operationId작업을 찾을 수 없습니다.
코드: 409 충돌. 예를 들어 최신 업데이트가 이미 수행되었습니다.
코드: 500 내부 서버 오류. API 호출을 다시 시도합니다. 오류가 지속되면 Microsoft 지원에 문의하세요.
관련 콘텐츠
- 상업용 Marketplace에서 SaaS 제품에 대한 추가 옵션은 상업용 Marketplace 계량 서비스 API 를 참조하세요.
- 다양한 프로그래밍 언어 및 샘플에 대한 클라이언트를 검토하고 사용합니다.