Model dostępu programowego dla komercyjnej platformy handlowej
Na tym diagramie przedstawiono wzorzec wywołania interfejsu API używany do tworzenia nowego szablonu raportu, planowania raportu niestandardowego i pobierania danych o błędach.
Rysunek 1. Ogólny przepływ wzorca wywołania interfejsu API
Ta lista zawiera więcej szczegółów na temat rysunku 1.
- Aplikacja kliencka może zdefiniować niestandardowy schemat/szablon raportu, wywołując interfejs API tworzenia zapytania raportu. Alternatywnie możesz użyć szablonu raportu (
QueryId) z listy zapytań systemowych. - Po pomyślnych działaniach interfejs API tworzenia szablonu raportu zwraca wartość
QueryId. - Następnie aplikacja kliencka wywołuje interfejs API tworzenia raportu przy użyciu
QueryIDelementu wraz z datą rozpoczęcia raportu, interwałem powtórzenia, cyklem i opcjonalnym identyfikatorem URI wywołania zwrotnego. - Po pomyślnych działaniach interfejs API tworzenia raportu zwraca wartość
ReportID. - Aplikacja kliencka jest powiadamiana o identyfikatorze URI wywołania zwrotnego, gdy tylko dane raportu będą gotowe do pobrania.
- Następnie aplikacja kliencka używa interfejsu API Pobierz wykonania raportów do wykonywania zapytań o stan raportu z zakresem
Report IDdat i . - Po pomyślnym zakończeniu zostanie zwrócony link pobierania raportu, a aplikacja może zainicjować pobieranie danych.
Specyfikacja języka zapytań raportów
Chociaż udostępniamy zapytania systemowe, których można użyć do tworzenia raportów, możesz również tworzyć własne zapytania na podstawie potrzeb biznesowych. Aby dowiedzieć się więcej na temat zapytań niestandardowych, zobacz Custom query specification (Specyfikacja zapytania niestandardowego).
Tworzenie interfejsu API zapytania raportu
Ten interfejs API ułatwia tworzenie zapytań niestandardowych definiujących zestaw danych, z których należy eksportować kolumny i metryki. Interfejs API zapewnia elastyczność tworzenia nowego szablonu raportowania na podstawie potrzeb biznesowych.
Możesz również użyć zapytań systemowych, które udostępniamy. Gdy niestandardowe szablony raportów nie są potrzebne, możesz wywołać interfejs API tworzenia raportu bezpośrednio przy użyciu identyfikatorów QueryId zapytań systemowych, które udostępniamy.
W poniższym przykładzie pokazano, jak utworzyć zapytanie niestandardowe, aby uzyskać znormalizowane użycie i szacowane opłaty finansowe za płatne jednostki SKU z zestawu danych ISVUsage w ostatnim miesiącu.
Składnia żądania
| Method | Identyfikator URI żądania |
|---|---|
| POST | https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledQueries |
Nagłówek żądania
| Nagłówek | Type | Opis |
|---|---|---|
| Autoryzacja | string | Wymagany. Token dostępu firmy Microsoft Entra. Format to Bearer <token>. |
| Typ zawartości | string |
application/JSON |
Parametr ścieżki
Brak
Parametr zapytania
Brak
Przykład ładunku żądania
{
"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"
}
Słownik
Ta tabela zawiera kluczowe definicje elementów w ładunku żądania.
| Parametr | Wymagania | opis | Dozwolone wartości |
|---|---|---|---|
Name |
Tak | Przyjazna dla użytkownika nazwa zapytania | string |
Description |
Nie | Opis utworzonego zapytania | string |
Query |
Tak | Ciąg zapytania oparty na potrzebie biznesowej | string |
Uwaga
Aby zapoznać się z przykładami zapytań niestandardowych, zobacz przykładowe zapytania.
Przykładowa odpowiedź
Ładunek odpowiedzi jest ustrukturyzowany w następujący sposób:
Kody odpowiedzi: 200, 400, 401, 403, 500
Przykład ładunku odpowiedzi:
{
"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
}
Słownik
Ta tabela zawiera kluczowe definicje elementów w odpowiedzi.
| Parametr | Opis |
|---|---|
QueryId |
Unikatowy identyfikator (UUID) utworzonego zapytania |
Name |
Nazwa podana w ładunku żądania podczas tworzenia zapytania |
Description |
Opis podany w ładunku żądania podczas tworzenia zapytania |
Query |
Niestandardowe zapytanie raportu podane w ładunku żądania podczas tworzenia zapytania |
Type |
Ustaw wartość na userDefined dla ręcznie utworzonych zapytań |
User |
Identyfikator użytkownika używany do tworzenia zapytania |
CreatedTime |
Czas UTC utworzenia zapytania. Format: rrrr-MM-ddTHH:mm:ssZ |
TotalCount |
Liczba rekordów w tablicy Value |
StatusCode |
Kod wyniku Możliwe wartości to 200, 400, 401, 403, 500 |
message |
Komunikat o stanie z wykonania interfejsu API |
Tworzenie interfejsu API raportu
Po pomyślnym utworzeniu niestandardowego szablonu raportu i otrzymaniu QueryID go w ramach odpowiedzi Utwórz zapytanie raportu ten interfejs API może być wywoływany w celu zaplanowanego wykonania zapytania w regularnych odstępach czasu. Możesz ustawić częstotliwość i harmonogram dostarczania raportu. W przypadku zapytań systemowych, które udostępniamy, interfejs API tworzenia raportu może być również wywoływany za pomocą identyfikatora QueryId.
Składnia żądania
| Method | Identyfikator URI żądania |
|---|---|
| POST | https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledReport |
Nagłówek żądania
| Nagłówek | Type | Opis |
|---|---|---|
| Autoryzacja | string | Wymagany. Token dostępu firmy Microsoft Entra. Format to Bearer <token>. |
| Typ zawartości | string | application/JSON |
Parametr ścieżki
Brak
Parametr zapytania
Brak
Przykład ładunku żądania
{
"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",
}
Słownik
Ta tabela zawiera kluczowe definicje elementów w ładunku żądania.
| Parametr | Wymagania | opis | Dozwolone wartości |
|---|---|---|---|
ReportName |
Tak | Przyjazna dla użytkownika nazwa przypisana do raportu | String |
Description |
Nie | Opis utworzonego raportu | String |
QueryId |
Tak | Identyfikator zapytania, który musi być używany do generowania raportów | String |
StartTime |
Tak | Znacznik czasu UTC, o którym rozpocznie się generowanie raportu. Format powinien mieć format rrrr-MM-ddTHH:mm:ssZ | String |
ExecuteNow |
Nie | Ten parametr powinien służyć do tworzenia raportu, który jest wykonywany tylko raz. StartTime, RecurrenceInterval, RecurrenceCounti EndTime są ignorowane, jeśli jest ustawiona wartość true |
Wartość logiczna |
QueryStartTime |
Nie. | Opcjonalnie określa godzinę rozpoczęcia zapytania wyodrębniającego dane. Ten parametr ma zastosowanie tylko dla jednego raportu wykonywania, który ma ExecuteNow ustawioną wartość true. Format powinien mieć format rrrr-MM-ddTHH:mm:ssZ |
Znacznik czasu jako ciąg |
QueryEndTime |
Nie. | Opcjonalnie określa godzinę zakończenia zapytania wyodrębniającego dane. Ten parametr ma zastosowanie tylko dla jednego raportu wykonywania, który ma ExecuteNow ustawioną wartość true. Format powinien mieć format rrrr-MM-ddTHH:mm:ssZ |
Znacznik czasu jako ciąg |
RecurrenceInterval |
Tak | Częstotliwość w godzinach generowania raportu. Wartość minimalna to 1, a wartość maksymalna to 17520 | Liczba całkowita |
RecurrenceCount |
Tak | Liczba raportów do wygenerowania. Limit zależy od interwału cyklu | Integer |
Format |
Nie. | Format pliku wyeksportowanego. Domyślny format to CSV | CSV/TSV |
CallbackUrl |
Nie. | Publicznie dostępny adres URL, który można opcjonalnie skonfigurować jako miejsce docelowe wywołania zwrotnego | String |
CallbackMethod |
Nie | Get/Post, metoda, którą można skonfigurować przy użyciu adresu URL wywołania zwrotnego | GET/POST |
EndTime |
Tak | Sygnatura czasowa UTC, na której zakończy się generowanie raportu. Format powinien mieć format rrrr-MM-ddTHH:mm:ssZ | String |
Uwaga
Podczas tworzenia raportu EndTime albo kombinacja RecurrenceInterval elementów i RecurrenceCount jest obowiązkowa.
Przykładowa odpowiedź
Ładunek odpowiedzi jest ustrukturyzowany w następujący sposób:
Kod odpowiedzi: 200, 400, 401, 403, 404, 500
Ładunek odpowiedzi:
{
"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
}
Słownik
Ta tabela zawiera kluczowe definicje elementów w odpowiedzi.
| Parametr | Opis |
|---|---|
ReportId |
Unikatowy identyfikator (UUID) utworzonego raportu |
ReportName |
Nazwa podana w ładunku żądania podczas tworzenia raportu |
Description |
Opis podany w ładunku żądania podczas tworzenia raportu |
QueryId |
Identyfikator zapytania podany w ładunku żądania podczas tworzenia raportu |
Query |
Tekst zapytania, który zostanie wykonany dla tego raportu |
User |
Identyfikator użytkownika używany do tworzenia raportu |
CreatedTime |
Czas UTC utworzenia raportu w tym formacie: rrrr-MM-ddTHH:mm:ssZ |
ModifiedTime |
Czas UTC ostatniej modyfikacji raportu w tym formacie: rrrr-MM-ddTHH:mm:ssZ |
ExecuteNow |
Parametr ExecuteNow podany w ładunku żądania podczas tworzenia raportu |
queryStartTime |
Czas rozpoczęcia zapytania podany w ładunku żądania podczas tworzenia raportu. Ma to zastosowanie tylko wtedy, gdy ExecuteNow jest ustawiona wartość "True" |
queryEndTime |
Czas zakończenia zapytania podany w ładunku żądania podczas tworzenia raportu. Ma to zastosowanie tylko wtedy, gdy ExecuteNow jest ustawiona wartość "True" |
StartTime |
Godzina rozpoczęcia podana w ładunku żądania podczas tworzenia raportu |
ReportStatus |
Stan wykonania raportu. Możliwe wartości to Wstrzymane, Aktywne i Nieaktywne. |
RecurrenceInterval |
Interwał cyklu podany w ładunku żądania podczas tworzenia raportu |
RecurrenceCount |
Pozostała liczba cykli dla raportu |
CallbackUrl |
Adres URL wywołania zwrotnego podany w ładunku żądania podczas tworzenia raportu |
CallbackMethod |
Metoda wywołania zwrotnego podana w ładunku żądania podczas tworzenia raportu |
Format |
Format plików raportu podanych w ładunku żądania podczas tworzenia raportu |
EndTime |
Godzina zakończenia podana w ładunku żądania podczas tworzenia raportu. Ma to zastosowanie tylko wtedy, gdy ExecuteNow jest ustawiona wartość "True" |
TotalRecurrenceCount |
RecurrenceCount podany w ładunku żądania podczas tworzenia raportu |
nextExecutionStartTime |
Sygnatura czasowa UTC, kiedy rozpocznie się następne wykonanie raportu |
TotalCount |
Liczba rekordów w tablicy Value |
StatusCode |
Kod wyniku. Możliwe wartości to 200, 400, 401, 403, 500 |
message |
Komunikat o stanie z wykonania interfejsu API |
Uzyskiwanie interfejsu API wykonywania raportów
Tej metody można użyć do wykonywania zapytań o stan wykonania raportu przy użyciu odebranego ReportId z interfejsu API tworzenia raportu. Metoda zwraca link pobierania raportu, jeśli raport jest gotowy do pobrania. W przeciwnym razie metoda zwraca stan. Możesz również użyć tego interfejsu API, aby pobrać wszystkie wykonania, które wystąpiły dla danego raportu.
Ważne
Ten interfejs API ma domyślne parametry zapytania ustawione dla executionStatus=Completed parametrów i getLatestExecution=true. W związku z tym wywołanie interfejsu API przed pierwszym pomyślnym wykonaniem raportu zwróci wartość 404. Oczekujące wykonania można uzyskać, ustawiając wartość executionStatus=Pending.
Składnia żądania
| Method | Identyfikator URI żądania |
|---|---|
| Get | https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledReport/execution/{reportId}?executionId={executionId}&executionStatus={executionStatus}&getLatestExecution={getLatestExecution} |
Nagłówek żądania
| Nagłówek | Type | Opis |
|---|---|---|
| Autoryzacja | string | Wymagany. Token dostępu firmy Microsoft Entra. Format to Bearer <token>. |
| Typ zawartości | string | application/json |
Parametr ścieżki
Brak
Parametr zapytania
| Nazwa parametru | Wymagania | Type | Opis |
|---|---|---|---|
reportId |
Tak | string | Filtruj, aby uzyskać szczegółowe informacje o wykonywaniu tylko raportów z podanymi reportId w tym argumencie. |
executionId |
Nie. | string | Filtruj, aby uzyskać szczegółowe informacje dotyczące tylko raportów z podanymi executionId w tym argumencie. Wiele executionIds można określić, oddzielając je średnikiem ";". |
executionStatus |
Nie. | ciąg/wyliczenie | Filtruj, aby uzyskać szczegółowe informacje dotyczące tylko raportów z podanymi executionStatus w tym argumencie.Prawidłowe wartości to: Pending, Running, Pausedi Completed Domyślna wartość to Completed. |
getLatestExecution |
Nie. | boolean | Interfejs API zwróci szczegóły najnowszego wykonania raportu. Domyślnie ten parametr ma wartość true. Jeśli zdecydujesz się przekazać wartość tego parametru jako false, interfejs API zwróci ostatnie 90 dni wystąpień wykonywania. |
Ładunek żądania
Brak
Przykładowa odpowiedź
Ładunek odpowiedzi jest ustrukturyzowany w następujący sposób:
Kody odpowiedzi: 200, 400, 401, 403, 404, 500
Przykład ładunku odpowiedzi:
{
"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 zakończeniu wykonywania raportu wyświetlany jest stan Completed wykonania. Raport można pobrać, wybierając adres URL w pliku reportAccessSecureLink.
Słownik
Kluczowe definicje elementów w odpowiedzi.
| Parametr | Opis |
|---|---|
ExecutionId |
Unikatowy identyfikator (UUID) wystąpienia wykonywania |
ReportId |
Identyfikator raportu skojarzony z wystąpieniem wykonywania |
RecurrenceInterval |
Interwał cyklu udostępniany podczas tworzenia raportu |
RecurrenceCount |
Liczba cykli podana podczas tworzenia raportu |
CallbackUrl |
Adres URL wywołania zwrotnego skojarzony z wystąpieniem wykonywania |
CallbackMethod |
Metoda wywołania zwrotnego podana w ładunku żądania podczas tworzenia raportu |
Format |
Format wygenerowanego pliku na końcu wykonywania |
ExecutionStatus |
Stan wystąpienia wykonywania raportu. Prawidłowe wartości to: Pending, Running, Pausedi Completed |
ReportLocation |
Lokalizacja, w której jest pobierany raport. |
ReportAccessSecureLink |
Łącze, za pomocą którego można bezpiecznie uzyskać dostęp do raportu |
ReportExpiryTime |
Czas UTC, po którym link raportu wygaśnie w tym formacie: rrrr-MM-ddTHH:mm:ssZ |
ReportGeneratedTime |
Czas UTC, o którym raport został wygenerowany w tym formacie: rrrr-MM-ddTHH:mm:ssZ |
EndTime |
Godzina zakończenia podana w ładunku żądania podczas tworzenia raportu. Ma to zastosowanie tylko wtedy, gdy ExecuteNow jest ustawiona wartość "True" |
TotalRecurrenceCount |
RecurrenceCount podany w ładunku żądania podczas tworzenia raportu |
nextExecutionStartTime |
Sygnatura czasowa UTC, kiedy rozpocznie się następne wykonanie raportu |
TotalCount |
Liczba zestawów danych w tablicy Value |
StatusCode |
Kod wyniku Możliwe wartości to 200, 400, 401, 403, 404 i 500 |
message |
Komunikat o stanie z wykonania interfejsu API |
Następne kroki
- Interfejsy API można wypróbować za pomocą adresu URL interfejsu API programu Swagger
- Utwórz pierwsze wywołanie interfejsu API dla raportów Szczegółowe informacje witryny Marketplace
Opinia
Dostępne już wkrótce: W 2024 r. będziemy stopniowo wycofywać zgłoszenia z serwisu GitHub jako mechanizm przesyłania opinii na temat zawartości i zastępować go nowym systemem opinii. Aby uzyskać więcej informacji, sprawdź: https://aka.ms/ContentUserFeedback.
Prześlij i wyświetl opinię dla