Model dostępu programowego dla komercyjnej platformy handlowej

Artykuł
06/14/2024

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 QueryID elementu 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 ID dat 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`, `RecurrenceCount`i `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`, `Paused`i `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`, `Paused`i `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.

Utwórz pierwsze wywołanie interfejsu API dla raportów usługi Marketplace Insights

Udostępnij za pośrednictwem

Model dostępu programowego dla komercyjnej platformy handlowej

Specyfikacja języka zapytań raportów

Tworzenie interfejsu API zapytania raportu

Tworzenie interfejsu API raportu

Uzyskiwanie interfejsu API wykonywania raportów

Opinia

Dodatkowe zasoby

Udostępnij za pośrednictwem

Model dostępu programowego dla komercyjnej platformy handlowej

Specyfikacja języka zapytań raportów

Tworzenie interfejsu API zapytania raportu

Tworzenie interfejsu API raportu

Uzyskiwanie interfejsu API wykonywania raportów

Powiązana zawartość

Opinia

Dodatkowe zasoby