Programové přístupové paradigma pro komerční marketplace

Článek
03/08/2025

Tento diagram znázorňuje vzor volání rozhraní API použitý k vytvoření nové šablony sestavy, naplánování vlastní sestavy a načtení dat o selhání.

Obrázek 1: Tok vzoru volání rozhraní API na vysoké úrovni

Tento seznam obsahuje další podrobnosti o obrázku 1.

Klientská aplikace může definovat vlastní schéma nebo šablonu sestavy voláním rozhraní API pro vytvoření dotazu pro sestavu. Alternativně můžete použít šablonu sestavy (QueryId) ze seznamu systémových dotazů.
V případě úspěchu rozhraní API pro vytvoření šablony sestavy vrátí QueryId.
Klientská aplikace pak volá rozhraní Create Report API pomocí QueryID spolu s počátečním datem sestavy, intervalem opakování, opakováním a volitelným identifikátorem URI zpětného volání.
V případě úspěchu rozhraní API pro vytvoření sestavy vrátí ReportID.
Klientská aplikace obdrží oznámení na URI zpětného volání, jakmile jsou data sestavy připravena ke stažení.
Klientská aplikace poté používá rozhraní Get Report Executions API k dotázání stavu sestavy pomocí Report ID a časového rozsahu.
Pokud se to podaří, se vrací odkaz ke stažení sestavy a aplikace může zahájit stahování dat.

Specifikace dotazovacího jazyka reportování

My poskytujeme systémové dotazy, které můžete použít k vytváření sestav, ale můžete také vytvářet vlastní dotazy na základě vašich obchodních potřeb. Další informace o vlastních dotazech najdete v dokumentu Specifikace vlastních dotazů.

Vytvoření rozhraní API pro dotazy na sestavy

Toto rozhraní API pomáhá vytvářet vlastní dotazy, které definují datovou sadu, ze které sloupce a metriky je potřeba exportovat. Rozhraní API poskytuje flexibilitu při vytváření nové šablony vytváření sestav na základě vašich obchodních potřeb.

Můžete také použít systémové dotazy , které poskytujeme. Pokud nejsou potřeba vlastní šablony sestav, můžete přímo volat rozhraní Create Report API pomocí QueryIds systémových dotazů, které poskytujeme.

Následující příklad ukazuje, jak vytvořit vlastní dotaz, který získá normalizované využití a odhadované finanční poplatky za placené skladové položky z datové sady ISVUsage za poslední měsíc.

Syntaxe požadavku

Metoda	Identifikátor URI požadavku
POST	`https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledQueries`

hlavičky požadavku

Záhlaví	Typ	Popis
Oprávnění	řetězec	Povinné Přístupový token Microsoft Entra. Formát je `Bearer <token>`.
Typ obsahu	`string`	`application/JSON`

parametr cesty

Žádný

Parametr dotazu

Žádný

příklad datové části požadavku

{
    "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"
}

glosář

Tato tabulka obsahuje klíčové definice prvků v datové části požadavku.

Parametr	Požadovaný	Popis	Povolené hodnoty
`Name`	Ano	Uživatelsky přívětivý název dotazu	řetězec
`Description`	Ne	Popis vytvořeného dotazu	řetězec
`Query`	Ano	Řetězec dotazu založený na obchodní potřebě	řetězec

Poznámka

Pro příklady vlastních dotazů viz ukázky dotazů.

ukázková odpověď

Datová část odpovědi je strukturovaná takto:

Kódy odpovědí: 200, 400, 401, 403, 500

Příklad datové části odpovědi:

{
  "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
}

Glosář

Tato tabulka poskytuje klíčové definice prvků v odpovědi.

Parametr	Popis
`QueryId`	Univerzální jedinečný identifikátor (UUID) vytvořeného dotazu
`Name`	Název zadaný v datové části požadavku během vytváření dotazu
`Description`	Popis zadaný v datové části požadavku během vytváření dotazu
`Query`	Vlastní dotaz sestavy zadaný v datové části požadavku během vytváření dotazu
`Type`	Nastavení na `userDefined` pro ručně vytvořené dotazy
`User`	ID uživatele použité k vytvoření dotazu
`CreatedTime`	Čas UTC při vytvoření dotazu Formát: yyyy-MM-ddTHH:mm:ssZ
`TotalCount`	Počet záznamů v poli Hodnota
`StatusCode`	Kód výsledku Možné hodnoty jsou 200, 400, 401, 403, 500
`message`	Stavová zpráva ze spuštění rozhraní API

