Programlı erişim paradigması

Bu diyagram, yeni bir rapor şablonu oluşturmak, özel raporu zamanlamak ve hata verilerini almak için kullanılan API çağrı modelini gösterir.

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

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

1. Istemci uygulaması, rapor sorgusu oluştur API'sini çağırarak özel rapor şemasını/şablonunu tanımlayabilir. Alternatif olarak, iş ortağı öngörüleri programlı erişim için sistem sorguları listesindekirapor şablonu kitaplık örneklerinden bir rapor şablonu (QueryId) seçebilirsiniz.
2. Başarılı olduğunda rapor sorgusu oluştur API 'SI QueryId döndürür.
3. Daha sonra istemci uygulamasının rapor başlangıç tarihi, yineleme aralığı, yinelenme ve isteğe bağlı bir geri çağırma URI 'SI ile birlikte QueryId kullanarak rapor oluşturma API 'sini çağırması gerekir.
4. Başarı durumunda rapor oluşturma API 'Si REPORTID ' yi döndürür.
5. İstemci uygulaması, rapor verileri indirilmeye uygun hale geldiğinde geri çağırma URL 'sinden bildirim alır.
6. İstemci uygulaması daha sonra rapor KIMLIĞI ve tarih aralığı ile raporun durumunu sorgulamak için rapor yürütmeleri al API 'sini kullanır.
7. Başarı durumunda, rapor indirme bağlantısı döndürülür ve uygulama verilerin indirilmesini başlatabilir.

Rapor sorgusu dil belirtimi

Raporları oluşturmak için kullanabileceğiniz Sistem sorguları sağlamamız sırasında, iş gereksinimlerinize göre kendi sorgularınızı de oluşturabilirsiniz. Özel sorgular hakkında daha fazla bilgi için bkz. özel sorgu belirtimi.

Rapor sorgu API 'SI oluştur

API, hangi sütunların ve ölçümlerin verilmesi 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ğini sağlar.

Sağladığımız sistem sorgularını da kullanabilirsiniz. Özel rapor şablonları gerekli olmadığında, sağlanmış sistem sorgularının QueryIds değerlerini kullanarak doğrudan Create Report API çağırabilirsiniz.

Aşağıdaki örnek, son ayın gelirine göre ilk 10 müşteriyi almak için özel bir sorgu oluşturmayı gösterir.

İstek sözdizimi

İstek üst bilgisi

Yol parametresi

Hiçbiri

Sorgu parametresi

Hiçbiri

Örnek istek yükü

{
  "Name": "CustomersRevenueQuery",
  "Description": "Query to get top 10 customers by revenue for last month",
  "Query": "SELECT CustomerName, Product, BilledRevenueUSD FROM CustomersAndTenants ORDER BY BilledRevenueUSD LIMIT 10 TIMESPAN LAST_MONTH"
}

Sözlük

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

Örnek yanıt

Yanıt yükü aşağıdaki şekilde yapılandırılır:

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

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

{
  "value": [
    {
      "queryId": "ec8366a4-d96e-4194-8c37-d5dbc0639033",
      "name": "CustomersRevenueQuery",
      "description": "Query to get top 10 customers by revenue for last month",
      "query": "SELECT CustomerName, Product, BilledRevenueUSD FROM CustomersAndTenants ORDER BY BilledRevenueUSD LIMIT 10 TIMESPAN LAST_MONTH",
      "type": "userDefined",
      "user": "GAUser@PITEST2.ccsctp.net",
      "createdTime": "2021-03-30T12:52:39Z"
    }
  ],
  "nextLink": null,
  "totalCount": 1,
  "message": "Query created successfully",
  "statusCode": 200,
  "dataRedacted": false
}

Sözlük

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

Rapor API 'SI oluştur

Özel rapor şablonu oluşturma ve sorgu yanıtı oluşturma ' nın bir parçası olarak QueryId alma sırasında, bu API, düzenli aralıklarla yürütülecek bir sorgu zamanlamak için çağrılabilir. Raporun teslim edileceği sıklığı ve zamanlamayı ayarlayabilirsiniz. Sağladığımız sistem sorguları için, rapor oluşturma API 'SI de QueryIdile çağrılabilir.

Geri Çağırma URL’si

Rapor oluşturma API 'si bir geri çağırma URL 'sini kabul eder. Bu URL, rapor oluşturma işlemi başarılı olduktan sonra çağrılacaktır. Geri çağırma URL 'SI genel olarak erişilebilir olmalıdır. URL 'ye ek olarak, bir geri çağırma yöntemi de verilebilir. Geri çağırma yöntemi yalnızca "GET" veya "POST" olabilir. Hiçbir değer geçirilmezse, varsayılan yöntem "POST" olacaktır. Oluşturmayı tamamlamış olan REPORTID, her zaman geri arama sırasında geri geçirilir.

Geri arama gönder: geçirilen URL Ise https://www.contosso.com/callback , çağrılan geri URL 'si https://www.contosso.com/callback/<reportID>

