Paradigma programového přístupu

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í.

Tok vysoké úrovně Obrázek 1: Tok rozhraní API na vysoké úrovni

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

  1. Klientská aplikace může definovat vlastní schéma nebo šablonu sestavy voláním rozhraní API pro vytvoření dotazu na sestavu. Alternativně můžete vybrat šablonu sestavy (QueryId) z ukázek knihovny šablon sestav v seznamu systémových dotazů pro programový přístup k partnerským přehledům.
  2. V případě úspěchu vrátí rozhraní API pro vytvoření dotazu na sestavu hodnotu QueryId.
  3. Klientská aplikace pak musí volat rozhraní API pro vytvoření sestavy 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í.
  4. V případě úspěchu vrátí rozhraní API pro vytvoření sestavy ID sestavy.
  5. Jakmile jsou data sestavy připravená ke stažení, klientská aplikace se upozorní na adresu URL zpětného volání.
  6. Klientská aplikace pak použije rozhraní API Get Report Executions k dotazování stavu sestavy s ID sestavy a rozsahem dat.
  7. V případě úspěchu se vrátí odkaz na stažení sestavy a aplikace může zahájit stahování dat.

Specifikace dotazovacího jazyka pro 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ích dotazech najdete v tématu o specifikaci vlastních dotazů.

Vytvoření rozhraní API pro dotazování sestav

Rozhraní API pomáhá vytvářet vlastní dotazy, které definují datovou sadu, ze které se mají exportovat sloupce a metriky. Rozhraní API poskytuje flexibilitu při vytváření nové šablony pro 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 volat rozhraní API pro vytváření sestav přímo pomocí QueryIds systémových dotazů, které jsou k dispozici.

Následující příklad ukazuje, jak vytvořit vlastní dotaz pro získání 10 nejlepších zákazníků podle výnosů za poslední měsíc.

Syntaxe požadavku

Metoda Identifikátor URI žádosti
POST https://api.partnercenter.microsoft.com/insights/v1/mpn/ScheduledQueries

Hlavička požadavku

Hlavička Typ Description
Autorizace řetězec Povinná hodnota. Přístupový Azure Active Directory služby Azure AD (Azure AD). Formát je  Bearer <token> .
Typ obsahu řetězec Application/JSON

Parametr cesty

Žádné

Parametr dotazu

Žádné

Ukázková datová část požadavku

{ 
  "Name": "CustomersRevenueQuery", 
  "Description": "Query to get top 10 customers by revenue for last month", 
  "Query": "SELECT CustomerName, Product, BilledRevenueUSD FROM CustomersAndTenants ORDER BY BilledRevenueUSD LIMIT 10 TIMESPAN LAST_MONTH" 
}

Glosář

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

Parametr Povinné Popis Povolené hodnoty
Name Yes Popisný název dotazu řetězec
Popis No Popis toho, co dotaz vrátí řetězec
Dotaz Yes Řetězec dotazu sestavy Datový typ: řetězec
Vlastní dotaz na základě obchodní potřeby

Poznámka

Ukázky vlastních dotazů najdete v tématu Příklady ukázkových 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": "ec8366a4-d96e-4194-8c37-d5dbc0639033",
      "name": "CustomersRevenueQuery",
      "description": "Query to get top 10 customers by revenue for last month",
      "query": "SELECT CustomerName, Product, BilledRevenueUSD FROM CustomersAndTenants ORDER BY BilledRevenueUSD LIMIT 10 TIMESPAN LAST_MONTH",
      "type": "userDefined",
      "user": "GAUser@PITEST2.ccsctp.net", 
      "createdTime": "2021-03-30T12:52:39Z" 
    }
  ], 
  "nextLink": null,
  "totalCount": 1,
  "message": "Query created successfully",
  "statusCode": 200,
  "dataRedacted": false
} 

Glosář

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

Parametr Popis
ID dotazu Univerzálně jedinečný identifikátor (UUID) dotazu, který jste vytvořili
Name Popisný název předaný dotazu v datové části požadavku
Description Popis při vytváření dotazu
Dotaz Dotaz sestavy předaný jako vstup při vytváření dotazu
Typ Nastavte na . userDefined
Uživatel ID uživatele použité k vytvoření dotazu
CreatedTime Čas UTC vytvoření dotazu v tomto formátu: rrrr-MM-ddTHH:mm:ssZ
TotalCount Počet datových sad v poli Hodnota
Statuscode Kód výsledku
Možné hodnoty jsou 200, 400, 401, 403, 500.
zpráva Stavová zpráva z spuštění rozhraní API

