README

Coveo PHP 实验性推送 API 旨在帮助您在用 PHP 编码时使用 Coveo 推送 API。

⚠️ 实验性，自行承担风险。

此存储库共享是为了提供帮助和提供信息（非官方支持，非生产使用）。
如需帮助，请勿联系 Coveo 支持，而应使用 Github 的问题功能。

备注：这是一个实验性存储库，不提供支持，自行承担风险。

这包括以下功能

在将文档推送到平台之前对其进行文档验证
在文档更新前后查看源更新状态
通过 Amazon S3 容器自动将大文件推送到平台

有关如何使用的代码示例，请参阅 examples 部分。

安装

确保您已安装 git。

然后，在您的命令提示符中，输入以下命令

pip install git+https://github.com/coveo-labs/Experimental-Push-PHP

将包包含到您的代码中

只需将以下行添加到您的项目中

use Coveo\Search\SDK\SDKPushPHP\Push;
use Coveo\Search\SDK\SDKPushPHP\PushType;
use Coveo\Search\SDK\SDKPushPHP\Document;

先决条件

在将文档推送到 Coveo Cloud 组织之前，您需要确保您有一个 Coveo Cloud 组织，并且该组织有一个推送源。

一旦满足这些先决条件，您需要获取您的组织 ID、源 ID 和 API 密钥。有关如何获取这些信息的更多信息，请参阅推送 API 教程 1 - 管理共享内容。

您还必须为您要随文档发送的每条元数据创建字段和映射。否则，您推送的一些数据可能会被 Coveo Cloud 忽略。有关在 Coveo Cloud 中创建字段和映射的说明，请参阅添加/编辑字段：[字段名] - 面板和编辑源的映射：[源名]。

推送文档

Coveo 推送 API 支持两种推送数据的方法：发送单个文档或发送文档批处理。

除非您只发送一个文档，否则您应始终以批处理的形式发送您的文档。

推送与流 API

对于常规推送源，使用默认的 Push 调用。如果您有一个目录源（用于电子商务）：请使用 Stream API 调用。如何？在创建 Push 类时，使用以下语法

完整目录索引

$pushtype = PushType::STREAM;
$push = new Push($sourceId, $orgId, $apiKey, $endpoint, NULL, $pushtype);

部分目录索引

$pushtype = PushType::UPDATE_STREAM;
$push = new Push($sourceId, $orgId, $apiKey, NULL, NULL, $pushtype);

使用不同的端点

如有需要使用不同的端点。例如欧盟数据中心

$endpoint = "https://api-eu.cloud.coveo.com/push/v1";
$pushtype = PushType::UPDATE_STREAM;
$push = new Push($sourceId, $orgId, $apiKey, $endpoint, NULL, $pushtype);

推送单个文档

只有当你想要添加或更新单个文档时，才应使用此方法。使用此方法推送多个文档可能会导致 Coveo 平台的 429 - 请求过多 响应。

在推送文档之前，你应该指定要使用的源 ID、组织 ID 和 API 密钥。

$push = new Push($sourceId, $orgId, $apiKey);

然后你可以创建一个带有适当选项的文档，如下所示

// Create a document
$mydoc = new Document("https://myreference.cov.com/&id=TESTME");
// Set plain text
$mydoc->SetData("ALL OF THESE WORDS ARE SEARCHABLE");
// Set FileExtension
$mydoc->FileExtension = ".html";
// Add Metadata
$mydoc->AddMetadata("connectortype", "CSV");
$authors = array();
array_push($authors,"Coveo");
array_push($authors,"R&D");
// rssauthors should be set as a multi-value field in your Coveo Cloud organization
$mydoc->AddMetadata("rssauthors", $authors);
// Set the Title
$mydoc->Title = "THIS IS A TEST";
// Set permissions
$user_email = "wim@coveo.com";
// Create a permission identity
$myperm = new PermissionIdentity(PermissionIdentityType::User, "", $user_email);
// Set the permissions on the document
$allowAnonymous = True;
$mydoc->SetAllowedAndDeniedPermissions(array($myperm), array(), $allowAnonymous);

上述代码将创建一个具有 https://myreference&id=TESTME URI 的文档。然后将其文档文本设置为 SetData 的值，并添加适当的元数据。

一旦文档准备就绪，你可以使用以下命令将其推送到索引

$push->AddSingleDocument($mydoc);

完整的示例如下所示

use Coveo\Search\SDK\SDKPushPHP\Push;
use Coveo\Search\SDK\SDKPushPHP\PushType;
use Coveo\Search\SDK\SDKPushPHP\Document;

//Reads the $sourceId, $orgId, and $apiKey
require_once('config.php');

// Setup the push client
$push = new Push($sourceId, $orgId, $apiKey);
// Get a first Ordering Id
$startOrderingId = $push->CreateOrderingId();

