Hızlı Başlangıç Kılavuzu

Dakikalar İçinde Çalışmaya Başlayın

Bu adım adım kılavuzu takip ederek mindzieStudio için ilk başarılı API çağrılarınızı yapabilir ve süreç madenciliği özelliklerini uygulamalarınıza entegre etmeye başlayabilirsiniz.

Ön Koşullar

• API Kimlik Bilgileri: Erişim jetonu, tenant ID ve proje ID'si
• Temel URL: Mindzie örneğinizin API uç noktası
• HTTPS Erişimi: Mindzie örneğinize güvenli bağlantı
• Geliştirme Ortamı: Tercih ettiğiniz programlama dili ve HTTP istemcisi

Kimlik bilgileriniz yok mu? API erişim kimlik bilgilerinizi nasıl alacağınızı öğrenmek için Kimlik Doğrulama Kılavuzu sayfasına göz atın.

Adım 1: Temel Bağlantıyı Test Edin

Mindzie örneğinize erişilebilir olduğundan emin olmak için temel bağlantıyı test ederek başlayın:

curl -X GET "https://your-mindzie-instance.com/api/Action/ping"

Beklenen Yanıt:

{
  "status": "ok",
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "1.0.0"
}

Adım 2: Kimlik Doğrulamayı Doğrulayın

Kimlik doğrulama bilgilerinizle authenticated ping endpoint'ini test edin:

curl -X GET "https://your-mindzie-instance.com/api/Action/ping/authenticated" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-Id: YOUR_TENANT_GUID" \
  -H "X-Project-Id: YOUR_PROJECT_GUID" \
  -H "Content-Type: application/json"

Beklenen Yanıt:

{
  "status": "authenticated",
  "timestamp": "2024-01-15T10:30:00Z",
  "tenantId": "12345678-1234-1234-1234-123456789012",
  "projectId": "87654321-4321-4321-4321-210987654321",
  "userId": "user@company.com",
  "permissions": ["read", "write", "admin"]
}

Adım 3: İlk API Çağrınız

İşlem geçmişini almak için pratik bir API çağrısı yapalım:

curl -X GET "https://your-mindzie-instance.com/api/Action/history?limit=5" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-Id: YOUR_TENANT_GUID" \
  -H "X-Project-Id: YOUR_PROJECT_GUID" \
  -H "Content-Type: application/json"

Örnek Yanıt:

{
  "actions": [
    {
      "actionId": "87654321-4321-4321-4321-210987654321",
      "actionType": "analyze",
      "status": "completed",
      "startTime": "2024-01-15T10:30:00Z",
      "endTime": "2024-01-15T10:32:15Z",
      "duration": 135,
      "userId": "user@company.com"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 1,
    "totalItems": 1,
    "itemsPerPage": 5
  }
}

Dil Bazlı Örnekler

JavaScript

Modern web uygulamaları ve Node.js arka uçları için fetch API veya axios kullanın.

Python

Veri bilimi iş akışları ve arka uç otomasyonu için requests kütüphanesini kullanın.

C#/.NET

Kurumsal uygulamalar ve mikroservisler için HttpClient kullanın.

JavaScript Örneği

Modern JavaScript ve fetch API kullanarak tam örnek:

// Konfigürasyon
const API_CONFIG = {
  baseURL: 'https://your-mindzie-instance.com/api',
  token: 'YOUR_ACCESS_TOKEN',
  tenantId: 'YOUR_TENANT_GUID',
  projectId: 'YOUR_PROJECT_GUID'
};

// API çağrıları için yardımcı fonksiyon
async function callMindzieAPI(endpoint, options = {}) {
  const url = `${API_CONFIG.baseURL}${endpoint}`;

  const defaultHeaders = {
    'Authorization': `Bearer ${API_CONFIG.token}`,
    'X-Tenant-Id': API_CONFIG.tenantId,
    'X-Project-Id': API_CONFIG.projectId,
    'Content-Type': 'application/json'
  };

  try {
    const response = await fetch(url, {
      ...options,
      headers: { ...defaultHeaders, ...options.headers }
    });

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }

    return await response.json();
  } catch (error) {
    console.error('API çağrısı başarısız oldu:', error);
    throw error;
  }
}

