Özel entegrasyon oluşturma

Özel entegrasyonlar, API destekli herhangi bir aracı bir ajana bağlamanızı sağlar. Bu, sınırsız olanaklar sunar. Aşağıda entegrasyon, aksiyon ve tetikleyici oluşturmaya dair kapsamlı bir rehber bulabilirsiniz.

Entegrasyonlar, aksiyonlar ve tetikleyiciler

Entegrasyonlar, ajan ile üçüncü taraf araçlar arasında kimlik doğrulama ve API iletişimini yöneten standart bağlantılardır. Her entegrasyon içinde şunları oluşturabilirsiniz:

• Aksiyonlar: Ajanların ve iş akışlarının API'lerle etkileşim kurmak için çağırabileceği işlevler (ör. "bilet oluştur", "e-posta gönder", "veri getir")
• Tetikleyiciler: Belirli olaylar gerçekleştiğinde iş akışlarını başlatan olay izleyicileri (ör. "yeni e-posta alındı", "dosya yüklendi")

Entegrasyon kurulumu

Entegrasyonlar menüsünde Add integration öğesine tıklayarak başlayın.

Ardından bir entegrasyon adı belirtin ve bir simge yükleyin (aksiyonlar kullanılırken sohbette ve entegrasyonlar genel bakışında gösterilir). Ajanların bu entegrasyonu ne zaman kullanacağını bilmesine yardımcı olacak bir açıklama ekleyin. Oluşturmak için Save öğesine basın.

Kimlik doğrulama

Build sekmesinde kimlik doğrulama ile başlayın. Kimlik doğrulama türünüzü seçin ve aşağıdaki adımları izleyerek yapılandırın:

API Key

API Key kimlik doğrulamasını seçtikten sonra, 2. adımda özel giriş alanları ekleyin (API anahtarı veya istemci kimliği gibi). Bu girdiler, kullanıcılar bağlantı kurarken toplanır ve "zorunlu" olarak işaretlenebilir.

1. adım, kimlik doğrulamayı doğrulamak için bir test API uç noktası ayarlamanıza olanak tanır. URL parametresini değiştirin ve data.auth.fieldId kullanarak giriş alanlarınıza referanslar ekleyin.

İstekler ve günlük kaydı için yerleşik ld.request ve ld.log işlevlerini kullanın.

Aksiyonunuzu test edin ve ilk bağlantınızı oluşturun.

OAuth 2.0

Özel entegrasyonlar OAuth 2.0 kimlik doğrulamasını destekler.

1. adım özel giriş alanlarına izin verir (bağlantı kurulumu sırasında toplanır). Client ID ve Client Secret 4. adımda girilir; dolayısıyla burası yalnızca ek parametreler içindir.

OAuth istemcisi oluşturun

Hedef uygulamanızda bir OAuth istemcisi/Uygulama/Proje kurun ve gerekli API'leri etkinleştirin. Bu uygulama özelidir; bu nedenle arayüzümüz 5. adımda özel koda destek verir.

Google Calendar için bir Google Service Account oluşturun, client ID ve secret almak üzere yeni bir anahtar üretin, bunları 4. adımda ajan'a ekleyin, OAuth Redirect URL değerini kaydedin ve Google Calendar API'yi etkinleştirin.

Authorization URL'ini değiştirin

Hizmetinizin OAuth belgelerini kontrol edin ve Authorization URL değerini çıkarın. Genellikle şablonumuzdaki BASE_URL değerini değiştirmek yeterlidir.

Google Calendar için:

return `https://accounts.google.com/o/oauth2/v2/auth?client_id=${env.CLIENT_ID}&response_type=code&scope=${data.input.scope}&access_type=offline&redirect_uri=${encodeURIComponent(data.input.redirectUrl)}&state=${data.input.state}&prompt=consent`;

Kapsamları (Scopes) tanımlayın

Aksiyonlarınızın gerektirdiği OAuth kapsamlarını tanımlayın. API belgenize göre bunları virgül veya boşlukla ayırarak listeleyin.

Google Calendar için (boşlukla ayrılmış):

https://www.googleapis.com/auth/calendar.events https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/userinfo.profile

Access Token ve Refresh Token URL'lerini sağlayın

