# BI veri kümeleri (https://docs.akollo.com/tr/connections/bi-datasets) Raporlama, üzerinde anlaşılmış rakamları veri kümeleri halinde yayımlar; örneğin kişi ve gün bazında onaylı saatler. Bir iş zekâsı aracı (Power BI, Tableau, Looker Studio ya da kendi betiğiniz) bu kümeleri bir API anahtarıyla genel API üzerinden okur. Rakamlar Akollo raporlarındakilerle aynıdır. Araç yalnızca okur; Akollo'da hiçbir şeyi değiştirmez. ## 1. Anahtar oluşturun [#1-anahtar-oluşturun] ### API anahtarları sayfasını açın [#api-anahtarları-sayfasını-açın] **Entegrasyonlar → API anahtarları** sayfasına gidin. ### Anahtara ad verin [#anahtara-ad-verin] Anahtara, onu hangi aracın kullandığını anlatan bir ad verin; örneğin "Power BI – finans çalışma alanı". ### Servis hesabını seçin [#servis-hesabını-seçin] Aracın adına çalışacağı **Servis hesabı**’nı seçin. Bu hesabın rapor veri kümelerini okuma izni olmalıdır. ### Kapsamı belirleyin [#kapsamı-belirleyin] **Kapsamlar** bölümünde **reports.dataset** (BI veri kümeleri, yalnızca okuma) için **Okuma**’yı seçin. Araç başka kayıtlara da ihtiyaç duymuyorsa diğer kapsamları **Yok** olarak bırakın. ### Son kullanma tarihini ve adresleri girin [#son-kullanma-tarihini-ve-adresleri-girin] Bir son kullanma tarihi girin. Araç hep aynı adreslerden bağlanıyorsa bu adresleri de yazın. ### Anahtarı kopyalayın [#anahtarı-kopyalayın] Anahtar gösterildiğinde kopyalayın; yalnızca bir kez gösterilir. Yalnızca bu kapsama sahip bir anahtar projeleri, görevleri ya da kişileri okuyamaz, hiçbir şeyi de değiştiremez. ## 2. Veri kümelerini listeleyin [#2-veri-kümelerini-listeleyin] ```bash curl https:///api/public/v1/datasets \ -H "Authorization: Bearer " \ -H "Akollo-Version: 2026-09-24" ``` Yanıt, anahtarın okuyabildiği her veri kümesini sürümüyle birlikte listeler: ```json { "data": [ { "key": "hours.daily", "version": 2 } ] } ``` Bir veri kümesinin sütunları değiştiğinde sürümü bir artar. Liste boş geliyorsa kurumunuz bu anahtarın servis hesabına henüz bir veri kümesi açmamıştır; raporlama yöneticinizden erişim isteyin. ## 3. Satırları sayfa sayfa okuyun [#3-satırları-sayfa-sayfa-okuyun] ```bash curl "https:///api/public/v1/datasets/hours.daily/rows" \ -H "Authorization: Bearer " \ -H "Akollo-Version: 2026-09-24" ``` ```json { "data": [ { "person": "…", "date": "2026-09-01", "approved_hours": 7.5 } ], "has_more": true, "next_cursor": "eyJ…", "dataset": { "key": "hours.daily", "version": 2 } } ``` * Her satır düz bir kayıttır. Bir değer metin, sayı, doğru/yanlış ya da boş olabilir. * `has_more` doğru olduğu sürece `?cursor=` ile yeniden isteyin. Yanıttaki `rel="next"` içeren `Link` başlığı da aynı adresi taşır; onu olduğu gibi izleyebilirsiniz. * Bir sayfada kaç satır olacağına raporlama karar verir. Akış `limit`, `$top` ya da `$select` kabul etmez. * Veri kümesinin yalnızca bir kısmını okumak için `$filter` ekleyin (aşağıda). Her sayfada aynı `$filter`'ı gönderin; `Link` başlığındaki adres onu zaten taşır. * Bir imleç tek bir veri kümesine, tek bir sürüme, tek bir `$filter`'a ve onu alan anahtara aittir. Siz sayfaları okurken veri kümesinin sürümü değişirse ya da imleci başka bir anahtarla gönderirseniz (örneğin anahtarı yeniledikten sonra) sonraki çağrı `400 CURSOR_INVALID` döner; ilk sayfadan yeniden başlayın. ### `$filter` ile süzme [#filter-ile-süzme] `$filter`, raporlamanın anahtara zaten açtığı satırları daraltır; hiçbir zaman genişletmez. `and` ile bağlanmış karşılaştırmalardan oluşur: ``` and … ``` * Sütunlar veri kümesinin kendi sütun adlarıdır (satırlarda göründüğü gibi, küçük harfle). * İşleçler: `eq` (eşit), `ne` (eşit değil), `gt`, `ge`, `lt`, `le` (büyük, büyük ya da eşit, küçük, küçük ya da eşit). Yalnızca küçük harf. * Değerler: tek tırnak içinde metin (metnin içindeki tırnağı iki tırnak olarak yazın: `'O''Brien'`), tam sayılar (`600`, `-15`), `true`, `false`, `null` (yalnızca `eq` ya da `ne` ile) ve tırnaksız `YYYY-AA-GG` biçiminde tarihler. * En çok 8 karşılaştırma ve 1 024 karakter. `or`, `not`, parantez ve işlevler desteklenmez. Örnekler (adresi oluştururken değeri URL kodlamasıyla yazın): ``` $filter=local_date ge 2026-09-01 and local_date lt 2026-10-01 $filter=team_id eq '018f0000-0000-7000-8000-000000000001' $filter=local_date ge 2026-09-01 and employee_count gt 5 ``` Veri kümesinde olmayan bir sütunu adlandıran ya da bir sütunu yanlış türde bir değerle karşılaştıran süzgeç `400 VALIDATION_FAILED` döner. ### Bir çağrı reddedildiğinde [#bir-çağrı-reddedildiğinde] | Yanıt | Anlamı | Ne yapmalı | | -------------------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | `401` | Anahtar tanınmıyor, süresi dolmuş ya da iptal edilmiş | Yeni bir anahtar oluşturun ya da anahtarı yenileyin | | `403 SCOPE_MISSING` | Anahtarda BI veri kümeleri kapsamı yok ya da servis hesabı okuma iznini kaybetmiş | Anahtarın kapsamlarını ve servis hesabının rolünü kontrol edin | | `404 NOT_FOUND` | Veri kümesi yok ya da bu anahtar onu okuyamıyor | Veri kümesi anahtarını listeyle karşılaştırın | | `400 VALIDATION_FAILED` | `limit` gibi desteklenmeyen bir sorgu parametresi ya da yukarıdaki kurallara uymayan bir `$filter` gönderilmiş | Yalnızca `cursor` ve `$filter` gönderin; süzgecin sütunlarını ve değerlerini denetleyin | | `400 CURSOR_INVALID` | İmleç bozulmuş, başka bir anahtarla alınmış ya da veri kümesinin sürümü değişmiş | İlk sayfadan yeniden başlayın | | `429` | Bir dakikada çok fazla çağrı yapılmış | `Retry-After` başlığındaki süre kadar bekleyin | | `502 integrations.bi.feed_drift` | Raporlamadan beklenmeyen biçimde veri gelmiş; hiçbir satır gönderilmemiş | Daha sonra yeniden deneyin; sürerse Akollo yöneticinize haber verin | | `503 integrations.bi.feed_unavailable` | Kurumunuzda raporlama kapalı | Daha sonra yeniden deneyin | ## Power BI Desktop [#power-bi-desktop] **Veri al → Boş sorgu**'yu seçin, Gelişmiş Düzenleyici'yi açın ve aşağıdaki sorguyu yapıştırın. Adresi, veri kümesi anahtarını ve API anahtarını yerine yazın. Power BI hizmetinde zamanlanmış yenileme için adresi aşağıdaki gibi `Web.Contents`'in ilk bağımsız değişkeninde, yolu da `RelativePath`'te tutun ve veri kaynağının kimlik bilgisini **Anonim** yapın; anahtar zaten başlıkta gidiyor. ```powerquery let Host = "https://", Dataset = "hours.daily", ApiKey = "", GetPage = (cursor as nullable text) => Json.Document( Web.Contents( Host, [ RelativePath = "api/public/v1/datasets/" & Dataset & "/rows", Query = if cursor = null then [] else [cursor = cursor], Headers = [Authorization = "Bearer " & ApiKey, #"Akollo-Version" = "2026-09-24"] ] ) ), Pages = List.Generate( () => GetPage(null), each _ <> null, each if _[has_more] then GetPage(_[next_cursor]) else null ), Rows = List.Combine(List.Transform(Pages, each _[data])), Result = Table.FromRecords(Rows, null, MissingField.UseNull) in Result ``` Rapor dosyası başkalarıyla paylaşılacaksa anahtarı sorgu metnine yazmak yerine bir Power BI parametresinde saklayın. ## Tableau [#tableau] Tableau akışı iki yoldan biriyle okuyabilir. * **Web Data Connector.** Küçük bir bağlayıcı sayfası aynı iki adresi çağırır: tablo seçicisi için veri kümelerini listeler, satırları da `next_cursor`'ı izleyerek sayfa sayfa okur. Anahtar sayfanın içine değil, bağlayıcının kimlik doğrulama adımına girilir. * **Zamanlanmış özet (extract).** Bir betik tüm sayfaları bir CSV dosyasına (ya da Tableau'nun Hyper API'siyle bir Hyper dosyasına) yazar; Tableau Server ya da Tableau Cloud özeti bu dosyadan belirli aralıklarla yeniler. Örneğin: ```python import csv, os, requests host = "https://" headers = {"Authorization": f"Bearer {os.environ['AKOLLO_API_KEY']}", "Akollo-Version": "2026-09-24"} url = f"{host}/api/public/v1/datasets/hours.daily/rows" rows, cursor = [], None while True: page = requests.get(url, headers=headers, params={"cursor": cursor} if cursor else None, timeout=60) page.raise_for_status() body = page.json() rows.extend(body["data"]) if not body["has_more"]: break cursor = body["next_cursor"] with open("hours_daily.csv", "w", newline="", encoding="utf-8") as file: columns = sorted({name for row in rows for name in row}) writer = csv.DictWriter(file, fieldnames=columns) writer.writeheader() writer.writerows(rows) ``` Anahtarı betik dosyasında değil, ortam değişkeninde ya da bir sır kasasında tutun. ## Looker Studio [#looker-studio] Looker Studio akışı iki yoldan biriyle okuyabilir. * **Topluluk bağlayıcısı.** Bir Apps Script bağlayıcısı aynı adresleri çağırır, kimlik doğrulama adımında anahtarı ister (anahtar türü) ve satırları `next_cursor`'ı izleyerek sayfa sayfa okur. * **Zamanlanmış Google E-Tablolar.** Bir e-tablodaki Apps Script, zamana bağlı bir tetikleyiciyle satırları okuyup bir sekmeye yazar; Looker Studio da kaynak olarak bu e-tabloyu kullanır. Örneğin: ```javascript function pullAkollo() { const key = PropertiesService.getScriptProperties().getProperty('AKOLLO_API_KEY'); const base = 'https:///api/public/v1/datasets/hours.daily/rows'; const headers = { Authorization: 'Bearer ' + key, 'Akollo-Version': '2026-09-24' }; let rows = []; let cursor = null; do { const url = cursor ? base + '?cursor=' + encodeURIComponent(cursor) : base; const body = JSON.parse(UrlFetchApp.fetch(url, { headers: headers }).getContentText()); rows = rows.concat(body.data); cursor = body.has_more ? body.next_cursor : null; } while (cursor); const columns = [...new Set(rows.flatMap((row) => Object.keys(row)))]; const sheet = SpreadsheetApp.getActive().getSheetByName('hours.daily'); sheet.clearContents(); sheet.getRange(1, 1, 1, columns.length).setValues([columns]); if (rows.length > 0) { sheet .getRange(2, 1, rows.length, columns.length) .setValues(rows.map((row) => columns.map((name) => row[name] ?? ''))); } } ``` Anahtarı betik özelliklerinde saklayın; e-tabloyu yalnızca bu rakamları görebilecek kişilerle paylaşın. ## Verileri dışarı aktarmanın diğer yolları [#verileri-dışarı-aktarmanın-diğer-yolları] Veri kümesi akışının yanı sıra **Entegrasyonlar → Veri aktarımı** sayfası dışa aktarma hedeflerini listeler: Azure Blob, Power BI ve Analitik SQL. Azure Blob dışa aktarımı açıkken Akollo her dosyayı seçilen kapsayıcıya bir kez yazar ve sonradan değiştirmez; mevcut dosyaları silmez, değiştirmez ve okumaz. Veri kümelerini doğrudan veritabanından okumak için [BI aracını SQL ile bağlama](/tr/connections/bi-sql-access) sayfasına bakın. ## İyi uygulamalar [#i̇yi-uygulamalar] * Her araç ve her çalışma alanı için ayrı bir anahtar kullanın; böylece birini değiştirirken diğerleri durmaz. * Rakamlar ne sıklıkla değişiyorsa o sıklıkta yenileyin, birkaç dakikada bir değil. Her çağrı anahtarın dakikalık sınırından düşer ve API kullanımı olarak kaydedilir. * Anahtarın süresi dolmadan onu yenileyin: Entegrasyonlar → API anahtarları → Döndür, siz aracı güncellerken önceki anahtarı kısa bir bekleme süresi boyunca çalışır durumda tutar. API anahtarını hiçbir zaman paylaşılan bir rapor dosyasına, betik dosyasına ya da e-tabloya yazmayın. Bunun yerine bir parametre, ortam değişkeni, sır kasası ya da betik özellikleri kullanın. ## Sık sorulan sorular [#sık-sorulan-sorular] Kurumunuz bu anahtarın servis hesabına henüz bir veri kümesi açmamıştır. Raporlama yöneticinizden erişim isteyin. Hayır. Sayfa boyutuna raporlama karar verir. Akış `limit`, `$top` ya da `$select` kabul etmez. Siz okurken veri kümesinin sürümü değişmiş, imleç başka bir anahtarla gönderilmiş (örneğin anahtarı döndürdükten sonra) ya da imleç bozulmuş olabilir. İlk sayfadan yeniden başlayın. Hayır. Araç yalnızca okur. Yalnızca BI veri kümeleri kapsamı olan bir anahtar projeleri, görevleri ya da kişileri okuyamaz, hiçbir şeyi değiştiremez. Evet. Veri kümeleri Akollo raporlarındaki rakamların aynısını taşır. ## İlgili sayfalar [#i̇lgili-sayfalar] * [BI aracını SQL ile bağlama](/tr/connections/bi-sql-access) * [API ve anahtarlar](/tr/connections/api) * [Raporlar](/tr/product-guide/reports)