// Örnek kullanım
async function quickStartExample() {
  try {
    // 1. Bağlantıyı test et
    console.log('Bağlantı testi yapılıyor...');
    const pingResult = await callMindzieAPI('/Action/ping');
    console.log('Ping başarılı:', pingResult);

    // 2. Kimlik doğrulamayı test et
    console.log('Kimlik doğrulama testi yapılıyor...');
    const authResult = await callMindzieAPI('/Action/ping/authenticated');
    console.log('Kimlik doğrulama başarılı:', authResult);

    // 3. İşlem geçmişini al
    console.log('İşlem geçmişi getiriliyor...');
    const history = await callMindzieAPI('/Action/history?limit=5');
    console.log('İşlem geçmişi:', history);

    console.log('Hızlı başlangıç başarıyla tamamlandı!');
    return history;
  } catch (error) {
    console.error('Hızlı başlangıç başarısız oldu:', error);
    throw error;
  }
}

// Örneği çalıştır
quickStartExample();

Python Örneği

Python requests kütüphanesi kullanarak tam örnek:

import requests
import json
from typing import Dict, Any

class MindzieQuickStart:
    def __init__(self, base_url: str, token: str, tenant_id: str, project_id: str):
        self.base_url = base_url.rstrip('/')
        self.headers = {
            'Authorization': f'Bearer {token}',
            'X-Tenant-Id': tenant_id,
            'X-Project-Id': project_id,
            'Content-Type': 'application/json'
        }

    def call_api(self, endpoint: str, method: str = 'GET', **kwargs) -> Dict[str, Any]:
        """Mindzie API çağrısı yapar"""
        url = f"{self.base_url}{endpoint}"

        try:
            response = requests.request(
                method=method,
                url=url,
                headers=self.headers,
                **kwargs
            )
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            print(f"API çağrısı başarısız oldu: {e}")
            raise

    def run_quick_start(self):
        """Hızlı başlangıç dizisini çalıştırır"""
        print("Mindzie API Hızlı Başlangıç başlatılıyor...")

        try:
            # 1. Bağlantı testi
            print("1. Bağlantı testi yapılıyor...")
            ping_result = requests.get(f"{self.base_url}/api/Action/ping")
            ping_result.raise_for_status()
            print(f"   Bağlantı OK: {ping_result.json()}")

            # 2. Kimlik doğrulama testi
            print("2. Kimlik doğrulama testi yapılıyor...")
            auth_result = self.call_api('/api/Action/ping/authenticated')
            print(f"   Kimlik doğrulama OK: {auth_result['status']}")

            # 3. İşlem geçmişini al
            print("3. İşlem geçmişi getiriliyor...")
            history = self.call_api('/api/Action/history?limit=5')
            print(f"   {len(history['actions'])} işlem alındı")

            print("Hızlı başlangıç başarıyla tamamlandı!")
            return history

        except Exception as e:
            print(f"Hızlı başlangıç başarısız oldu: {e}")
            raise

# Kullanım örneği
if __name__ == "__main__":
    # Kimlik bilgilerinizi yapılandırın
    quick_start = MindzieQuickStart(
        base_url='https://your-mindzie-instance.com/api',
        token='YOUR_ACCESS_TOKEN',
        tenant_id='YOUR_TENANT_GUID',
        project_id='YOUR_PROJECT_GUID'
    )

    # Hızlı başlangıcı çalıştırın
    result = quick_start.run_quick_start()
    print(f"Nihai sonuç: {json.dumps(result, indent=2)}")

C#/.NET Örneği

C# HttpClient kullanarak tam örnek:

using System;
using System.Net.Http;
using System.Text.Json;
using System.Threading.Tasks;

public class MindzieQuickStart
{
    private readonly HttpClient _httpClient;
    private readonly string _baseUrl;

    public MindzieQuickStart(string baseUrl, string token, string tenantId, string projectId)
    {
        _baseUrl = baseUrl.TrimEnd('/');

        _httpClient = new HttpClient();
        _httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {token}");
        _httpClient.DefaultRequestHeaders.Add("X-Tenant-Id", tenantId);
        _httpClient.DefaultRequestHeaders.Add("X-Project-Id", projectId);
    }