API'nizin OAuth belgelerinde Access Token URL ve Refresh Token URL değerlerini kontrol edin. Genellikle şablonumuzdaki tokenUrl değerini güncellemek işe yarar.

Google Calendar için:

const tokenUrl ='https://oauth2.googleapis.com/token';

Kimlik doğrulama kurulumunu test edin

Kimlik doğrulamayı doğrulamak için bir test API uç noktası sağlayın (ör. /me). Bu test isteğinin dönüş değeri, kurulan bağlantıların adlandırmasını etkilemek için OAuth Client Label içinde kullanılabilir. Dönüş değerine şu şekilde erişebilirsiniz: {{data.input}}

Google Calendar için: Google Sheets - {{data.input.useremail.value}}

Bir bağlantı ekleyerek ve yetkilendirme akışının çalıştığını doğrulayarak test edin.

Google Calendar için şu şekilde test ederiz:

url: 'https://people.googleapis.com/v1/people/me?personFields=names,emailAddresses'

Genel API'ler

Kimlik doğrulama gerektirmeyen genel kullanıma açık API'ler için None seçeneğini seçin.

Aksiyon oluşturma

Aksiyonlar, ajanların API uç noktalarınızla etkileşim kurmasını sağlar. İki tür aksiyon vardır:

• Regular Actions: Standart API etkileşimleri (oluşturma, okuma, güncelleme, silme işlemleri)
• Native Actions: ajan'ın dosya sistemiyle entegre olan özel dosya arama ve indirme aksiyonları

Regular Actions

Regular Actions en yaygın türdür ve standart API işlemlerini yönetir.

Regular Actions ne zaman oluşturulmalı

• CRUD işlemleri: API çağrılarıyla veri oluşturma, okuma, güncelleme veya silme
• Veri işleme: Analiz, dönüştürme veya doğrulama için API'lere veri gönderme
• Dosya işlemleri: Hizmetlere dosya yükleme, belgeler işleme, ekler gönderme
• Bildirimler: E-posta, mesaj gönderme veya bilet oluşturma
• Entegrasyonlar: Birden fazla hizmeti bağlama veya platformlar arasında veri senkronizasyonu

Regular Actions kurulumu

1. Aksiyon ekle: Entegrasyonunuzda "Add Action" öğesine tıklayın
2. Temel bilgileri yapılandırın: Ad, açıklama ve slug ayarlayın
3. Giriş alanları ekleyin: Aksiyonun kullanıcılardan ihtiyaç duyduğu verileri tanımlayın
4. Aksiyon kodunu yazın: API etkileşim mantığını uygulayın
5. Test edin: Aksiyonunuzun doğru çalıştığını doğrulayın

Aksiyon ve giriş açıklamaları

Model, hangi aksiyonu çağıracağına ve her alanı nasıl dolduracağına karar vermek için aksiyon ve giriş açıklamalarınızı okur. Aksiyonlarınızın nasıl çalıştığını açıklamak için bir Skill gerekmez.

• Aksiyon açıklaması: Aksiyonun ne yaptığını, ne zaman kullanılacağını ve ne döndürdüğünü belirtin
• Giriş açıklamaları: Beklenen biçimi, izin verilen değerleri ve varsayılanları belirtin
• Benzer aksiyonlar: Her açıklamada hangisinin ne zaman kullanılacağını belirtin

Giriş alanı türleri

Örnek: Bilet oluşturma aksiyonu

// Validate required inputs
if (!data.input.title) {
  return { error: "Title is required" };
}

// Build request
const options = {
  method: "POST",
  url: "https://api.ticketing-service.com/tickets",
  headers: {
    Authorization: `Bearer ${data.auth.api_key}`,
    "Content-Type": "application/json",
  },
  body: {
    title: data.input.title,
    description: data.input.description || "",
    priority: data.input.priority || "medium",
    assignee: data.input.assignee,
  },
};

try {
  const response = await ld.request(options);

  if (response.status === 201) {
    return {
      success: true,
      ticketId: response.json.id,
      url: response.json.url,
      message: `Created ticket #${response.json.id}: ${data.input.title}`,
    };
  } else {
    throw new Error(`API returned status ${response.status}`);
  }
} catch (error) {
  ld.log("Error creating ticket:", error.message);
  return {
    success: false,
    error: `Failed to create ticket: ${error.message}`,
  };
}

