Microsoft 상업용 Marketplace의 SaaS 처리 작업 API v2
이 문서에서는 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 를 참조하세요.
- 다양한 프로그래밍 언어 및 샘플에 대한 클라이언트를 검토하고 사용합니다.
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기