Ticari market için programlı erişim paradigması

Bu diyagramda yeni bir rapor şablonu oluşturmak, özel raporu zamanlamak ve hata verilerini almak için kullanılan API çağrı düzeni gösterilir.

Şekil 1: API çağrı deseninin üst düzey akışı

Bu liste Şekil 1 hakkında daha fazla ayrıntı sağlar.

1. İstemci Uygulaması, Rapor Sorgusu Oluşturma API'siniçağırarak özel rapor şemasını/şablonunu tanımlayabilir. Alternatif olarak, sistem sorgularınınlistesinden bir rapor şablonu (QueryId) kullanabilirsiniz.
2. Başarılı olduğunda Rapor Şablonu Oluştur API'si QueryIddöndürür.
3. İstemci uygulaması daha sonra rapor başlangıç tarihi, Yineleme Aralığı, Yineleme ve isteğe bağlı geri çağırma URI'siyle birlikte QueryID kullanarak Rapor Oluşturma API'sini çağırır.
4. Başarıyla tamamlanırsa, Rapor Oluşturma API, ReportIDdöndürür.
5. rapor verileri indirilmeye hazır olur olmaz istemci uygulamasına geri çağırma URI'sinde bildirim gönderilir.
6. İstemci uygulaması daha sonra raporun durumunu Report ID ve tarih aralığıyla sorgulamak için Rapor Yürütmelerini Alma API'sini kullanır.
7. Başarılı olduğunda rapor indirme bağlantısı döndürülür ve uygulama verilerin indirilmesini başlatabilir.

Rapor sorgu dili belirtimi

Rapor oluşturmak için kullanabileceğiniz sistem sorguları sağlarken, iş gereksinimlerinize göre kendi sorgularınızı da oluşturabilirsiniz. Özel sorgular hakkında daha fazla bilgi edinmek için bkz. Özel sorgu belirtimi.

Rapor sorgusu API'si oluşturma

Bu API, sütunların ve ölçümlerin dışarı aktarılması gereken veri kümesini tanımlayan özel sorgular oluşturmaya yardımcı olur. API, iş gereksinimlerinize göre yeni bir raporlama şablonu oluşturma esnekliği sağlar.

Sağladığımız sistem sorgularını da kullanabilirsiniz. Özel rapor şablonlarına ihtiyaç duyulmadığında, sağladığımız sistem sorgularının QueryIds kullanarak Rapor Oluşturma API'sini doğrudan çağırabilirsiniz.

Aşağıdaki örnekte, geçen aya ait ISVUsage veri kümesinden Normalleştirilmiş Kullanım ve ÜCRETLİ SKU'lar için Tahmini Finansal Ücretler almak için nasıl özel sorgu oluşturulacağı gösterilmektedir.

İstek sözdizimi

İstek başlığı

yol parametresi

Hiç kimse

sorgu parametresi

Hiç kimse

İstek yükü örneği

{
    "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özlük

Bu tablo, istek yükündeki öğelerin anahtar tanımlarını sağlar.

Örnek yanıt

Yanıt yükü aşağıdaki gibi yapılandırılmıştır:

Yanıt kodları: 200, 400, 401, 403, 500

Yanıt yükü örneği:

{
  "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özlük

Bu tablo yanıttaki öğelerin anahtar tanımlarını sağlar.

Rapor API'si oluşturma

Özel bir rapor şablonunu başarıyla oluşturduktan ve Rapor Sorgusu Oluşturma yanıtının bir parçası olarak QueryID aldıktan sonra, düzenli aralıklarla yürütülecek bir sorguyu zamanlamak için bu API çağrılabilir. Raporun teslim edilmesi için bir sıklık ve zamanlama ayarlayabilirsiniz. Sağladığımız sistem sorguları için Rapor Oluştur API'sini QueryIdile de çağırabilirsiniz.

İstek sözdizimi

İstek üst bilgisi

yol parametresi

Hiç kimse

sorgu parametresi

Hiç kimse

İstek yükü örneği

{
  "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özlük

Bu tablo, istek yükündeki öğelerin anahtar tanımlarını sağlar.

Örnek yanıt

Yanıt yükü aşağıdaki gibi yapılandırılmıştır:

Yanıt kodu: 200, 400, 401, 403, 404, 500

Yanıt yükü:

{
  "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özlük

Bu tablo yanıttaki öğelerin anahtar tanımlarını sağlar.

Rapor yürütmeleri API'lerini alma

ReportId alarak Rapor Oluşturma API'si üzerinden rapor yürütme durumunu sorgulamak için bu yöntemi kullanabilirsiniz. Yöntem, rapor indirme için hazırsa rapor indirme bağlantısını döndürür. Aksi takdirde yöntem durumu döndürür. Bu API'yi belirli bir rapor için gerçekleşen tüm yürütmeleri almak için de kullanabilirsiniz.

İstek sözdizimi

İstek üst bilgisi

yol parametresi

Hiç kimse

sorgu parametresi

İstek yükü

Hiç kimse

Örnek yanıt

Yanıt yükü aşağıdaki gibi yapılandırılmıştır:

Yanıt kodları: 200, 400, 401, 403, 404, 500

Yanıt yükü örneği:

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

Rapor yürütme tamamlandıktan sonra yürütme durumu Completed gösterilir. reportAccessSecureLinkURL'yi seçerek raporu indirebilirsiniz.

Sözlük

Yanıttaki öğelerin anahtar tanımları.

API'leri Swagger API URL'siaracılığıyla deneyebilirsiniz.

İlgili içerik

• Marketplace Insights raporları için ilk API çağrınızı yapın