README

此存储库包含LaunchDarkly的REST API客户端库。此客户端库是从我们的OpenAPI规范自动生成的，使用了代码生成库。

此REST API用于自定义集成、数据导出或自动化您的功能标志工作流程。**不要**使用此客户端库在您的Web或移动应用程序中包含功能标志。要集成功能标志与您的应用程序，请阅读SDK文档。

此客户端库仅与我们的最新版本REST API兼容，版本20220603。此客户端库的早期版本（版本10.0.0之前）仅与我们的早期版本REST API兼容。创建访问令牌时，您可以设置与令牌关联的REST API版本。默认情况下，使用令牌发送的API请求将使用指定的API版本。要了解更多信息，请阅读版本。

OpenAPIClient-php

概述

认证

LaunchDarkly的REST API使用HTTPS协议，最低TLS版本为1.2。

所有REST API资源都通过个人或服务访问令牌或会话cookie进行认证。不支持其他认证机制。您可以在您的账户设置页面管理个人访问令牌。

LaunchDarkly还有SDK密钥、移动密钥和客户端ID，分别用于我们的服务器端SDK、移动SDK和基于JavaScript的SDK。**这些密钥不能用于访问我们的REST API**。这些密钥是特定环境的，只能执行如获取功能标志设置的只读操作。

保护您的访问令牌和SDK密钥

访问令牌不应在任何不受信任的上下文中暴露。永远不要将访问令牌放入客户端JavaScript，或将其嵌入到移动应用程序中。LaunchDarkly有特殊的移动密钥，可以嵌入到移动应用程序中。如果您意外暴露了访问令牌或SDK密钥，您可以从您的账户设置页面重置它。

客户端ID可以安全地嵌入到不受信任的上下文中。它专为客户端JavaScript使用而设计。

通过请求头进行认证

与API认证的首选方法是向您的请求添加包含您的访问令牌的Authorization头。Authorization头的值必须是您的访问令牌。

从账户设置页面管理个人访问令牌。

通过会话cookie进行认证

出于测试目的，您可以直接从您的Web浏览器进行API调用。如果您已登录到LaunchDarkly应用程序，API将使用您的现有会话进行调用认证。

如果您拥有除了管理员以外的其他角色，或者定义了自定义角色，您可能没有权限执行某些API调用。在这种情况下，您将收到401响应代码。

修改Origin头部会导致错误

LaunchDarkly会验证任何由会话cookie认证的API请求的Origin头部是否与预期的Origin头部匹配。预期的Origin头部是https://app.launchdarkly.com。

如果Origin头部与预期不符，LaunchDarkly将返回一个错误。这个错误可能会阻止LaunchDarkly应用程序正常工作。

任何故意更改Origin头部的浏览器扩展都可能引起这个问题。例如，Allow-Control-Allow-Origin: * Chrome扩展将Origin头部更改为http://evil.com，导致应用程序失败。

为了避免这个错误，请不要修改您的Origin头部。

当使用访问令牌进行认证时，LaunchDarkly不需要匹配Origin，因此这个问题不会影响正常的API使用。

表示形式

所有资源都期望并返回JSON响应体。错误响应也发送JSON体。要了解更多关于API错误格式的信息，请阅读错误。

实际上这意味着您总是获得一个设置了Content-Type头部为application/json的响应。

此外，PATCH、POST和PUT请求的请求体必须以JSON格式编码，并设置Content-Type头部为application/json。

摘要和详细表示

当您获取资源列表时，响应只包括每个资源的最重要的属性。这是资源的摘要表示。当您获取单个资源，例如单个功能标志时，您将收到资源的详细表示。

找到详细表示的最佳方式是跟随链接。每个摘要表示都包含到其详细表示的链接。

展开响应

有时资源的详细表示默认情况下不包括所有属性。如果这种情况发生，请求方法将明确记录这一点，并描述您可以在展开的响应中包含哪些属性。

要包含额外的属性，请将expand请求参数追加到您的请求中，并添加要包含的属性的逗号分隔列表。例如，当您将?expand=members,roles追加到获取团队端点时，展开的响应将包括这两个属性。

链接和可寻址性

导航API的最佳方式是通过跟随链接。这些是链接到其他资源的表示中的属性。API始终使用相同的链接格式。

API内其他资源的链接封装在_links对象中
如果资源有一个对应于网站HTML内容的链接，它将存储在一个特殊的_site链接中

每个链接有两个属性

href，其中包含URL
type，它描述了内容类型

例如，一个功能资源可能返回以下内容