Dosya yükleme örneği

// Handle file uploads (requires FILE input field)
const document = data.input.document; // FileData object

if (!document) {
  return { error: "Please attach a document" };
}

// Validate file type
const allowedTypes = ["application/pdf", "image/jpeg", "image/png"];
if (!allowedTypes.includes(document.mimeType)) {
  return {
    error: `Unsupported file type: ${
      document.mimeType
    }. Allowed: ${allowedTypes.join(", ")}`,
  };
}

const options = {
  method: "POST",
  url: "https://api.example.com/documents",
  headers: {
    Authorization: `Bearer ${data.auth.api_key}`,
    "Content-Type": "application/json",
  },
  body: {
    filename: document.fileName,
    content: document.base64,
    mimeType: document.mimeType,
  },
};

const response = await ld.request(options);
return {
  success: true,
  documentId: response.json.id,
  message: `Uploaded ${document.fileName} successfully`,
};

Aksiyonlardan dosya döndürme

Aksiyonlar ayrıca dosya üretebilir ve döndürebilir:

// Generate CSV export
const data = await fetchCustomerData();

const csvHeader = "Name,Email,Created";
const csvRows = data.map(
  (customer) => `"${customer.name}","${customer.email}","${customer.created}"`
);
const csvContent = [csvHeader, ...csvRows].join("\n");

return {
  files: {
    fileName: `customers-${new Date().toISOString().slice(0, 10)}.csv`,
    mimeType: "text/csv",
    text: csvContent, // Use 'text' for UTF-8 content, 'base64' for binary
  },
  success: true,
  exported: data.length,
};

Tetikleyici oluşturma

Tetikleyiciler, olaylar için harici sistemleri izler ve iş akışlarını otomatik olarak başlatabilir.

Tetikleyiciler ne zaman oluşturulmalı

• Olay izleme: Yeni e-postaları, dosyaları, kayıtları veya değişiklikleri algılama
• İş akışı otomasyonu: Belirli olaylar gerçekleştiğinde süreçleri başlatma
• Veri senkronizasyonu: Değişiklikleri algılayarak sistemleri senkronize tutma
• Bildirimler: Harici olaylara tepki verip kullanıcıları bilgilendirme

Tetikleyici türleri

• Polling Triggers: Yeni olaylar için API'leri periyodik olarak kontrol eder
• Webhook Triggers: Harici sistemlerden gerçek zamanlı bildirimler alır

Polling tetikleyicileri kurulumu

1. Tetikleyici ekle: Entegrasyonunuzda "Add Trigger" öğesine tıklayın
2. Ayarları yapılandırın: Ad, açıklama ve yoklama aralığını ayarlayın
3. Giriş alanları ekleyin: Yapılandırma parametrelerini tanımlayın (isteğe bağlı)
4. Tetikleyici kodunu yazın: Yoklama mantığını uygulayın
5. Test edin: Tetikleyicinizin olayları doğru algıladığını doğrulayın

Zorunlu dönüş biçimi

Tetikleyiciler şu yapıya sahip bir olay dizisi döndürmelidir:

return [
  {
    id: "unique_event_id", // Required: Unique identifier
    timestamp: "2024-01-15T...", // Required: Event timestamp (ISO string)
    data: {
      // Your event data here
      eventType: "new_email",
      subject: "Important message",
      from: "sender@example.com",
      // ... other event properties
    },
  },
];

Örnek: Yeni e-posta tetikleyicisi

// Fetch recent emails
const options = {
  method: "GET",
  url: "https://api.email-service.com/messages",
  headers: {
    Authorization: `Bearer ${data.auth.access_token}`,
  },
  params: {
    since: new Date(Date.now() - 60 * 60 * 1000).toISOString(), // Last hour
    limit: 10,
  },
};

try {
  const response = await ld.request(options);
  const emails = response.json.messages || [];

  // Transform to required format
  const results = emails.map((email) => ({
    id: email.id,
    timestamp: email.receivedAt,
    data: {
      messageId: email.id,
      subject: email.subject,
      from: email.from,
      to: email.to,
      body: email.body,
      isRead: email.isRead,
    },
  }));

  return results;
} catch (error) {
  ld.log("Error fetching emails:", error.message);
  throw error;
}

