Megosztás a következőn keresztül:

SaaS fulfillment operations API-k v2 a Microsoft kereskedelmi piactéren

  • Cikk

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.

Javítás 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.

Következő lépések