Programozott hozzáférési paradigma kereskedelmi piactérhez

Ez az ábra egy új jelentéssablon létrehozásához, az egyéni jelentés ütemezéséhez és a hibaadatok lekéréséhez használt API-hívásmintát mutatja be.

1. ábra: Az API-hívásminta magas szintű folyamata

Ez a lista további részleteket tartalmaz az 1. ábráról.

1. Az ügyfélalkalmazás a Jelentés lekérdezése APImeghívásával definiálhatja az egyéni jelentéssémát/sablont. Másik lehetőségként használhat jelentéssablont (QueryId) a rendszer lekérdezéseinek listájából.
2. Siker esetén a Jelentéssablon létrehozása API visszaadja a QueryId.
3. Az ügyfélalkalmazás ezután meghívja a Jelentés Létrehozás API-t a QueryID segítségével a jelentés kezdő dátumával, az Ismétlési időközzel, a Gyakorisággal és az opcionális visszahívási URL-lel.
4. Siker esetén a Jelentéskészítő API visszaadja a ReportID.
5. Az ügyfélalkalmazás értesítést kap a visszahívási URI-n, amint a jelentés adatai készen állnak a letöltésre.
6. Az ügyfélalkalmazás ezután a Jelentésvégrehajtások API használatával kérdezi le a jelentés állapotát a Report ID és a dátumtartomány alapján.
7. Sikeresség esetén a rendszer visszaadja a jelentés letöltési hivatkozását, és az alkalmazás kezdeményezheti az adatok letöltését.

Jelentés lekérdezési nyelvének specifikációja

Bár rendszer lekérdezéseket biztosítunk, jelentéseket hozhat létre, de saját lekérdezéseket is létrehozhat az üzleti igényei alapján. Az egyéni lekérdezésekkel kapcsolatos további információkért lásd egyéni lekérdezés specifikációját.

Jelentés lekérdezési API létrehozása

Ez az API segít egyéni lekérdezéseket létrehozni, amelyek meghatározzák azt az adatkészletet, amelyből az oszlopokat és metrikákat exportálni kell. Az API rugalmasan hozhat létre új jelentéssablont az üzleti igényeinek megfelelően.

Az általunk biztosított rendszer-lekérdezéseket is használhatja. Ha nincs szükség egyéni jelentéssablonokra, meghívhatja a Jelentéskészítő API- közvetlenül az általunk biztosított rendszer-lekérdezések QueryIds használatával.

Az alábbi példa bemutatja, hogyan hozhat létre egyéni lekérdezést a normalizált használat és a fizetős termékváltozatok becsült pénzügyi költségeinek lekéréséhez az elmúlt hónap ISVUsage adatkészletből.

Kérés szintaxisa

Kérelem fejlécének

Elérési út paraméter

Egyik sem

lekérdezési paraméter

Egyik sem

Kérelmi hasoadat példa

{
    "Name": "ISVUsageQuery",
    "Description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
    "Query": "SELECT UsageDate, NormalizedUsage, EstimatedExtendedChargePC FROM ISVUsage WHERE SKUBillingType = 'Paid' ORDER BY UsageDate DESC TIMESPAN LAST_MONTH"
}

szószedet

Ez a táblázat a kérelem hasznos adatelemeinek kulcsdefinícióit tartalmazza.

válaszminta

A válasz csomagja a következőképpen épül fel:

Válaszkódok: 200, 400, 401, 403, 500

Válasz payload példa:

{
  "value": [
        {
            "queryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c",
            "name": " ISVUsageQuery",
            "description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
            "query": " SELECT UsageDate, NormalizedUsage, EstimatedExtendedChargePC FROM ISVUsage WHERE SKUBillingType = 'Paid' ORDER BY UsageDate DESC TIMESPAN LAST_MONTH",
            "type": "userDefined",
            "user": "142344300",
            "createdTime": "2024-01-06T05:38:34Z"
        }
    ],
    "totalCount": 1,
    "message": "Query created successfully",
    "statusCode": 200
}

szószedet

Ez a táblázat a válasz elemeinek kulcsdefinícióit tartalmazza.

Jelentés API létrehozása