Dosya ekli tetikleyiciler

Tetikleyiciler dosya içeren olaylar algıladığında, bunları data nesnesine ekleyin. Dosya içeriğini indirmek için ld.request() kullanın:

const results = [];

for (const email of emails) {
  const attachments = [];

  if (email.attachments && email.attachments.length > 0) {
    for (const attachment of email.attachments) {
      const fileResponse = await ld.request({
        method: "GET",
        url: `https://api.email-service.com/attachments/${attachment.id}`,
        headers: {
          Authorization: `Bearer ${data.auth.access_token}`,
        },
        responseType: "stream",
      });

      attachments.push({
        fileName: attachment.filename,
        mimeType: attachment.mimeType,
        base64: Buffer.from(fileResponse.buffer).toString("base64"),
      });
    }
  }

  results.push({
    id: email.id,
    timestamp: email.receivedAt,
    data: {
      subject: email.subject,
      from: email.from,
      body: email.body,
      files: attachments,
    },
  });
}

return results;

Webhook tetikleyicileri

Tetikleyici oluşturucu şu anda yalnızca polling tetikleyicilerini destekler. Webhook (REST\_HOOK) tetikleyicileri API üzerinden kullanılabilir ancak henüz tetikleyici oluşturucu arayüzünde sunulmamaktadır.

Native Actions

Native Actions, kullanıcının cihazında yerel olarak depolanmayan dosyaları aramanıza ve indirmenize olanak tanır. SharePoint, OneDrive, Google Drive ve Confluence için native aksiyonları zaten oluşturduk. Sohbette + öğesine tıklayın ve bu dosyaları aramak ve eklemek için bağlı bir hizmeti adıyla seçin. Bu entegrasyonlardan hiçbiri bağlı değilse menü Select file gösterir. Cihazınızdan yüklemek için Add files kullanın. Bir Ajana bilgi eklerken aynı kaynakları da ekleyebilirsiniz.

Native entegrasyonları kullanarak sohbete dosya ekleyin.

Native bir entegrasyon kullanarak Ajan bilgisine dosya ekleyin.

Diğer araçlar için native aksiyonlar oluşturmak, aynı şekilde bu platformlardan dosya aramanızı ve indirmenizi sağlar.

Native Action kurulumu

Native bir aksiyon kurmak için entegrasyonunuzu her zamanki gibi oluşturmaya başlayın. Başka bir aksiyon ekleyin ve Step 1 altında Advanced bölümünde aksiyon türü olarak "Search files" veya "Download file" seçin.

Ardından aksiyonu diğer aksiyonlar gibi oluşturursunuz; ancak işlevinizin belirli bir nesne yapısı döndürmesi gerekir. Bu, uyumluluğu sağlar ve ajanların dosyaları ile arama sonuçlarını doğru işlemesine olanak tanır.

Zorunlu çıktı biçimi

Seçtiğiniz aksiyona bağlı olarak işleviniz belirli bir nesne yapısı döndürmelidir. Bu, uyumluluğu sağlar ve ajanların dosyaları ile arama sonuçlarını doğru işlemesine olanak tanır.

Search files: Native bir arama entegrasyonu oluştururken işleviniz aşağıdaki şemaya uyan bir nesne dizisi döndürmelidir:

{
  url: string,
  documentId: string,
  title: string,
  author?: {
    id: string,
    name: string,
    imgUrl?: string,
  },
  mimeType: string,
  lastSeenByUser: Date,
  createdDate: Date,
  lastModifiedByAnyone: Date,
  lastModifiedByUserId?: {
    id?: string,
    name?: string,
    lastModifiedByUserIdDate: Date,
  },
  parent?: {
    id: string,
    title?: string,
    url?: string,
    type?: string,
    driveId?: string,
    siteId?: string,
    listId?: string,
    listItemId?: string,
  }
}

Tüm arama sonuçlarında title ve mimeType arayüzde görüntülenir.

Her parametre için ayrıntılı açıklamaya da bakın:

Zorunlu alanlar

İsteğe bağlı alanlar

Kullanım yönergeleri