    public async Task<T> CallApiAsync<T>(string endpoint)
    {
        try
        {
            var response = await _httpClient.GetAsync($"{_baseUrl}{endpoint}");
            response.EnsureSuccessStatusCode();

            var content = await response.Content.ReadAsStringAsync();
            return JsonSerializer.Deserialize<T>(content, new JsonSerializerOptions
            {
                PropertyNameCaseInsensitive = true
            });
        }
        catch (HttpRequestException ex)
        {
            Console.WriteLine($"API çağrısı başarısız oldu: {ex.Message}");
            throw;
        }
    }

    public async Task RunQuickStartAsync()
    {
        Console.WriteLine("Mindzie API Hızlı Başlangıç başlatılıyor...");

        try
        {
            // 1. Bağlantı testi
            Console.WriteLine("1. Bağlantı testi yapılıyor...");
            using var pingClient = new HttpClient();
            var pingResponse = await pingClient.GetAsync($"{_baseUrl}/api/Action/ping");
            pingResponse.EnsureSuccessStatusCode();
            Console.WriteLine("   Bağlantı OK");

            // 2. Kimlik doğrulama testi
            Console.WriteLine("2. Kimlik doğrulama testi yapılıyor...");
            var authResult = await CallApiAsync<AuthResponse>("/api/Action/ping/authenticated");
            Console.WriteLine($"   Kimlik doğrulama OK: {authResult.Status}");

            // 3. İşlem geçmişini al
            Console.WriteLine("3. İşlem geçmişi getiriliyor...");
            var history = await CallApiAsync<ActionHistoryResponse>("/api/Action/history?limit=5");
            Console.WriteLine($"   {history.Actions.Length} işlem alındı");

            Console.WriteLine("Hızlı başlangıç başarıyla tamamlandı!");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Hızlı başlangıç başarısız oldu: {ex.Message}");
            throw;
        }
    }

    public void Dispose()
    {
        _httpClient?.Dispose();
    }
}

// Veri modelleri
public class AuthResponse
{
    public string Status { get; set; }
    public string TenantId { get; set; }
    public string ProjectId { get; set; }
    public string UserId { get; set; }
}

public class ActionHistoryResponse
{
    public ActionItem[] Actions { get; set; }
    public PaginationInfo Pagination { get; set; }
}

public class ActionItem
{
    public string ActionId { get; set; }
    public string ActionType { get; set; }
    public string Status { get; set; }
    public DateTime StartTime { get; set; }
    public DateTime? EndTime { get; set; }
}

public class PaginationInfo
{
    public int CurrentPage { get; set; }
    public int TotalPages { get; set; }
    public int TotalItems { get; set; }
}

// Kullanım
class Program
{
    static async Task Main(string[] args)
    {
        var quickStart = new MindzieQuickStart(
            "https://your-mindzie-instance.com/api",
            "YOUR_ACCESS_TOKEN",
            "YOUR_TENANT_GUID",
            "YOUR_PROJECT_GUID"
        );

        try
        {
            await quickStart.RunQuickStartAsync();
        }
        finally
        {
            quickStart.Dispose();
        }
    }
}

Yaygın Sorunlar ve Çözümleri

Kimlik Doğrulama Başarısızlıkları

• 401 Unauthorized: Erişim jetonunuzun doğru ve süresinin dolmamış olduğunu kontrol edin
• 403 Forbidden: Tenant/proje ID’lerini ve kullanıcı izinlerini kontrol edin
• 400 Bad Request: Gerekli tüm başlıkların dahil edildiğinden emin olun

Bağlantı Sorunları

• Ağ zaman aşımı: Güvenlik duvarı ayarlarını ve ağ bağlantısını kontrol edin
• SSL/TLS hataları: Sertifika geçerliliğini ve HTTPS yapılandırmasını doğrulayın
• DNS çözümlemesi: Mindzie örneği URL’sinin doğru olduğundan emin olun

Oran Sınırı (Rate Limiting)

• 429 Too Many Requests: Üstel geri çekilme (exponential backoff) yeniden deneme mantığını uygulayın
• Oran sınırlarını izleyin: Yanıt başlıklarından oran limiti bilgilerini kontrol edin
• İstekleri optimize edin: API çağrılarını azaltmak için sayfalandırma ve filtreleme kullanın

Sonraki Adımlar

Tebrikler! mindzieAPI hızlı başlangıcını başarıyla tamamladınız. Güçlü entegrasyonlar geliştirmeye başlamak için Actions API veya Blocks API sayfalarını keşfedin.