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

Článek
06/14/2024

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: Základní tok modelu volání rozhraní API

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

Klientská aplikace může definovat vlastní schéma sestavy nebo šablonu voláním rozhraní API pro vytvoření dotazu sestavy. Případně můžete použít šablonu sestavy (QueryId) ze seznamu systémových dotazů.
Při úspěchu vrátí rozhraní API pro vytvoření šablony sestavy QueryIdhodnotu .
Klientská aplikace pak volá rozhraní API pro vytvoření sestavy pomocí QueryID počátečního data sestavy, intervalu opakování, opakování a volitelného identifikátoru URI zpětného volání.
Při úspěchu vrátí rozhraní API pro vytvoření sestavy ReportIDhodnotu .
Klientská aplikace dostane oznámení na identifikátor URI zpětného volání, jakmile jsou data sestavy připravena ke stažení.
Klientská aplikace pak pomocí rozhraní API Get Report Executions dotazuje stav sestavy s rozsahem dat a rozsahem Report ID dat.
Při úspěchu se vrátí odkaz ke stažení sestavy a aplikace může zahájit stahování dat.

Specifikace dotazovacího jazyka sestavy

I když poskytujeme systémové dotazy , které můžete použít k vytváření sestav, můžete také vytvářet vlastní dotazy na základě vašich obchodních potřeb. Další informace o vlastníchdotazch

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 vlastní šablony sestav nejsou potřeba, můžete rozhraní API pro vytvoření sestavy volat přímo pomocí id dotazů systému, 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 žádosti
POST	`https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledQueries`

Hlavička požadavku

Hlavička	Typ	Popis
Autorizace	string	Povinný: Přístupový token Microsoft Entra. Formát je `Bearer <token>`.
Typ obsahu	`string`	`application/JSON`

Parametr cesty

Nic

Parametr dotazu

Nic

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žadováno	Popis	Povolené hodnoty
`Name`	Ano	Uživatelsky přívětivý název dotazu	string
`Description`	No	Popis vytvořeného dotazu	string
`Query`	Ano	Řetězec dotazu založený na obchodní potřebě	string

Poznámka:

Příklady vlastních dotazů najdete v ukázkových dotazech.

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`	Nastavit na `userDefined` 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: rrrr-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ření rozhraní API pro sestavy

Při úspěšném vytvoření vlastní šablony sestavy a přijetí QueryID odpovědi dotazu na vytvoření sestavy je možné toto rozhraní API volat, aby se dotaz spustil v pravidelných intervalech. Můžete nastavit frekvenci a plán doručení sestavy. Pro systémové dotazy, které poskytujeme, je možné rozhraní API pro vytvoření sestavy volat také pomocí QueryId.

Syntaxe požadavku

metoda	Identifikátor URI žádosti
POST	`https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledReport`

Hlavička požadavku

Hlavička	Typ	Popis
Autorizace	string	Povinný: Přístupový token Microsoft Entra. Formát je `Bearer <token>`.
Typ obsahu	string	`application/JSON`

Parametr cesty

Nic

Parametr dotazu

Nic

Příklad datové části 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žadováno	Popis	Povolené hodnoty
`ReportName`	Ano	Uživatelsky přívětivý název přiřazený k sestavě	Řetězcové
`Description`	No	Popis vytvořené sestavy	String
`QueryId`	Ano	ID dotazu, které je potřeba použít pro generování sestav	String
`StartTime`	Ano	Časové razítko UTC, ve kterém bude generování sestavy začínat. Formát by měl být rrrr-MM-ddTHH:mm:ssZ.	Řetězcové
`ExecuteNow`	No	Tento parametr by se měl použít k vytvoření sestavy, která se spustí pouze jednou. `StartTime`, `RecurrenceIntervalRecurrenceCount`a `EndTime` jsou ignorovány, pokud je nastavena na`true`	Logický
`QueryStartTime`	No	Volitelně určuje čas zahájení dotazu extrahujícího data. Tento parametr je použitelný pouze pro jednu čas sestavu provádění, která je nastavena `ExecuteNow` na `true`. Formát by měl být rrrr-MM-ddTHH:mm:ssZ.	Časové razítko jako řetězec
`QueryEndTime`	No	Volitelně určuje čas ukončení dotazu extrahujícího data. Tento parametr je použitelný pouze pro jednu čas sestavu provádění, která je nastavena `ExecuteNow` 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`	No	Formát souboru exportovaného souboru Výchozí formát je CSV.	CSV/TSV
`CallbackUrl`	No	Veřejně přístupná adresa URL, která se dá volitelně nakonfigurovat jako cíl zpětného volání	Řetězcové
`CallbackMethod`	No	Metoda Get/Post, která se dá nakonfigurovat s adresou URL zpětného volání	GET/POST
`EndTime`	Ano	Časové razítko UTC, ve kterém bude generování sestavy ukončeno. Formát by měl být rrrr-MM-ddTHH:mm:ssZ.	String