Tarihler: \ Tüm tarih alanları geçerli ISO 8601 dizeleri olmalı veya tamamen atlanmalıdır. Geçersiz tarihler ayrıştırma hatalarına yol açar.

Null ve Atlanan:

• Açıkça boş olan alanlar için null kullanın (ör. içerik önizlemesi yok)
• Veri geçerli değilse veya kullanılamıyorsa alanları tamamen atlayın

Üst bilgi: Kullanıcıların dosya hiyerarşilerinde gezinmesine yardımcı olmak için mümkün olduğunca fazla üst bilgi ekleyin

• Yazar bilgisi: Yazar nesnelerinde her zaman hem id hem name ekleyin veya nesnenin tamamını atlayın
• Arama alakalılığı: contentPreview gibi alanlar, bir dosyanın sorguyla neden eşleştiğini göstererek arama deneyimini önemli ölçüde iyileştirebilir

Aşağıda native SharePoint Search files aksiyonu için bir örnek uygulama bulabilirsiniz.

  const entityTypes = ["driveItem"];
  const queryString = data.input.query;

  try {
    // Perform search if query exists
    const searchRequest = {
      requests: [
        {
          entityTypes,
          query: { queryString },
          trimDuplicates: true,
          queryAlterationOptions: {
            enableModification: true,
            enableSuggestions: true,
          },
        },
      ],
    };

    const searchResult = await ld.request({
      method: 'POST',
      url: 'https://graph.microsoft.com/v1.0/search/query',
      body: searchRequest,
      headers: {
        'Authorization': `Bearer ${data.auth.access_token}`,
        'Content-Type': 'application/json',
      },
    });

    const hits = searchResult.json?.value?.[0]?.hitsContainers?.[0]?.hits;
    if (hits && hits.length > 0) {
      const results = hits.filter((hit) => hit.resource.name).map((hit) => {
        const { resource } = hit;
        return {
          url: encodeURI(`${resource.webUrl}?web=1`),
          documentId: resource.id,
          title: resource.name,
          mimeType: getMimeTypeFromFileName(resource.name),
          author: resource.createdBy?.user ? {
            id: resource.createdBy.user.email || '',
            name: resource.createdBy.user.displayName || '',
          } : undefined,
          createdDate: resource.createdDateTime,
          lastModifiedByAnyone: resource.lastModifiedDateTime,
          lastModifiedByUserId: resource.lastModifiedBy?.user ? {
            id: resource.lastModifiedBy.user.email || '',
            name: resource.lastModifiedBy.user.displayName || '',
            lastModifiedByUserIdDate: resource.lastModifiedDateTime,
          } : undefined,
          parent: resource.parentReference ? {
            id: resource.parentReference.id || '',
            title: resource.parentReference.path ? resource.parentReference.path.split('/').pop() : undefined,
            driveId: resource.parentReference.driveId || '',
          } : undefined,
        };
      });
      return results;
    }
    return [];
  } catch (error) {
    ld.log(`Error: ${error.message}, Stack: ${error.stack}`);
    return [];
  }

  function getMimeTypeFromFileName(fileName) {
    const extension = fileName.split('.').pop().toLowerCase();
    const mimeTypes = {
      'txt': 'text/plain',
      'doc': 'application/msword',
      'docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
      'pdf': 'application/pdf',
    };
    return mimeTypes[extension] || 'application/octet-stream';
  }

Download file\ Native indirme aksiyonları için aşağıdaki biçimde bir nesne döndürün:

{
  fileName: string,
  mimeType: string,
  buffer: response.buffer, // Conditional: for binary files
  url: string,
  lastModified: Date,
  text: string // Conditional: for text files
}

Tüm arama sonuçlarında fileName ve mimeType arayüzde görüntülenir.

Her parametre için ayrıntılı açıklamaya da bakın:

Genel bakış

Önemli notlar

İçerik alanları: Ya buffer YA DA text sağlamalısınız, asla ikisini birden:\ buffer için kullanın: Görseller, PDF'ler, Office belgeleri, videolar, herhangi bir ikili biçim\ text için kullanın: Düz metin, HTML, kaynak kodu, JSON, XML, herhangi bir metin biçimi

MIME türü doğruluğu: mimeType, döndürülen içeriği doğru yansıtmalıdır:

