SaaS fulfillment operations API-k v2 a Microsoft kereskedelmi piactéren
Feljegyzés
Az SaaS fulfillment Operations API-k meghívásához létre kell hoznia egy közzétevő engedélyezési jogkivonatát a megfelelő erőforrás-azonosítóval. Megtudhatja, hogyan szerezheti be a közzétevő engedélyezési jogkivonatát
Ez a cikk az SaaS fulfillment operations API-k 2. verzióját ismerteti.
A műveletek a ChangePlan, a ChangeQuantity és az Reinstate műveletek részeként a webhookon keresztül érkező kérelmek megválaszolásához hasznosak. Ez lehetőséget nyújt arra, hogy az alábbi API-k használatával elfogadjon vagy elutasítson egy olyan kérést, amely a webhook sikeres vagy sikertelen műveletet tartalmaz.
Ez csak azokra a webhookeseményekre vonatkozik, mint a ChangePlan, a ChangeQuantity és a Reinstate, amelyekhez ACK szükséges. A független szoftverszállítónak (ISV) nincs szüksége műveletre a megújítási, felfüggesztési és leiratkozási eseményeken, mert csak értesítési események.
Függőben lévő műveletek listázása
Kérje le a megadott SaaS-előfizetés függőben lévő műveleteinek listáját. A közzétevőnek az Operation Patch API meghívásával nyugtáznia kell a visszaadott műveleteket.
Kap https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations?api-version=<ApiVersion>
Lekérdezési paraméterek:
Paraméter | Érték |
---|---|
ApiVersion |
Használja a 2018-08-31-et. |
subscriptionId |
A megvásárolt SaaS-előfizetés egyedi azonosítója. Ezt az azonosítót a kereskedelmi piactér engedélyezési jogkivonatának feloldása után kapja meg a Resolve API használatával. |
Kérelemfejlécek:
Paraméter | Érték |
---|---|
content-type |
application/json |
x-ms-requestid |
Az ügyfél kérésének nyomon követésére szolgáló egyedi sztringérték, lehetőleg GUID. Ha ez az érték nincs megadva, a rendszer létrehoz egyet, és megadja a válaszfejlécekben. |
x-ms-correlationid |
Az ügyfélen végzett művelet egyedi sztringértéke. Ez a paraméter korrelálja az ügyfélművelet összes eseményét a kiszolgálóoldali eseményekkel. Ha ez az érték nincs megadva, a rendszer létrehoz egyet, és megadja a válaszfejlécekben. |
authorization |
A formátum az, "Bearer <access_token>" amikor a közzétevő lekéri a jogkivonat értékét a Microsoft Entra alkalmazáson alapuló jogkivonat lekérése című témakörben leírtak szerint. |
Válaszkódok:
Kód: 200 Függőben lévő műveleteket ad vissza a megadott SaaS-előfizetésen.
Példa válasz hasznos adatra:
{
"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
}
]
}
Üres json értéket ad vissza, ha nincsenek függőben lévő műveletek.
Kód: 400 Hibás kérés: érvényesítési hibák.
Kód: 403 Tiltott. Az engedélyezési jogkivonat érvénytelen, lejárt vagy nem lett megadva. A kérés egy SaaS-előfizetéshez próbál hozzáférni egy olyan ajánlathoz, amely az engedélyezési jogkivonat létrehozásához használttól eltérő Microsoft Entra-alkalmazásazonosítóval van közzétéve.
Ez a hiba gyakran az SaaS-regisztráció helytelen végrehajtásának tünete.
Kód: 404 Nem található. Az SaaS-előfizetés subscriptionId
nem található.
Kód: 500 Belső kiszolgálóhiba. Próbálkozzon újra az API-hívással. Ha a hiba továbbra is fennáll, forduljon a Microsoft ügyfélszolgálatához.
Művelet állapotának lekérése
Ez az API lehetővé teszi, hogy a közzétevő nyomon kövesse a megadott aszinkron művelet állapotát: Leiratkozás, ChangePlan vagy ChangeQuantity.
Ennek operationId
az API-hívásnak az értéke lekérhető az Operation-Location által visszaadott értékből, a függőben lévő Operations API-hívásból vagy a <id>
webhook-hívásban kapott paraméterértékből.
Kap https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=<ApiVersion>
Lekérdezési paraméterek:
Paraméter | Érték |
---|---|
ApiVersion |
Használja a 2018-08-31-et. |
subscriptionId |
A megvásárolt SaaS-előfizetés egyedi azonosítója. Ezt az azonosítót a kereskedelmi piactér engedélyezési jogkivonatának feloldása után kapja meg a Resolve API használatával. |
operationId |
A lekért művelet egyedi azonosítója. |
Kérelemfejlécek:
Paraméter | Érték |
---|---|
content-type |
application/json |
x-ms-requestid |
Az ügyfél kérésének nyomon követésére szolgáló egyedi sztringérték, lehetőleg GUID. Ha ez az érték nincs megadva, a rendszer létrehoz egyet, és megadja a válaszfejlécekben. |
x-ms-correlationid |
Az ügyfélen végzett művelet egyedi sztringértéke. Ez a paraméter korrelálja az ügyfélművelet összes eseményét a kiszolgálóoldali eseményekkel. Ha ez az érték nincs megadva, a rendszer létrehoz egyet, és megadja a válaszfejlécekben. |
authorization |
Egyedi hozzáférési jogkivonat, amely azonosítja az API-hívást kezdeményező közzétevőt. A formátum az, "Bearer <access_token>" amikor a közzétevő lekéri a jogkivonat értékét a Microsoft Entra alkalmazáson alapuló jogkivonat lekérése című témakörben leírtak szerint. |
Válaszkódok:
Kód: 200 Lekéri a megadott SaaS-művelet részleteit.
Példa válasz hasznos adatra:
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": ""
}
Kód: 403 Tiltott. Az engedélyezési jogkivonat érvénytelen, lejárt vagy nem lett megadva. A kérés egy SaaS-előfizetéshez próbál hozzáférni egy olyan ajánlathoz, amely az engedélyezési jogkivonat létrehozásához használttól eltérő Microsoft Entra-alkalmazásazonosítóval van közzétéve.
Ez a hiba gyakran az SaaS-regisztráció helytelen végrehajtásának tünete.
Kód: 404 Nem található.
subscriptionId
Az előfizetés nem található.operationId
A művelet nem található.
Kód: 500 Belső kiszolgálóhiba. Próbálkozzon újra az API-hívással. Ha a hiba továbbra is fennáll, forduljon a Microsoft ügyfélszolgálatához.
Művelet állapotának frissítése
Ezzel az API-val frissítheti a függőben lévő művelet állapotát, hogy jelezze a művelet sikerességét vagy sikertelenségét a közzétevő oldalán.
Ennek operationId
az API-hívásnak az értéke lekérhető az Operation-Location által visszaadott értékből, a függőben lévő Operations API-hívásból vagy a <id>
webhook-hívásban kapott paraméterértékből.
Folt https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=<ApiVersion>
Lekérdezési paraméterek:
Paraméter | Érték |
---|---|
ApiVersion |
Használja a 2018-08-31-et. |
subscriptionId |
A megvásárolt SaaS-előfizetés egyedi azonosítója. Ezt az azonosítót a kereskedelmi piactér engedélyezési jogkivonatának feloldása után kapja meg a Resolve API használatával. |
operationId |
A befejezett művelet egyedi azonosítója. |
Kérelemfejlécek:
Paraméter | Érték |
---|---|
content-type |
application/json |
x-ms-requestid |
Az ügyfél kérésének nyomon követésére szolgáló egyedi sztringérték, lehetőleg GUID. Ha ez az érték nincs megadva, a rendszer létrehoz egyet, és megadja a válaszfejlécekben. |
x-ms-correlationid |
Az ügyfélen végzett művelet egyedi sztringértéke. Ez a paraméter korrelálja az ügyfélművelet összes eseményét a kiszolgálóoldali eseményekkel. Ha ez az érték nincs megadva, a rendszer létrehoz egyet, és megadja a válaszfejlécekben. |
authorization |
Egyedi hozzáférési jogkivonat, amely azonosítja az API-hívást kezdeményező közzétevőt. A formátum az, "Bearer <access_token>" amikor a közzétevő lekéri a jogkivonat értékét a Microsoft Entra alkalmazáson alapuló jogkivonat lekérése című témakörben leírtak szerint. |
Példa a hasznos adatok kérésére:
{
"status": "Success" // Allowed Values: Success/Failure. Indicates the status of the operation on ISV side.
}
Válaszkódok:
Kód: 200 A partneroldali művelet befejezésének értesítése. Ez a válasz például jelezheti a kiadói oldalon a helyek vagy tervek változásának befejezését.
Kód: 403
- Tiltott. Az engedélyezési jogkivonat nem érhető el, érvénytelen vagy lejárt. Előfordulhat, hogy a kérés olyan előfizetést próbál elérni, amely nem az aktuális közzétevőhöz tartozik.
- Tiltott. Az engedélyezési jogkivonat érvénytelen, lejárt vagy nem lett megadva. A kérés egy SaaS-előfizetéshez próbál hozzáférni egy olyan ajánlathoz, amely az engedélyezési jogkivonat létrehozásához használttól eltérő Microsoft Entra-alkalmazásazonosítóval van közzétéve.
Ez a hiba gyakran az SaaS-regisztráció helytelen végrehajtásának tünete.
Kód: 404 Nem található.
subscriptionId
Az előfizetés nem található.operationId
A művelet nem található.
Kód: 409 Ütközés. Egy újabb frissítés például már teljesült.
Kód: 500 Belső kiszolgálóhiba. Próbálkozzon újra az API-hívással. Ha a hiba továbbra is fennáll, forduljon a Microsoft ügyfélszolgálatához.
Kapcsolódó tartalom
- Az SaaS-ajánlatokra vonatkozó további lehetőségekért tekintse meg a kereskedelmi piactér mérési szolgáltatás API-jait a kereskedelmi piactéren.
- Tekintse át és használja az ügyfeleket különböző programozási nyelvekhez és mintákhoz.