{
  \"_links\": {
    \"parent\": {
      \"href\": \"/api/features\",
      \"type\": \"application/json\"
    },
    \"self\": {
      \"href\": \"/api/features/sort.order\",
      \"type\": \"application/json\"
    }
  },
  \"_site\": {
    \"href\": \"/features/sort.order\",
    \"type\": \"text/html\"
  }
}

从这里，您可以通过跟随parent链接导航到功能的父集合，或通过跟随_site链接导航到功能的网站页面。

集合始终表示为一个具有items属性的JSON对象，该属性包含表示数组的数组。像所有其他表示一样，集合在顶层定义了_links。

分页集合包含first、last、next和prev链接，其中包含包含集合中相应元素的URL。

更新

支持部分更新的资源使用PATCH动词。大多数资源支持JSON patch格式。某些资源还支持JSON merge patch格式，某些资源支持语义补丁格式，这是一种指定要执行修改的方法，作为一系列可执行指令的集合。每个资源都支持可选的注释，您可以在更新时提交。注释将出现在出站webhook、审计日志和其他集成中。

当一个资源同时支持JSON patch和语义补丁时，我们在请求方法中记录两者。然而，我们文档中包含的具体请求体字段和描述只匹配一种补丁类型。

使用JSON patch进行更新

JSON patch是一种指定对资源执行修改的方法。JSON patch使用路径和一组有限的操作来描述如何将资源的当前状态转换为新的状态。JSON patch文档始终是数组，其中每个元素包含一个操作、更新字段的路径和新的值。

例如，在这个功能标志表示中

{
    \"name\": \"New recommendations engine\",
    \"key\": \"engine.enable\",
    \"description\": \"This is the description\",
    ...
}

您可以使用以下补丁文档更改功能标志的描述