Geri arama al: geçilen URL Ise https://www.contosso.com/callback , çağrılan geri URL 'si https://www.contosso.com/callback?reportId=<reportID>

ExecuteNow raporları

Zamanlama olmadan rapor oluşturmak için bir sağlama vardır. Rapor oluşturma API 'si yükü, ExecuteNow API çağrıldıktan hemen sonra raporun oluşturulmasını sıraya alacak bir parametreyi kabul edebilir. ExecuteNowTrue olarak ayarlandığında, StartTimeRecurrenceCountRecurrenceInterval Bu raporlar zamanlanmadığından alanlar:, yok sayılır.

True olduğunda iki ek alan geçirilebilir ExecuteNowQueryStartTime ve QueryEndTime . Bu iki alan, TIMESPAN sorgudaki alanı geçersiz kılar. Bu alanlar, değişiklik olmayan sabit bir zaman dilimi için sürekli olarak oluşturulan veriler, zamanlanan raporlar için geçerli değildir.

İstek sözdizimi

İstek üst bilgisi

Yol parametresi

Hiçbiri

Sorgu parametresi

Hiçbiri

Örnek istek yükü

{
  "ReportName": "Top10_CustomersReport",
  "Description": "Top 10 customers by revenue for last month",
  "QueryId": "ec8366a4-d96e-4194-8c37-d5dbc0639033",
  "StartTime": "2021-03-31T18:41:00Z",
  "ExecuteNow": false,
  "QueryStartTime": null,
  "QueryEndTime": null,
  "RecurrenceInterval": 24,
  "RecurrenceCount": 100,
  "Format": "CSV",
  "CallbackUrl": "https://<SampleCallbackUrl>",
  "CallbackMethod": "GET"
}

Sözlük

İstek yükünde öğelerin temel tanımları aşağıda verilmiştir:

Örnek yanıt

Yanıt yükü aşağıdaki şekilde yapılandırılır:

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

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

{
  "value": [
    {
      "reportId": "d9548477-16d4-492a-bf9c-0cf91a9f69bf",
      "reportName": "Top10_CustomersReport",
      "description": "Top 10 customers by revenue for last month",
      "queryId": "ec8366a4-d96e-4194-8c37-d5dbc0639033",
      "query": "SELECT CustomerName, Product, BilledRevenueUSD FROM CustomersAndTenants ORDER BY BilledRevenueUSD LIMIT 10 TIMESPAN LAST_MONTH",
      "user": "GAUser@PITEST2.ccsctp.net",
      "createdTime": "2021-03-30T13:11:58Z",
      "modifiedTime": null,
      "executeNow": false,
      "startTime": "2021-03-31T18:41:00Z",
      "reportStatus": "Active",
      "recurrenceInterval": 24,
      "recurrenceCount": 100,
      "callbackUrl": "https://<SampleCallbackUrl>",
      "callbackMethod": "GET",
      "format": "csv"
    }
  ],
  "nextLink": null,
  "totalCount": 1,
  "message": "Report created successfully",
  "statusCode": 200,
  "dataRedacted": false
}

Sözlük

Yanıttaki öğelerin temel tanımları aşağıda verilmiştir:

Rapor yürütme API 'sini al

Rapor oluşturma API'Sinden alınan REPORTID kullanarak rapor yürütmenin durumunu sorgulamak için bu yöntemi kullanabilirsiniz. Rapor indirmeye hazırsanız, yöntemi rapor indirme bağlantısını döndürür. Aksi takdirde, yöntemi durumu döndürür. Belirli bir rapor için gerçekleşen tüm yürütmeleri almak için bu API 'yi de kullanabilirsiniz.

İstek sözdizimi

İstek üst bilgisi

Yol parametresi

Sorgu parametresi

Örnek Istek yükü

Hiçbiri

Örnek Yanıt

Yanıt yükü aşağıdaki şekilde yapılandırılır:

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

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

{
  "value": [
    {
      "executionId": "906931dc-4f2f-4195-bbb2-d7295c7550d3",
      "reportId": "d9548477-16d4-492a-bf9c-0cf91a9f69bf",
      "recurrenceInterval": 24,
      "recurrenceCount": 100,
      "callbackUrl": null,
      "callbackMethod": null,
      "format": "csv",
      "executionStatus": "Completed",
      "reportLocation": null,
      "reportAccessSecureLink": "https://<path to report for download>",
      "reportExpiryTime": null,
      "reportGeneratedTime": "2021-03-31T18:41:00Z"
    }
  ],
  "nextLink": null,
  "totalCount": 1,
  "message": null,
  "statusCode": 200,
  "dataRedacted": false
}

Rapor yürütme tamamlandıktan sonra, yürütme durumu Completed gösterilir. İçindeki URL 'YI seçerek raporu indirebilirsiniz reportAccessSecureLink .

Sözlük

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

Sonraki adımlar

• Swagger API URL 'si aracılığıyla API 'leri deneyin
• [İlk API çağrısını yapın] (insights-programmatic-first-api-call.md