// Create a document
$mydoc = new Document("https://myreference.cov.com/&id=TESTME");
// Set plain text
$mydoc->SetData("ALL OF THESE WORDS ARE SEARCHABLE");
// Set FileExtension
$mydoc->FileExtension = ".html";
// Add Metadata
$mydoc->AddMetadata("connectortype", "CSV");
$authors = array();
array_push($authors,"Coveo");
array_push($authors,"R&D");
// rssauthors should be set as a multi-value field in your Coveo Cloud organization
$mydoc->AddMetadata("rssauthors", $authors);
// Set the Title
$mydoc->Title = "THIS IS A TEST";
// Set permissions
$user_email = "wim@coveo.com";
// Create a permission identity
$myperm = new PermissionIdentity(PermissionIdentityType::User, "", $user_email);
// Set the permissions on the document
$allowAnonymous = True;
$mydoc->SetAllowedAndDeniedPermissions(array($myperm), array(), $allowAnonymous);

// Push the document
$push->AddSingleDocument($mydoc);

// Delete older documents
$push->DeleteOlderThan($startOrderingId);

推送文档批量

此 SDK 提供了一种方便的方式将文档批量发送到 Coveo Cloud 平台。使用此方法，你可以确保你的文档在发送到 Coveo Cloud 时不会被限制。

与之前的调用一样，你必须首先指定你的源 ID、组织 ID 和 API 密钥。

$push = new Push($sourceId, $orgId, $apiKey);

然后你必须开始批量操作，并设置每个批量的最大大小。如果你不设置请求的最大大小，它将默认为 256 Mb。大小以字节为单位。

// Start the batch
$push->Start($updateSourceStatus, $deleteOlder);
// Set the maximum
$push->SetSizeMaxRequest(150*1024*1024);

updateSourceStatus 选项确保在推送文档时将源设置为 Rebuild，而 deleteOlder 选项删除在推送新文档之前已经存在于你源中的文档。

然后你可以开始添加文档到你的源，使用 Add 命令，如下所示

$push->Add(createDoc('/testfiles/Large1.pptx', '1'));

为了简化起见，假设存在一个 createDoc 函数。此函数返回与单个文档示例中 mydoc 元素格式相同的文档。

Add 命令检查当前批次的文档总大小是否不超过最大大小。当它超过时，它将启动向 Amazon S3 的文件上传，然后通过 Push API 将这些数据推送到 Coveo Cloud。

如果你想使用内存消耗检查，将 setMaxMemoryPercentage 设置为一个大于 0 的值。当 PHP 进程的可用内存超过最大值时，它将开始推送批量。

最后，一旦你添加完你的文档，你应该始终结束批量操作。这样，剩余的文档将被推送到平台，你的 Push 源的源状态将被设置为 Idle，旧文档将从你的源中删除。

以下示例演示了如何做到这一点。

// Setup the push client
$push = new Push($sourceId, $orgId, $apiKey);
// Start the batch
$push->Start($updateSourceStatus, $deleteOlder);
// Set the maximum
$push->SetSizeMaxRequest(150*1024*1024);

$push->Add(createDoc('/testfiles/Large1.pptx', '1'));
$push->Add(createDoc('/testfiles/Large2.pptx', '1'));
$push->Add(createDoc('/testfiles/Large1.pptx', '2'));
$push->Add(createDoc('/testfiles/Large2.pptx', '2'));
$push->Add(createDoc('/testfiles/Large1.pptx', '3'));
$push->Add(createDoc('/testfiles/Large2.pptx', '3'));
$push->Add(createDoc('/testfiles/Large1.pptx', '4'));
$push->Add(createDoc('/testfiles/Large2.pptx', '4'));
$push->Add(createDoc('/testfiles/Large1.pptx', '5'));
$push->Add(createDoc('/testfiles/Large2.pptx', '5'));

# End the Push
$push->End($updateSourceStatus, $deleteOlder);

向您的文档添加证券

在 Coveo 中，你可以向文档添加证券，这样只有允许的用户或组才能查看文档。此 SDK 允许你在推送文档时添加安全提供者信息。有关如何格式化权限的说明，请参阅Push API 教程 2 - 管理受保护内容。

你应该首先定义你的安全提供者，如下所示

// First, define a name for your Security Provider
$mysecprovidername = "MySecurityProviderTest"

// Then, define the cascading security provider information
$cascading = array(
    "Email Security Provider"=> array(
        "name"=> "Email Security Provider",
        "type"=> "EMAIL"));

// Finally, create the provider
$push->AddSecurityProvider($mysecprovidername, "EXPANDED", $cascading);

AddSecurityProvider 命令会自动将你的当前源与新建的安全提供者关联起来。

安全提供者创建后，你可以使用它来设置文档的权限。

以下示例添加了一个简单的权限集

// Set permissions
$user_email = "wim@coveo.com";
// Create a permission identity
$myperm = new PermissionIdentity(PermissionIdentityType::User, "", $user_email);
// Set the permissions on the document
$allowAnonymous = True;
$mydoc->SetAllowedAndDeniedPermissions(array($myperm), array(), $allowAnonymous);

以下示例展示了如何在文档中集成更复杂的权限集，用户可以通过以下两种方式访问文档：一是他们被单独授权，二是他们属于有权访问该文档的组。此示例还包括被明确拒绝访问文档的用户。