[{ \"op\": \"replace\", \"path\": \"/description\", \"value\": \"This is the new description\" }]

您可以在单个请求中指定要执行的多项修改。您还可以在应用补丁之前测试是否满足某些先决条件

[
  { \"op\": \"test\", \"path\": \"/version\", \"value\": 10 },
  { \"op\": \"replace\", \"path\": \"/description\", \"value\": \"The new description\" }
]

上述补丁请求测试功能标志的version是否为10，如果是，则更改功能标志的描述。

不可编辑的属性，如资源中的_links，名称以下划线开头。

使用JSON merge patch进行更新

JSON merge patch是另一种指定对资源执行修改的格式。JSON merge patch不如JSON patch表达能力强。然而，在许多情况下，构造合并补丁文档更简单。例如，您可以使用以下合并补丁文档更改功能标志的描述

{
  \"description\": \"New flag description\"
}

使用语义补丁进行更新

某些资源支持语义补丁格式。语义补丁是一组可执行指令，用于指定对资源执行修改的方法。

语义补丁允许您使用精确、定制的指令明确表示意图。在许多情况下，您可以在不依赖于资源当前状态的情况下独立定义语义补丁指令。这在定义可能在将来应用的变化时非常有用。

要发出语义补丁请求，必须在您的Content-Type头中追加domain-model=launchdarkly.semanticpatch。

以下是方法

Content-Type: application/json; domain-model=launchdarkly.semanticpatch

如果您不使用此头调用语义补丁资源，您将收到400响应，因为您的语义补丁将被解释为JSON patch。

语义补丁请求的正文包含以下属性

comment (字符串): (可选) 更新的描述。
environmentKey (字符串): (仅对某些资源为必需) 环境密钥。
instructions (数组): (必需) 更新应执行的操作列表。列表中的每个操作都必须是一个对象，其中包含一个kind属性，指示指令。如果指令需要参数，您必须在对象中包括这些参数作为额外的字段。支持语义补丁的每个资源的文档都包括可用的指令和任何其他参数。

例如

{
  \"comment\": \"optional comment\",
  \"instructions\": [ {\"kind\": \"turnFlagOn\"} ]
}

如果在补丁中遇到任何错误，端点将返回错误，并且不会更改资源。一般来说，如果资源已处于您请求的状态，则每个指令都会默默无动作。

带有注释的更新

您可以在 PATCH 更改中提交可选注释。

要提交一个与 JSON 补丁文档一起的注释，请使用以下格式

{
  \"comment\": \"This is a comment string\",
  \"patch\": [{ \"op\": \"replace\", \"path\": \"/description\", \"value\": \"The new description\" }]
}

要提交一个与 JSON 合并补丁文档一起的注释，请使用以下格式

{
  \"comment\": \"This is a comment string\",
  \"merge\": { \"description\": \"New flag description\" }
}

要提交一个与语义补丁一起的注释，请使用以下格式

{
  \"comment\": \"This is a comment string\",
  \"instructions\": [ {\"kind\": \"turnFlagOn\"} ]
}

错误

API 总是以通用格式返回错误。以下是一个示例

{
  \"code\": \"invalid_request\",
  \"message\": \"A feature with that key already exists\",
  \"id\": \"30ce6058-87da-11e4-b116-123b93f75cba\"
}

code 指示错误的通用类别。message 是对错误发生原因的易于理解的解释。id 是一个唯一标识符。当您与 LaunchDarkly 支持团队合作调试特定 API 调用的问题时，请使用它。

HTTP 状态错误响应代码

CORS

LaunchDarkly API 支持任何来源的 AJAX 请求的跨源资源共享（CORS）。如果请求中给出了 Origin 标头，它将被作为显式允许的来源回显。否则，请求将返回通配符，Access-Control-Allow-Origin: *。有关 CORS 的更多信息，请阅读CORS W3C 建议。示例 CORS 标头可能如下所示

Access-Control-Allow-Headers: Accept, Content-Type, Content-Length, Accept-Encoding, Authorization
Access-Control-Allow-Methods: OPTIONS, GET, DELETE, PATCH
Access-Control-Allow-Origin: *
Access-Control-Max-Age: 300

您可以使用与同源调用相同的方式制作经过身份验证的 CORS 调用，使用令牌或基于会话的身份验证。如果您正在使用会话身份验证，则应将您的 xhr 请求的 withCredentials 属性设置为 true。您永远不应向不受信任的实体暴露您的访问令牌。

速率限制

我们使用多种速率限制策略来确保我们 API 的可用性。对我们的 API 的速率限制调用返回 429 状态代码。对我们的 API 的调用包括指示当前速率限制状态的标头。返回的具体标头取决于被调用的 API 路由。限制取决于路由、身份验证机制和其他因素。不受速率限制的路由可能不包含以下描述的任何标头。

速率限制和 SDK

LaunchDarkly SDK 永远不会受到速率限制，并且不使用此处定义的 API 端点。LaunchDarkly 使用不同的方法集，包括流/服务器发送事件和全局 CDN，以确保 LaunchDarkly SDK 所用路由的可用性。

全局速率限制

经过身份验证的请求受全局限制。这是您的帐户每十秒可以向 API 发起的最大调用次数。帐户上的所有服务和个人访问令牌共享此限制，因此超过限制可能会影响其他令牌。受全局速率限制影响的调用可能返回以下标头

我们不会公开记录可以全球范围内进行的调用次数。此限制可能会更改，我们鼓励客户针对规范编程，依赖于上述定义的两个标头，而不是将当前限制硬编码。

路由级别速率限制

一些经过身份验证的路由有自定义速率限制。这些也每十秒重置一次。任何撞击相同路由的服务或个人访问令牌都共享此限制，因此超过限制可能会影响其他令牌。受路由级别速率限制影响的调用返回以下标头

一个路由代表一个特定的 URL 模式和动词。例如，删除环境端点是单个路由，对删除环境的每次调用都计入您对该路由的路由级别速率限制。

我们不会公开记录每个帐户每十秒可以对每个端点进行的调用次数的具体次数。这些限制可能会更改，我们鼓励客户针对规范编程，依赖于上述定义的两个标头，而不是将当前限制硬编码。

基于IP的速率限制

我们在一些API路由上还采用了基于IP的速率限制。如果您触发了基于IP的速率限制，您的API响应将包含一个指示何时重试的Retry-After头。客户端必须在至少等待Retry-After秒后才能对我们API进行更多调用，并应采用抖动和退避策略以避免再次触发速率限制。

OpenAPI (Swagger) 和客户端库

我们为API提供了一个完整的OpenAPI (Swagger) 规范。

我们根据OpenAPI规范自动生成多个客户端库。了解更多信息，请访问GitHub上的客户端库集合。您也可以使用此规范生成客户端库，以便在您选择的编程语言中与我们的REST API交互。

我们的OpenAPI规范支持Postman和Insomnia等基于API的工具。在许多情况下，您可以直接导入我们的规范来探索我们的API。

方法覆盖

一些防火墙和HTTP客户端限制了除GET和POST之外动词的使用。在这些环境中，使用DELETE、PATCH和PUT动词的API端点不可访问。

为了避免这个问题，我们的API支持X-HTTP-Method-Override头，允许客户端使用POST请求“隧道”DELETE、PATCH和PUT请求。

例如，要使用POST请求调用PATCH端点，您可以在头中包含X-HTTP-Method-Override:PATCH。

测试资源

在我们将API资源以通用可用性发布之前，我们有时会以测试状态发布新的API资源。

处于测试阶段的资源仍在测试和开发中。它们可能会在没有通知的情况下发生变化，包括变得向后不兼容。

我们尽可能快地将资源推广到通用可用性。这发生在经过足够的测试并且我们满意我们不再需要进行向后不兼容的更改之后。

我们在文档中标记测试资源为“测试”提示，如图下所示

此功能处于测试阶段

要使用此功能，请传递一个包含LD-API-Version键且值为beta的头。在每个调用中使用此头。要了解更多信息，请阅读测试资源。

处于测试阶段的资源仍在测试和开发中。它们可能会在没有通知的情况下发生变化，包括变得向后不兼容。

使用测试资源

要使用测试资源，您必须在请求中包含一个头。如果您在没有此头的情况下调用测试资源，您将收到403响应。

使用此头

LD-API-Version: beta

联邦环境

在美国政府控制的域名上可用的LaunchDarkly版本与对公众可用的LaunchDarkly版本不同。如果您是美国联邦机构的员工或承包商，并在工作中使用LaunchDarkly，您可能使用的是联邦实例的LaunchDarkly。

如果您在LaunchDarkly的联邦实例中工作，每个请求的基本URI是https://app.launchdarkly.us。在“尝试”沙盒中的每个请求中，点击请求路径以查看联邦环境的完整资源路径。

要了解更多信息，请阅读联邦环境中的LaunchDarkly。

版本控制

我们努力保持我们的REST API向后兼容，但在发布新功能的过程中，我们有时不得不进行向后不兼容的更改。如果您没有相应准备，这些破坏性更改可能会导致意外的行为。

我们REST API的更新包括对LaunchDarkly最新特性的支持。每次我们进行重大更改时，也会发布新的REST API版本。我们同时支持多个API版本，以便您可以按自己的节奏从当前API版本迁移到新版本。

按请求设置API版本

您可以通过发送一个LD-API-Version头，在特定的请求上设置API版本，如下例所示：

LD-API-Version: 20240415

头部的值是您想请求的API版本号。每个版本号对应于版本发布的日期，格式为yyyymmdd。在上面的例子中，版本号20240415对应于2024年4月15日。

按访问令牌设置API版本

当您创建访问令牌时，必须指定要使用的API版本。这确保了使用此令牌的集成不会被版本更改破坏。

在版本化发布之前创建的令牌，其版本设置为20160426，这是当前版本化方案之前存在的API版本，以便它们可以像版本化之前一样继续工作。

如果您想将您的集成升级到使用新的API版本，您可以显式设置上述头部。

最佳实践：为每个客户端或集成设置头部

我们建议您在您构建的任何客户端或集成中显式设置API版本头部。

在手动测试期间，仅依赖于访问令牌API版本。

API版本变更日志

要了解更多关于如何确定EOL的信息，请阅读LaunchDarkly的EOL（终止服务）政策。

有关更多信息，请访问https://support.launchdarkly.com。

安装与使用

要求

PHP 7.4及更高版本。也应在PHP 8.0中工作。

Composer

要通过Composer安装绑定，请将以下内容添加到composer.json中：

{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/launchdarkly/api-client-php.git"
    }
  ],
  "require": {
    "launchdarkly/api-client-php": "*@dev"
  }
}

然后运行composer install

手动安装

下载文件并包含autoload.php

<?php
require_once('/path/to/OpenAPIClient-php/vendor/autoload.php');

入门

请按照安装过程进行操作，然后运行以下命令：

<?php
require_once(__DIR__ . '/vendor/autoload.php');



// Configure API key authorization: ApiKey
$config = LaunchDarklyApi\Configuration::getDefaultConfiguration()->setApiKey('Authorization', 'YOUR_API_KEY');
// Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
// $config = LaunchDarklyApi\Configuration::getDefaultConfiguration()->setApiKeyPrefix('Authorization', 'Bearer');


$apiInstance = new LaunchDarklyApi\Api\AccessTokensApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);
$id = 'id_example'; // string | The ID of the access token to update

try {
    $apiInstance->deleteToken($id);
} catch (Exception $e) {
    echo 'Exception when calling AccessTokensApi->deleteToken: ', $e->getMessage(), PHP_EOL;
}

API端点

所有URI都相对于https://app.launchdarkly.com

模型

授权

API密钥

类型：API密钥
API密钥参数名：授权
位置：HTTP头

测试

要运行测试，请使用

composer install
vendor/bin/phpunit

作者

support@launchdarkly.com

关于此包

此PHP包是由OpenAPI Generator项目自动生成的

API版本：2.0
- 包版本：16.1.1
构建包：org.openapitools.codegen.languages.PhpClientCodegen

launchdarkly / api-client-php

维护者

详细信息