Amikor sikeresen létrehoz egy egyéni jelentéssablont, és a Jelentéskészítő lekérdezés létrehozása válasz részeként megkapja a QueryID-t, ez az API hívható meg a lekérdezés rendszeres időközönként történő ütemezésére. Beállíthatja a jelentés kézbesítésének gyakoriságát és ütemezését. Az általunk biztosított rendszerlekérdezésekhez a Jelentés létrehozása API QueryIdkóddal is meghívható.

Kérés szintaxisa

Kérelem fejlécének

Elérési út paraméter

Egyik sem

lekérdezési paraméter

Egyik sem

Hasznos adatok kérése példa

{
  "ReportName": "ISVUsageReport",
  "Description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
  "QueryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c ",
  "StartTime": "2021-01-06T19:00:00Z ",
  "executeNow": false,
  "RecurrenceInterval": 48,
  "RecurrenceCount": 20,
  "Format": "csv",
  "CallbackUrl": "https://<SampleCallbackUrl>"
  "callbackMethod": "GET",
}

szószedet

Ez a táblázat a kérelem hasznos adatelemeinek kulcsdefinícióit tartalmazza.

válaszminta

A válasz adathalmaza a következőképpen épül fel:

Válaszkód: 200, 400, 401, 403, 404, 500

Válasz terhelése

{
  "Value": [
    {
            "reportId": "72fa95ab-35f5-4d44-a1ee-503abbc88003",
            "reportName": "ISVUsageReport",
            "description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
            "queryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c",
            "query": "SELECT UsageDate, NormalizedUsage, EstimatedExtendedChargePC FROM ISVUsage WHERE SKUBillingType = 'Paid' ORDER BY UsageDate DESC TIMESPAN LAST_MONTH",
            "user": "142344300",
            "createdTime": "2024-01-06T05:46:00Z",
            "modifiedTime": null,
            "startTime": "2024-01-06T19:00:00Z",
            "reportStatus": "Active",
            "recurrenceInterval": 48,
            "recurrenceCount": 20,
            "callbackUrl": "https://<SampleCallbackUrl>",
            "callbackMethod": "GET",
            "format": "csv"
    }
  ],
  "TotalCount": 1,
  "Message": "Report created successfully",
  "StatusCode": 200
}

szószedet

Ez a táblázat a válasz elemeinek kulcsdefinícióit tartalmazza.

Jelentésvégrehajtási API lekérése

Ezzel a módszerrel lekérdezheti a jelentésvégrehajtás állapotát a jelentéskészítési API-kapott ReportId használatával. A metódus a jelentés letöltési hivatkozását adja vissza, ha a jelentés készen áll a letöltésre. Ellenkező esetben a metódus visszaadja az állapotot. Ezzel az API-val lekérheti az adott jelentéshez tartozó összes végrehajtást.

Kérés szintaxisa

Kérelem fejlécének

Elérési út paraméter

Egyik sem

lekérdezési paraméter

Adatcsomag kérése

Egyik sem

válaszminta

A válasz adatcsomag a következőképpen van felépítve:

Válaszkódok: 200, 400, 401, 403, 404, 500

Példa válasz adathalmazra:

{
    "value": [
        {
            "executionId": "a0bd78ad-1a05-40fa-8847-8968b718d00f",
            "reportId": "72fa95ab-35f5-4d44-a1ee-503abbc88003",
            "recurrenceInterval": 4,
            "recurrenceCount": 10,
            "callbackUrl": null,
            "format": "csv",
            "executionStatus": "Completed",
            "reportAccessSecureLink": "https://<path to report for download>",
            "reportExpiryTime": null,
            "reportGeneratedTime": "2021-01-13T14:40:46Z"
        }
    ],
    "totalCount": 1,
    "message": null,
    "statusCode": 200
}

Ha a jelentés végrehajtása befejeződött, megjelenik a végrehajtási állapot Completed. A jelentést a reportAccessSecureLinkURL-címének kiválasztásával töltheti le.

Szószedet

A válasz elemeinek kulcsdefiníciói.

Az API-kat a Swagger API URL-keresztül is kipróbálhatja.

Kapcsolódó tartalom

• Első API-hívás indítása Marketplace Insights-jelentésekhez