Vytvořit API pro vytváření sestav

Při úspěšném vytvoření vlastního reportu pomocí šablony a přijetí QueryID v rámci odpovědi na dotaz sestavy , můžete toto API použít k naplánování pravidelného spouštění dotazu. Můžete nastavit frekvenci a harmonogram pro doručení sestavy. Pro systémové dotazy, které poskytujeme, lze rozhraní API pro vytvoření sestavy volat také pomocí QueryId.

syntaxe požadavku

Metoda	Požadavek URI
POST	`https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledReport`

hlavičky požadavku

Záhlaví	Typ	Popis
Oprávnění	řetězec	Povinné. Přístupový token Microsoft Entra. Formát je `Bearer <token>`.
Typ obsahu	řetězec	`application/JSON`

parametr cesty

Žádný

Parametr dotazu

Žádný

příklad obsahu požadavku

{
  "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",
}

glosář

Tato tabulka obsahuje klíčové definice prvků v datové části požadavku.

Parametr	Požadovaný	Popis	Povolené hodnoty
`ReportName`	Ano	Uživatelsky přívětivý název přiřazený k sestavě	Řetězec
`Description`	Ne	Popis vytvořené sestavy	Řetězec
`QueryId`	Ano	ID dotazu, které je potřeba použít pro generování sestav	Řetězec
`StartTime`	Ano	Časové razítko UTC, ve kterém bude generování sestavy zahájeno. Formát by měl být rrrr-MM-ddTHH:mm:ssZ.	Řetězec
`ExecuteNow`	Ne	Tento parametr by měl být použit k vytvoření sestavy, která se spustí pouze jednou. `StartTime`, `RecurrenceInterval`, `RecurrenceCount`a `EndTime` se ignorují, pokud je tato možnost nastavená na `true`	Booleovský
`QueryStartTime`	Ne	Volitelně určuje čas zahájení dotazu extrahujícího data. Tento parametr je použitelný pouze pro jednorázovou zprávu o provedení, která má `ExecuteNow` nastaveno na `true`. Formát by měl být rrrr-MM-ddTHH:mm:ssZ.	Časové razítko jako řetězec
`QueryEndTime`	Ne	Volitelně určuje čas ukončení dotazu extrahujícího data. Tento parametr je použitelný pouze pro jednorázovou sestavu provádění, která má `ExecuteNow` nastaveno na `true`. Formát by měl být rrrr-MM-ddTHH:mm:ssZ.	Časové razítko jako řetězec
`RecurrenceInterval`	Ano	Frekvence v hodinách, ve kterých má být sestava generována. Minimální hodnota je 1 a maximální hodnota je 17520	Integer
`RecurrenceCount`	Ano	Počet vygenerovaných sestav Limit závisí na intervalu opakování.	Celé číslo
`Format`	Ne	Formát souboru exportovaného souboru Výchozí formát je CSV.	CSV/TSV
`CallbackUrl`	Ne	Veřejně přístupná adresa URL, která se dá volitelně nakonfigurovat jako cíl zpětného volání	Řetězec
`CallbackMethod`	Ne	Metoda Get/Post, která se dá nakonfigurovat s adresou URL zpětného volání	GET/POST
`EndTime`	Ano	Časové razítko UTC, kdy bude generování sestavy ukončeno. Formát by měl být rrrr-MM-ddTHH:mm:ssZ.	Řetězec

Poznámka

Při vytváření sestavy je povinná EndTime nebo kombinace RecurrenceInterval a RecurrenceCount.

ukázková odpověď

Datová část odpovědi je strukturovaná takto:

Kód odpovědi: 200, 400, 401, 403, 404, 500

Datová část odpovědi:

{
  "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
}

glosář

Tato tabulka poskytuje klíčové definice prvků v odpovědi.

Parametr	Popis
`ReportId`	Univerzální jedinečný identifikátor (UUID) zprávy, kterou jste vytvořili
`ReportName`	Název zadaný v datové části žádosti při vytváření sestavy
`Description`	Popis zadaný v datové části požadavku během vytváření sestavy
`QueryId`	Identifikátor dotazu uvedený v obsahu požadavku při vytváření zprávy
`Query`	Text dotazu, který se spustí pro tuto sestavu
`User`	ID uživatele použité k vytvoření sestavy
`CreatedTime`	UTC čas ve formátu, kdy byla vytvořena zpráva: rrrr-MM-ddTHH:mm:ssZ
`ModifiedTime`	UTC čas, kdy byla zpráva naposledy změněna, v tomto formátu: rrrr-MM-ddTHH:mm:ssZ
`ExecuteNow`	Parametr ExecuteNow zadaný v datové části požadavku během vytváření sestavy
`queryStartTime`	Čas spuštění dotazu zadaný v datové části požadavku během vytváření sestavy To platí jenom v případě, že je `ExecuteNow` nastavená na Hodnotu True.
`queryEndTime`	Koncový čas dotazu zadaný v datové části požadavku během vytváření sestavy. To platí jenom v případě, že je `ExecuteNow` nastavená na Hodnotu True.
`StartTime`	Počáteční čas zadaný v datové části žádosti během vytváření sestavy
`ReportStatus`	Stav provádění zprávy Možné hodnoty jsou Pozastaveno, Aktivnía Neaktivní.
`RecurrenceInterval`	Interval opakování zadaný v obsahu požadavku při vytváření zprávy
`RecurrenceCount`	Zbývající počet opakování pro sestavu
`CallbackUrl`	Adresa URL zpětného volání zadaná v datové části požadavku během vytváření sestavy
`CallbackMethod`	Metoda zpětného volání zadaná v datové části požadavku během vytváření sestavy
`Format`	Formát souborů sestav poskytnutých v datové části požadavku při vytváření sestav
`EndTime`	Koncový čas poskytnutý v datové části požadavku během vytváření sestavy To platí jenom v případě, že je `ExecuteNow` nastavená na Hodnotu True.
`TotalRecurrenceCount`	`RecurrenceCount` zadané v datové části žádosti během vytváření sestavy
`nextExecutionStartTime`	Časové razítko UTC, kdy bude zahájeno další generování sestavy.
`TotalCount`	Počet záznamů v poli Hodnota
`StatusCode`	Kód výsledku Možné hodnoty jsou 200, 400, 401, 403, 500
`message`	Stavová zpráva ze spuštění rozhraní API

Získání rozhraní API pro spouštění sestav

Tuto metodu můžete použít k dotazování na stav provádění sestavy pomocí ReportId přijatého z rozhraní API pro vytvoření sestavy. Metoda vrátí odkaz ke stažení sestavy, pokud je sestava připravená ke stažení. V opačném případě vrátí metoda stav. Toto rozhraní API můžete také použít k získání všech spuštění, ke kterým došlo pro danou sestavu.

Důležitý

Toto rozhraní API má nastavené výchozí parametry dotazu pro executionStatus=Completed a getLatestExecution=true. Proto volání rozhraní API před prvním úspěšným spuštěním sestavy vygeneruje chybu 404. Čekající spuštění lze získat nastavením executionStatus=Pending.

syntaxe požadavku

Metoda	Požadavek na URI
Získat	`https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledReport/execution/{reportId}?executionId={executionId}&executionStatus={executionStatus}&getLatestExecution={getLatestExecution}`

hlavičky požadavku

Záhlaví	Typ	Popis
Oprávnění	řetězec	Povinné. Přístupový token Microsoft Entra. Formát je `Bearer <token>`.
Typ obsahu	řetězec	`application/json`

parametr cesty

Žádný

parametr dotazu