• HTML olarak dışa aktarılan yerel Google Docs için yine de "application/vnd.google-apps.document" kullanın
• Dönüştürülmüş dosyalar için dışa aktarma biçimini değil, orijinal kaynak MIME türünü kullanın

Dosya adlandırma: fileName şunları yapmalıdır:

• Doğru dosya uzantısını içermek
• Kullanıcıların kaynak sistemden beklediği adla eşleşmek
• Geçersiz dosya sistemi karakterlerini kaldıracak şekilde temizlenmek

URL gereksinimleri: url şunları yapmalıdır:

• Kullanıcının kimlik doğrulamasıyla erişilebilir olmak
• Dosyayı kaynak uygulamada açmak (indirme bağlantısı değil)
• Hızlıca süresi dolmayan kararlı bir bağlantı olmak

Aşağıda native SharePoint Download file aksiyonu için bir örnek uygulama bulabilirsiniz.

  async function downloadOneDriveFile() {
    try {
      // Construct the API path based on the input configuration
      const config = JSON.parse(data.input.parent);
      let apiPath = '';

      if (config.listId && config.listItemId) {
        apiPath = `/sites/${config.siteId}/lists/${config.listId}/items/${data.input.itemId}/driveItem`;
      } else if (config.driveId) {
        apiPath = `/drives/${config.driveId}/items/${data.input.itemId}`;
      } else if (config.groupId) {
        apiPath = `/groups/${config.groupId}/drive/items/${data.input.itemId}`;
      } else if (config.userId) {
        apiPath = `/users/${config.userId}/drive/items/${data.input.itemId}`;
      } else if (config.siteId) {
        apiPath = `/sites/${config.siteId}/drive/items/${data.input.itemId}`;
      } else {
        throw new Error('Insufficient information to construct API path');
      }

      // Make the request to get the file metadata including download URL
      const options = {
        method: 'GET',
        url: `https://graph.microsoft.com/v1.0${apiPath}`,
        headers: {
          'Authorization': 'Bearer ' + data.auth.access_token,
          'Accept': 'application/json',
        },
      };

      const response = await ld.request(options);

      if (response.json['@microsoft.graph.downloadUrl']) {
        const downloadUrl = response.json['@microsoft.graph.downloadUrl'];

        // Request to download the file content
        const contentOptions = {
          method: 'GET',
          url: downloadUrl,
          responseType: 'stream'
        };

        const contentResponse = await ld.request(contentOptions);

        if (contentResponse.status !== 200) {
          throw new Error(
            `Error fetching file content: ${JSON.stringify(contentResponse)}`
          );
        }

        return {
          fileName: response.json.name,
          mimeType: response.json.file.mimeType,
          buffer: contentResponse.buffer,
          url: response.json.webUrl,
          lastModified: response.json.lastModifiedDateTime,
        };
      } else {
        throw new Error('Could not download file!');
      }
    } catch (error) {
      ld.log('Error downloading item from OneDrive: ' + error.message);
      throw error;
    }
  }

  return downloadOneDriveFile();

Giriş alanlarına erişim

Giriş alanı değerleri için data.input.{fieldSlug}, kullanıcının mevcut bağlantısından kimlik doğrulama alanı değerleri için data.auth.{fieldSlug} kullanın. Slug, entegrasyon oluşturucuda her alanı oluştururken ayarladığınız tanımlayıcıdır.

Özel kod bölümleri için yerleşik işlevler

Entegrasyon işlevlerinizi kurmanıza yardımcı olması için Integration Agent kullanın.

Özel kod bölümleri, yaygın işlemler için bir dizi yerleşik yardımcı işleve erişebilir. En sık kullanılanlar şunlardır:

Temel işlevler

• ld.request() - Harici API'lere HTTP istekleri yapma
• ld.log() - Hata ayıklama bilgisi çıktısı
• atob() / btoa() - Base64 kodlama/çözme
• JSON.stringify() / JSON.parse() - JSON işleme
• Tam Sandbox Yardımcı İşlevleri Referansı — Veri dönüşümleri (CSV, Parquet, Arrow), SQL doğrulama, kriptografi, AWS istek imzalama, Microsoft XMLA entegrasyonu ve daha fazlası dahil tüm kullanılabilir sandbox yardımcı işlevlerini görüntüleyin.