Vytvoření rozhraní API pro sestavy

Po úspěšném vytvoření vlastní šablony sestavy a přijetí QueryID v rámci odpovědi create report query (Vytvořit dotaz sestavy) je možné toto rozhraní API volat a naplánovat tak spuštění dotazu v pravidelných intervalech. Můžete nastavit frekvenci a plán doručení sestavy. V případě systémových dotazů, které poskytujeme, je možné rozhraní API pro vytvoření sestavy volat také pomocí QueryId.

Adresa URL zpětného volání

Rozhraní API pro vytváření sestav přijímá adresu URL zpětného volání. Tato adresa URL bude volána, jakmile bude generování sestavy úspěšné. Adresa URL zpětného volání by měla být veřejně dosažitelná. Kromě adresy URL lze také určit metodu zpětného volání. Metoda zpětného volání může být pouze "GET" nebo "POST". Výchozí metoda, pokud není předána žádná hodnota, bude "POST". ReportId, která byla dokončená generace, bude vždy předána zpět během zpětného volání.

PO zpětném volání: Pokud byla předána adresa URL https://www.contosso.com/callback , pak se adresa URL zpětného volání. https://www.contosso.com/callback/<reportID>

ZÍSKAT zpětné volání: Pokud byla předána adresa URL https://www.contosso.com/callback , pak se adresa URL zpětného volání bude https://www.contosso.com/callback?reportId=<reportID>

Sestavy ExecuteNow

Existuje zřízení pro vygenerování sestavy bez plánování. Datová část rozhraní API pro vytvoření sestavy může přijmout parametr ExecuteNow , který bude zařadit do fronty, aby se vygenerovala hned po volání rozhraní API. Pokud ExecuteNow je nastaveno na hodnotu true, pole: StartTime , RecurrenceCount , RecurrenceInterval jsou ignorována, protože tyto sestavy nejsou naplánovány.

Další pole mohou být předána ExecuteNow , když je hodnota true QueryStartTime a QueryEndTime . Tato dvě pole přepíšou TIMESPAN pole v dotazu. Tato pole se nevztahují k plánovaným sestavám, protože data budou průběžně vygenerována po pevný časový úsek, který se nemění.

Syntaxe žádosti

Metoda Identifikátor URI žádosti
POST https://api.partnercenter.microsoft.com/insights/v1/mpn/ScheduledReport

Hlavička požadavku

Hlavička Typ Description
Autorizace řetězec Povinná hodnota. přístupový token Azure Active Directory (Azure AD). Formát je  Bearer <token> .
Typ obsahu řetězec Application/JSON

Parametr cesty

Žádné

Parametr dotazu

Žádné

Ukázková datová část požadavku

{
  "ReportName": "Top10_CustomersReport",
  "Description": "Top 10 customers by revenue for last month",
  "QueryId": "ec8366a4-d96e-4194-8c37-d5dbc0639033",
  "StartTime": "2021-03-31T18:41:00Z",
  "ExecuteNow": false,
  "QueryStartTime": null,
  "QueryEndTime": null,
  "RecurrenceInterval": 24,
  "RecurrenceCount": 100,
  "Format": "CSV",
  "CallbackUrl": "https://<SampleCallbackUrl>",
  "CallbackMethod": "GET"
}

Glosář

Klíčové definice prvků v datové části požadavku jsou kloubově navýšené:

