Udostępnij za pośrednictwem


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.

Ilustruje wzorzec wywołania interfejsu API używany do tworzenia nowego szablonu raportu, planowania raportu niestandardowego i pobierania danych niepowodzenia.Rysunek 1. Ogólny przepływ wzorca wywołania interfejsu API

Ta lista zawiera więcej szczegółów na temat rysunku 1.

  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.
  2. Po pomyślnych działaniach interfejs API tworzenia szablonu raportu zwraca wartość QueryId.
  3. Następnie aplikacja kliencka wywołuje interfejs API tworzenia raportu przy użyciu QueryID elementu wraz z datą rozpoczęcia raportu, interwałem powtórzenia, cyklem i opcjonalnym identyfikatorem URI wywołania zwrotnego.
  4. Po pomyślnych działaniach interfejs API tworzenia raportu zwraca wartość ReportID.
  5. Aplikacja kliencka jest powiadamiana o identyfikatorze URI wywołania zwrotnego, gdy tylko dane raportu będą gotowe do pobrania.
  6. Następnie aplikacja kliencka używa interfejsu API Pobierz wykonania raportów do wykonywania zapytań o stan raportu z zakresem Report ID dat i .
  7. 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

Interfejsy API można wypróbować za pomocą adresu URL interfejsu API programu Swagger.