Hızlı örnekler

HTTP isteği

const options = {
  method: "GET",
  url: `https://www.googleapis.com/calendar/v3/calendars/${data.input.calendarId}/events/${data.input.eventId}`,
  headers: {
    Authorization: "Bearer " + data.auth.access_token,
    Accept: "application/json",
  },
};

const response = await ld.request(options);
return response.json;

JSON ayrıştırma

const properties = data.input.properties
  ? JSON.parse(data.input.properties)
  : {};

const options = {
  method: "PATCH",
  url: `https://api.hubapi.com/crm/v3/objects/companies/${data.input.companyId}`,
  headers: {
    Authorization: "Bearer " + data.auth.access_token,
    "Content-Type": "application/json",
  },
  body: { properties },
};

Base64 kodlama

const auth = btoa(`${env.CLIENT_ID}:${env.CLIENT_SECRET}`);

Sandbox kitaplık kısıtlamaları

Özel entegrasyon kodu güvenli bir sandbox ortamında çalışır. Harici kitaplıkları (npm, pip vb.) yükleyemez veya içe aktaramazsınız - yalnızca sınırlı bir yerleşik JavaScript/Node.js API kümesi kullanılabilir. Gelişmiş işleme için (ör. PDF ayrıştırma, görsel manipülasyonu) harici API'leri veya hizmetleri kullanın ve bunları entegrasyon kodunuzdan çağırın.

En iyi uygulamalar

Aksiyon tasarımı

• Tek sorumluluk: Her aksiyon bir işi iyi yapmalıdır
• Net adlandırma: Amacı açıklayan tanımlayıcı aksiyon adları kullanın
• Giriş doğrulama: Zorunlu girdileri her zaman doğrulayın ve yararlı hata mesajları sağlayın
• Hata işleme: API hatalarını zarifçe yakalayın ve işleyin
• Günlük kaydı: Hata ayıklamaya yardımcı olmak için ld.log() kullanın

Kimlik (ID) işleme

Çoğu API çağrısı belirli dahili kimlikler gerektirir. Sorun, ajanların bu kimlikleri tahmin edememesi ve "HubSpot'ta belirli kişiyi getir" veya "Google Calendar'da belirli takvime etkinlik ekle" gibi aksiyonlar çağrılırken kötü bir kullanıcı deneyimi yaratmasıdır.

Çözüm: Bu kimlikleri önce ajana getirip döndüren yardımcı aksiyonlar oluşturun. Örneğin HubSpot için Get deal context işlevimiz, kullanılabilir pipeline ve stage'ler için dahili kimlikleri toplamak üzere GET uç noktalarını kullanır. Bu, ajanların artık gerekli bağlama sahip olduğu için Create deal veya Update deal gibi aksiyonları çok daha etkili kullanmasını sağlar.

Performans

• API çağrılarını en aza indirin: Mümkün olduğunda işlemleri toplu hale getirin
• Sayfalama kullanın: Büyük veri kümelerini uygun şekilde işleyin
• Zaman aşımı işleme: Harici API çağrıları için uygun zaman aşımları ayarlayın

Güvenlik

• Girdileri doğrulayın: Kullanıcı girdisine doğrulama olmadan asla güvenmeyin
• Verileri temizleyin: Harici API'lere göndermeden önce verileri temizleyin
• Gizlilikleri yönetin: Hassas veriler için kimlik doğrulama alanlarını kullanın, asla sabit kodlamayın
• Hız sınırlama: API hız sınırlarına uyun ve geri çekilme stratejileri uygulayın

SSS

Mevcut bir entegrasyonla kapsanmayan bir araç veya API'ye ajan bağlanması gerektiğinde özel bir entegrasyon oluşturun. Tekrarlanabilir aksiyonlar, yapılandırılmış veri alma ve kullanıcıların sistemler arasında veriyi elle kopyalamaması gereken iş akışları için en uygundur.

Kimlik doğrulamayı, uç nokta URL'lerini, istek yöntemlerini, zorunlu başlıkları, giriş şemasını, çıktı şemasını ve harici API'nin beklenen yanıtı döndürüp döndürmediğini kontrol edin. Karmaşık mantık eklemeden önce bir aksiyonu basit girdilerle test edin.