Parametr Povinné Popis Povolené hodnoty
ReportName Yes Název, který se má přiřadit k sestavě řetězec
Popis No Popis vytvořené sestavy řetězec
QueryId Yes ID dotazu sestavy řetězec
StartTime Yes Časové razítko UTC, na kterém bude zahájeno generování sestavy.
Formát by měl být: RRRR-MM-ddTHH: mm: ssZ
řetězec
ExecuteNow No Tento parametr by se měl použít k vytvoření sestavy, která se spustí jenom jednou. StartTime, RecurrenceInterval , a RecurrenceCount jsou ignorovány, pokud je tato hodnota nastavena na true. Sestava se spustí hned asynchronním způsobem. true nebo false
QueryStartTime No Volitelně určuje počáteční čas pro dotazování extrahování dat. Tento parametr lze použít pouze pro jednorázové sestavy spuštění, které jsou ExecuteNow nastaveny na hodnotu true. Nastavují se tato přepsání parametrů TIMESPAN v dotazu. 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, který extrahuje data. Tento parametr lze použít pouze pro sestavu jednorázového spuštění, která má ExecuteNow hodnotu true. Nastavují se tato přepsání parametrů TIMESPAN v dotazu. Formát by měl být RRRR-MM-ddTHH: mm: ssZ Časové razítko jako řetězec
RecurrenceInterval Yes Frekvence vygenerování sestavy v hodinách
Minimální hodnota je 4 a maximální hodnota je 2160.
integer
RecurrenceCount No Počet sestav, které mají být vygenerovány. integer
Formát No Formát souboru exportovaného souboru
Výchozí hodnota je CSV.
"CSV"/"TSV"
CallbackUrl No Veřejně dosažitelná adresa URL, která může být volitelně nakonfigurovaná jako cíl zpětného volání Řetězec (adresa URL protokolu HTTP)
CallbackMethod No Metoda, která se má použít pro zpětné volání ZÍSKAT NEBO ZVEŘEJNIT

Ukázková odpověď

Datová část odpovědi je strukturována takto:

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

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

{ 
  "value": [
    { 
      "reportId": "d9548477-16d4-492a-bf9c-0cf91a9f69bf", 
      "reportName": "Top10_CustomersReport", 
      "description": "Top 10 customers by revenue for last month", 
      "queryId": "ec8366a4-d96e-4194-8c37-d5dbc0639033", 
      "query": "SELECT CustomerName, Product, BilledRevenueUSD FROM CustomersAndTenants ORDER BY BilledRevenueUSD LIMIT 10 TIMESPAN LAST_MONTH", 
      "user": "GAUser@PITEST2.ccsctp.net", 
      "createdTime": "2021-03-30T13:11:58Z", 
      "modifiedTime": null, 
      "executeNow": false, 
      "startTime": "2021-03-31T18:41:00Z", 
      "reportStatus": "Active", 
      "recurrenceInterval": 24, 
      "recurrenceCount": 100, 
      "callbackUrl": "https://<SampleCallbackUrl>", 
      "callbackMethod": "GET", 
      "format": "csv"
    } 
  ], 
  "nextLink": null, 
  "totalCount": 1, 
  "message": "Report created successfully", 
  "statusCode": 200, 
  "dataRedacted": false 
}

Glosář

Klíčové definice prvků v odpovědi jsou kloubově navýšené:

Parametr Popis
ReportId Univerzálně jedinečný identifikátor (UUID) sestavy, kterou jste vytvořili
ReportName Název zadaný pro sestavu v datové části požadavku
Description Popis zadaný při vytváření sestavy
QueryId ID dotazu předané v době, kdy jste sestavu vytvořili
Dotaz Text dotazu, který se spustí pro tuto sestavu
Uživatel ID uživatele, které se použilo k vytvoření sestavy
CreatedTime Čas UTC, kdy byla sestava vytvořena v tomto formátu: RRRR-MM-ddTHH: mm: ssZ
ModifiedTime Čas UTC, kdy se sestava naposledy změnila v tomto formátu: RRRR-MM-ddTHH: mm: ssZ
ExecuteNow ExecuteNow příznak nastavený v okamžiku vytvoření sestavy
StartTime Čas UTC, kdy bude spuštění sestavy začínat v tomto formátu: RRRR-MM-ddTHH: mm: ssZ
ReportStatus Stav provádění sestavy Možné hodnoty jsou Paused , Active a. Inactive
RecurrenceInterval Interval opakování zadaný při vytváření sestavy
RecurrenceCount Počet opakování poskytnutý během vytváření sestavy
CallbackUrl Adresa URL zpětného volání poskytnutá v žádosti
CallbackMethod Metoda zpětného volání poskytnutá v žádosti
Formát Formát souborů sestav Možné hodnoty jsou CSV nebo TSV .
TotalCount Počet záznamů v poli hodnot
StatusCode Kód výsledku
zpráva Možné hodnoty jsou 200, 400, 401, 403, 500. Stavová zpráva od spuštění rozhraní API