Název parametru	Požadovaný	Typ	Popis
`reportId`	Ano	řetězec	Filtrem získáte podrobnosti o provádění pouze sestav s `reportId` zadanými v tomto argumentu.
`executionId`	Ne	řetězec	Filtrováním získáte podrobnosti pouze o sestavách s `executionId` zadanými v tomto argumentu. Více `executionIds` lze zadat tak, že je oddělíte středníkem ";".
`executionStatus`	Ne	string/enum	Filtrováním získáte podrobnosti pouze o sestavách s `executionStatus` zadanými v tomto argumentu. Platné hodnoty jsou: `Pending`, `Running`, `Paused`a `Completed` Výchozí hodnota je `Completed`.
`getLatestExecution`	Ne	booleovský	Rozhraní API vrátí podrobnosti o nejnovějším spuštění sestavy. Ve výchozím nastavení je tento parametr nastaven na `true`. Pokud se rozhodnete předat hodnotu tohoto parametru jako `false`, rozhraní API vrátí instance provádění za posledních 90 dnů.

datová část požadavku

Žádný

ukázková odpověď

Datová část odpovědi je strukturovaná takto:

Kódy odpovědí: 200, 400, 401, 403, 404, 500

Příklad datové části odpovědi:

{
    "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
}

Po dokončení provádění sestavy se zobrazí stav spuštění Completed. Sestavu si můžete stáhnout kliknutím na adresu URL v reportAccessSecureLink.

glosář

Klíčové definice prvků v odpovědi

Parametr	Popis
`ExecutionId`	Univerzální jedinečný identifikátor (UUID) prováděcí instance
`ReportId`	ID sestavy přidružené k instanci spuštění
`RecurrenceInterval`	Interval opakování zadaný při vytváření zprávy
`RecurrenceCount`	Počet opakování poskytnutý během vytváření zprávy
`CallbackUrl`	Adresa URL zpětného volání přidružená k instanci spuštění
`CallbackMethod`	Metoda zpětného volání zadaná v datové části požadavku během vytváření sestavy
`Format`	Formát vygenerovaného souboru na konci spuštění
`ExecutionStatus`	Stav instance spuštění sestavy Platné hodnoty jsou: `Pending`, `Running`, `Paused`a `Completed`
`ReportLocation`	Umístění, kam se zpráva stáhne.
`ReportAccessSecureLink`	Odkaz, prostřednictvím kterého lze bezpečně získat přístup k sestavě
`ReportExpiryTime`	Čas UTC, po kterém odkaz na sestavu vyprší, v tomto formátu: rrrr-MM-ddTHH:mm:ssZ
`ReportGeneratedTime`	Čas UTC, kdy byl vygenerován report v tomto formátu: rrrr-MM-ddTHH:mm:ssZ
`EndTime`	Koncový čas poskytnutý v datové části požadavku během vytváření sestavy To platí jenom v případě, že je `ExecuteNow` nastavená na Hodnotu True.
`TotalRecurrenceCount`	`RecurrenceCount` zadané v datové části žádosti během vytváření sestavy
`nextExecutionStartTime`	Časové razítko UTC, kdy se spustí další spuštění sestavy
`TotalCount`	Počet datových sad v poli Hodnota
`StatusCode`	Kód výsledku Možné hodnoty jsou 200, 400, 401, 403, 404 a 500.
`message`	Stavová zpráva ze spuštění rozhraní API

Rozhraní API si můžete vyzkoušet prostřednictvím adresy URL rozhraní Swagger API.

Udělejte své první volání rozhraní API pro sestavy Marketplace Insights

Sdílet prostřednictvím

Programové přístupové paradigma pro komerční marketplace

Specifikace dotazovacího jazyka reportování

Vytvoření rozhraní API pro dotazy na sestavy

Vytvořit API pro vytváření sestav

Získání rozhraní API pro spouštění sestav

Váš názor

Další materiály

Sdílet prostřednictvím

Programové přístupové paradigma pro komerční marketplace

Specifikace dotazovacího jazyka reportování

Vytvoření rozhraní API pro dotazy na sestavy

Vytvořit API pro vytváření sestav

Získání rozhraní API pro spouštění sestav

Související obsah

Váš názor

Další materiály