Poznámka:

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

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) sestavy, kterou jste vytvořili
`ReportName`	Název zadaný v datové části požadavku během vytváření sestavy
`Description`	Popis zadaný v datové části požadavku během vytváření sestavy
`QueryId`	ID dotazu zadané v datové části požadavku během vytváření sestavy
`Query`	Text dotazu, který se spustí pro tuto sestavu
`User`	ID uživatele použité k vytvoření sestavy
`CreatedTime`	UTC Čas vytvoření sestavy v tomto formátu: rrrr-MM-ddTHH:mm:ssZ
`ModifiedTime`	UTC Čas poslední změny sestavy 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 `ExecuteNow` je nastavená hodnota True.
`queryEndTime`	Koncový čas dotazu zadaný v datové části požadavku během vytváření sestavy. To platí jenom v případě, že `ExecuteNow` je nastavená hodnota True.
`StartTime`	Počáteční čas zadaný v datové části žádosti během vytváření sestavy
`ReportStatus`	Stav provádění sestavy Možné hodnoty jsou Pozastaveno, Aktivní a Neaktivní.
`RecurrenceInterval`	Interval opakování zadaný v datové části požadavku během vytváření sestavy
`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ů sestavy zadaných v datové části požadavku během vytváření sestavy
`EndTime`	Koncový čas poskytnutý v datové části požadavku během vytváření sestavy To platí jenom v případě, že `ExecuteNow` je nastavená hodnota True.
`TotalRecurrenceCount`	`RecurrenceCount` v datové části požadavku během vytváření sestavy
`nextExecutionStartTime`	Časové razítko UTC, kdy se spustí další spuště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 vrátí hodnotu 404. Čekající spuštění lze získat nastavením executionStatus=Pending.

Syntaxe požadavku

metoda	Identifikátor URI žádosti
Získat	`https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledReport/execution/{reportId}?executionId={executionId}&executionStatus={executionStatus}&getLatestExecution={getLatestExecution}`

Hlavička požadavku

Hlavička	Typ	Popis
Autorizace	string	Povinný: Přístupový token Microsoft Entra. Formát je `Bearer <token>`.
Typ obsahu	string	`application/json`

Parametr cesty

Nic

Parametr dotazu

Název parametru	Požaduje se	Type	Popis
`reportId`	Ano	string	Filtrem získáte podrobnosti o provádění pouze sestav, které `reportId` jsou uvedené v tomto argumentu.
`executionId`	No	string	Filtrováním získáte podrobnosti pouze o sestavách, které `executionId` jsou uvedené v tomto argumentu. Násobek `executionIds` lze zadat tak, že je oddělíte středníkem ";".
`executionStatus`	No	string/enum	Filtrováním získáte podrobnosti pouze o sestavách, které `executionStatus` jsou uvedené v tomto argumentu. Platné hodnoty jsou: `Pending`, `Running`, `Paused`a `Completed` Výchozí hodnota je `Completed`.
`getLatestExecution`	No	boolean	Rozhraní API vrátí podrobnosti o poslední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 žádosti

Nic

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 Completed spuštění. Sestavu si můžete stáhnout výběrem adresy URL v souboru reportAccessSecureLink.

Glosář

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

Parametr	Popis
`ExecutionId`	Univerzální jedinečný identifikátor (UUID) instance spuštění
`ReportId`	ID sestavy přidružené k instanci spuštění
`RecurrenceInterval`	Interval opakování zadaný během vytváření sestavy
`RecurrenceCount`	Počet opakování zadaný během vytváření sestavy
`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 sestava stáhne.
`ReportAccessSecureLink`	Propojení, přes které se sestava dá bezpečně získat přístup
`ReportExpiryTime`	ČAS UTC, po kterém vyprší platnost odkazu na sestavu v tomto formátu: rrrr-MM-ddTHH:mm:ssZ
`ReportGeneratedTime`	Čas UTC, kdy byla sestava generována 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 `ExecuteNow` je nastavená hodnota True.
`TotalRecurrenceCount`	`RecurrenceCount` v datové části požadavku 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í API Swaggeru.

Vytvoření prvního volání rozhraní API pro sestavy Přehledy z Marketplace

Sdílet prostřednictvím

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

Specifikace dotazovacího jazyka sestavy

Vytvoření rozhraní API pro dotazy na sestavy

Vytvoření rozhraní API pro sestavy

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 sestavy

Vytvoření rozhraní API pro dotazy na sestavy

Vytvoření rozhraní API pro sestavy

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

Související obsah

Váš názor

Další materiály