Získat rozhraní API pro spuštění sestavy

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

Důležité

Toto rozhraní API má výchozí parametry dotazu nastavené 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í 404. Nedokončené spouštění lze získat nastavením executionStatus=Pending .

Syntaxe žádosti

Metoda Identifikátor URI žádosti
GET https://api.partnercenter.microsoft.com/insights/v1/mpn/ScheduledReport/execution/{reportId}?executionId={executionId}&executionStatus={executionStatus}&getLatestExecution={getLatestExecution}

Hlavička požadavku

Hlavička Typ Description
Autorizace řetězec Povinná hodnota. přístupový token Azure Active Directory (Azure AD). Formát je  Bearer <token> .
Typ obsahu řetězec Application/JSON

Parametr cesty

Název parametru Požaduje se Typ Description
reportId Yes řetězec Filtr pro získání podrobností o spuštění pouze sestav s reportId, které jsou uvedeny v tomto argumentu. Více reportIds je možné zadat tak, že je oddělíte středníkem ";".

Parametr dotazu

Název parametru Požaduje se Typ Description
executionId No řetězec Filtr pro získání podrobností o pouze sestavách s executionId, které jsou uvedeny v tomto argumentu. Více executionIds je možné zadat tak, že je oddělíte středníkem ";".
executionStatus No Řetězec/výčet Filtr pro získání podrobností o pouze sestavách s executionStatus, které jsou uvedeny v tomto argumentu.
Platné hodnoty jsou: Pending , Running , a Paused Completed .
Výchozí hodnota je Completed.
Více stavů je možné zadat tak, že je oddělíte středníkem (;).
getLatestExecution No boolean Rozhraní API vrátí podrobnosti o posledním spuštění. Ve výchozím nastavení je tento parametr nastavený na hodnotu true.
Pokud se rozhodnete předat hodnotu tohoto parametru jako false, vrátí rozhraní API instance provádění za posledních 90 dnů.

Ukázková 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": "906931dc-4f2f-4195-bbb2-d7295c7550d3",
      "reportId": "d9548477-16d4-492a-bf9c-0cf91a9f69bf",
      "recurrenceInterval": 24,
      "recurrenceCount": 100,
      "callbackUrl": null,
      "callbackMethod": null,
      "format": "csv",
      "executionStatus": "Completed",
      "reportLocation": null,
      "reportAccessSecureLink": "https://<path to report for download>",
      "reportExpiryTime": null,
      "reportGeneratedTime": "2021-03-31T18:41:00Z"
    }
  ],
  "nextLink": null,
  "totalCount": 1,
  "message": null,
  "statusCode": 200,
  "dataRedacted": false
}

Po dokončení spuštění sestavy se zobrazí Completed stav spuštění. Sestavu si můžete stáhnout výběrem adresy URL v reportAccessSecureLink .

Glosář

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

Parametr Popis
ID spuštění Univerzálně jedinečný identifikátor (UUID) instance provádění
ID sestavy ID sestavy přidružené k instanci spuštění
OpakováníInterval Interval opakování poskytovaný během vytváření sestavy
Počet opakování Počet opakování při vytváření sestavy
CallbackUrl (Url zpětného volání) Adresa URL zpětného volání přidružená k instanci provádění
Metoda zpětného volání Metoda zpětného volání přidružená k instanci provádění
Formát Formát generovaného souboru na konci provádění
Stav spuštění Stav instance spuštění sestavy
Platné hodnoty: Pending , Running , Paused a Completed
ReportAccessSecureLink Odkaz, přes který můžete bezpečně přistupovat k sestavě
ReportExpiryTime Čas UTC, po jehož uplynutí vyprší platnost odkazu na sestavu v tomto formátu: rrrr-MM-ddTHH:mm:ssZ
ReportGeneratedTime Čas UTC, ve kterém byla sestava vygenerována v tomto formátu: rrrr-MM-ddTHH:mm:ssZ
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.
zpráva Stavová zpráva z spuštění rozhraní API

Další kroky

  • Vyzkoušejte si rozhraní API prostřednictvím adresy URL rozhraní API Swaggeru.
  • [První volání rozhraní API] (insights-programmatic-first-api-call.md