最后，此示例包括两个权限级别。第一个权限级别的优先级高于第二个权限级别；如果一个用户在第一个权限级别被允许访问文档，但在第二个级别被拒绝，他们仍然可以访问该文档。然而，被明确拒绝访问的用户仍然无法访问文档。

// Define a list of users that should have access to the document.
$users = array("Wim","Peter");

// Define a list of users that should not have access to the document.
$deniedusers = array("Alex","Anne");

// Define a list of groups that should have access to the document.
$groups = array("HR","RD","SALES");

// Create the permission Levels. Each level can include multiple sets.
$permLevel1 = new DocumentPermissionLevel('First');
$permLevel1Set1 = new DocumentPermissionSet('1Set1');
$permLevel1Set2 = new DocumentPermissionSet('1Set2');
$permLevel1Set1->AllowAnonymous = False;
$permLevel1Set2->AllowAnonymous = False;
$permLevel2 = new DocumentPermissionLevel('Second');
$permLevel2Set = new DocumentPermissionSet('2Set1');
$permLevel2Set->AllowAnonymous = False;

// Set the allowed permissions for the first set of the first level
foreach ($users as $user) {
    // Create the permission identity
    $permLevel1Set1->AddAllowedPermissions(
    new PermissionIdentity($GUSER, $mysecprovidername, $user));
}

// Set the denied permissions for the second set of the first level
foreach ($deniedusers as $user) {
  // Create the permission identity
  $permLevel1Set2->AddDeniedPermissions(
  new PermissionIdentity($GUSER, $mysecprovidername, $user));
}

// Set the allowed permissions for the first set of the second level
foreach ($groups as $group) {
  // Create the permission identity
  $permLevel2Set->AddAllowedPermissions(
  new PermissionIdentity($GGROUP, $mysecprovidername, $group));
}

// Set the permission sets to the appropriate level
$permLevel1->AddPermissionSet($permLevel1Set1);
$permLevel1->AddPermissionSet($permLevel1Set2);
$permLevel2->AddPermissionSet($permLevel2Set);

// Set the permissions on the document
array_push($mydoc->Permissions, $permLevel1);
array_push($mydoc->Permissions, $permLevel2);

证券是通过权限级别创建的，它可以包含多个权限集（参见复杂权限模型定义示例）。

使用自定义安全提供者设置证券还需要您通知索引哪些成员和用户映射是可用的。您通常会在索引过程完成后这样做。

添加安全扩展

证券也支持批量调用。

要这样做，您必须首先启动安全扩展，如下所示

$push->StartExpansion($mysecprovidername);

然后必须正确扩展您在安全中定义的任何组，如下所示

// group memberships for: HR, RD
foreach ($groups as $group) {
    // for each group set the users
    $members = array();
    foreach ($usersingroup as $user) {
        // Create a permission Identity
        array_push($members,
          new PermissionIdentityExpansion($GUSER, $mysecprovidername, $user));
    }
    log2($GGROUP);
    log2($group);
    $push->AddExpansionMember(
      new PermissionIdentityExpansion($GGROUP, $mysecprovidername, $group), $members, array(), array());
}

对于每个身份，您还需要将其映射到电子邮件安全提供者

foreach ($users as $user) {
    // Create a permission Identity
    $mappings = array();
    array_push($mappings,new PermissionIdentityExpansion($GUSER, "Email Security Provider", $user . "@coveo.com"));

    $wellknowns = array();
    array_push($wellknowns, new PermissionIdentityExpansion($GGROUP, $mysecprovidername, "Everyone"));

    $push->AddExpansionMapping(
      new PermissionIdentityExpansion($GUSER, $mysecprovidername, $user), array(), $mappings, $wellknowns);
}

与之前的批量调用一样，您必须记得以如下方式结束调用

$push->EndExpansion($mysecprovidername);

这样，您就可以确保剩余的身份被正确发送到Coveo平台。

在下一个安全权限更新周期之后，证券将被更新（参见刷新安全身份提供者）。

测试

如果您想进行测试，可以使用XAMPP来启动您的本地web服务器。在\htdocs\下创建一个新目录：安装composer require coveo/sdkpushphp。这将安装所有依赖项。现在使用examples目录中的文件开始测试。您可能需要以如下方式开始您的文件：

require_once __DIR__ . '/../vendor/autoload.php';
use Coveo\Search\SDK\SDKPushPHP\Push;
use Coveo\Search\SDK\SDKPushPHP\Document;

require_once('config.php');

变更

2021年2月

首次发布

2021年12月

Anca对代码进行了大量改进！！

2022年2月

支持Stream API

2023年11月

在PermissionSet中添加了SetAllowAnonymous
在put/post中添加了sleep
修复了AddPermissionExpansion中的空数组问题
修复了AddJSON logger
修复了AddSingleDocument
修复了Attempts doPost doPut
修复了带有检查false的重试机制
修复了当文档过大时的totalSize
添加了内存检查。使用函数SetMaxMemoryPercentage(int $p_Max)可以设置一个额外的检查，如果PHP进程消耗了太多的内存，它将比阈值更早地开始推送内容

依赖项

参考文献

Coveo Push API

coveo / sdkpushphp

维护者

详细信息