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.

1. Aplikacja kliencka może zdefiniować niestandardowy schemat/szablon raportu, wywołując interfejs API tworzenia zapytań raportu . Alternatywnie można użyć szablonu raportu (QueryId) z listy zapytań systemowych.
2. Po pomyślnym zakończeniu, interfejs API Create Report Template zwraca QueryId.
3. Następnie aplikacja kliencka wywołuje interfejs API tworzenia raportu przy użyciu QueryID wraz z datą rozpoczęcia raportu, interwałem powtórzenia, cyklem i opcjonalnym identyfikatorem URI wywołania zwrotnego.
4. W przypadku powodzenia interfejs API tworzenia raportu zwraca ReportID.
5. Aplikacja kliencka jest powiadamiana poprzez adres URI wywołania zwrotnego, jak tylko dane raportu będą gotowe do pobrania.
6. Następnie aplikacja kliencka używa interfejsu API Get Report Executions, aby zapytać o stan raportu przy użyciu Report ID i zakresu dat.
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óre 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 o zapytaniach niestandardowych, zobacz specyfikację zapytań niestandardowych.

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ń systemu , które udostępniamy. Gdy niestandardowe szablony raportów nie są potrzebne, możesz wywołać interfejs API tworzenia raportów bezpośrednio przy użyciu QueryIds 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

nagłówek żądania

parametr ścieżki

Żaden

parametr zapytania

Żaden

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"
}

Glosariusz

Ta tabela zawiera kluczowe definicje elementów w ładunku żądania.

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
}

Glosariusz

Ta tabela zawiera kluczowe definicje elementów w odpowiedzi.

Utwórz API raportu

Po pomyślnym utworzeniu niestandardowego szablonu raportu i otrzymaniu QueryID w ramach odpowiedzi na Utwórz Zapytanie Raportu, ten interfejs API można wywołać, aby zaplanować wykonywanie zapytania w regularnych odstępach czasu. Możesz ustawić częstotliwość i harmonogram dostarczania raportu. W przypadku kwerend systemowych można również wywołać interfejs API tworzenia raportu za pomocą QueryId.

Składnia żądania

Nagłówek żądania

parametr ścieżki

Żaden

parametr zapytania

Żaden

przykład danych żą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.

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.

Uzyskaj dostęp do interfejsu API wykonywania raportów

Za pomocą tej metody można wykonywać zapytania o stan wykonania raportu używając ReportId otrzymanych z API do tworzenia raportów. 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 uzyskać wszystkie wykonania związane z danym raportem.

Składnia żądania

Nagłówek żądania

parametr ścieżki

Żaden

parametr zapytania

treść żądania

Żaden

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 wykonania Completed. Raport można pobrać, wybierając adres URL w reportAccessSecureLink.

Słownik

Kluczowe definicje elementów w odpowiedzi.

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

Powiązana zawartość

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