什么是卡托 API

本文帮助您开始使用卡托 API 来监控和配置账户中的设置和项目。

概述

卡托 API 是与卡托云无缝集成的主要自动化接口。使用卡托 API 来设置有效的操作工作流程，如部署和配置，以及全面的状态监控、统计数据收集和分析，以简化您的网络和安全性。

卡托 API 终端和架构

API 终端和架构的 URL 是特定于托管卡托管理应用程序实例的位置的。可能存在一个 <prefix> 值，它被附加到您的账户、API 终端和架构的 URL 上。

API 终端的 URL 格式为 https://api.<prefix>.catonetworks.com/api/v1/graphql2。

API 架构的 URL 格式为 https://api.<prefix>.catonetworks.com/api/schema。

API端点的URL

如果没有前缀（例如 cc.catonetworks.com），则使用以下 URL：https://api.catonetworks.com/api/v1/graphql2
如果有前缀（例如 cc.us1.catonetworks.com），则您应该使用以下 URL（为不同位置修改前缀）：https://api.us1.catonetworks.com/api/v1/graphql2

API架构的URL

如果没有前缀（例如 cc.catonetworks.com），则使用以下 URL：https://api.catonetworks.com/api/schema
如果有前缀（例如 cc.us1.catonetworks.com），则您应该使用以下 URL（为不同位置修改前缀）：https://api.us1.catonetworks.com/api/schema

API 架构文档

卡托API基于GraphQL，提供与REST API工具和客户端完全兼容的直观界面。 GraphQL还提供了灵活性，允许您仅查询所需的数据，减少过度获取，提高效率。

卡托 API 文档可在卡托网络 GraphQL API 参考上查阅，其中包括：

架构定义和文档
示例 API 调用和相应的样本响应
带有互动游乐场的 GraphQL API 端点，用于探索和测试 API

API 生命周期

本节根据特定 API 的成熟度等级和可用性介绍不同的生命周期阶段。

每个新的 API 初始发布在 Beta 阶段。从 Beta 到 GA 的过渡需经过内部审核和考量，以验证该 API 的稳定性并达到生产就绪。通常，从 Beta 到 GA 的过渡大约需要一年时间。

注意

注意：以下描述的生命周期仅指正式定义的卡托 API，如在卡托网络 GraphQL API 参考中定义。它不包括任何作为参考提供的额外工具和示例。

例如，它不包括在卡托 GitHub 账户上提供的开源示例和实用程序。这些资源按"原样"提供，不附带进一步开发、维护或支持的保证或义务。

API 成熟度等级

这些是作为生命周期阶段的一部分的 API 成熟度等级：

Beta: 处于 Beta 阶段的 API 功能完整且被认为完全可操作，使之适用于生产环境中的使用。然而，它们可能会根据用户反馈或其他考虑进行更改。这些更改，包括对 API 架构的重大更改，可能会在短时间内发生，需要更新客户端代码。
GA (General Availability): GA 中的 API 稳定、生产就绪，并提供长期支持和向后兼容的承诺。 API 架构的重大更改很少见，将在提前通知，以提供充足的时间进行客户端代码调整。

未明确标记为 Beta 的 API 被视为 GA。在某些情况下，在 GA API 中，个别字段、类型和输入可能会被标记为 Beta。

API 可用性等级

这些是生命周期阶段的一部分的 API 可用性等级：

EA (Early Availability): EA 中的 API 提供给有限用户组用于测试和反馈，之后才会进行更广泛的发布。访问可能需要特殊审批或条件。
Gradual Rollout: 根据行业最佳实践标准，卡托 API 逐步推出，以确保稳定性并监测性能，随着时间推移扩展到所有账户。

未标记为 EA 或 Gradual Rollout 的 API 被视为完全部署并对所有用户开放。

API 标签总结

本节总结了文档中根据成熟度和可用性等级使用的 API 标签。

没有标签的 API 完全对所有账户开放，并且很少会有破坏性的架构更改。任何此类更改将在提前几个月通知。有关这些更改的更多信息，请参阅下文可能破坏架构的更改。

EA
- 仅对加入卡托 EA 计划的客户开放，要加入，请联系我们 ea@catonetworks.com
Beta
- 可能会对架构进行更改
- 重大更改通知时间可能短至两周
- Beta API 支持全功能
发布
- 这些GA API正在逐步推出，几周内可向所有账户开放
- 调用 Rollout 状态的 API 可能会导致错误消息，因为该 API 尚未对您的账户开放

可能破坏架构的更改

本节讨论卡托对 GraphQL API 架构的更改可能影响 API 调用的行为和结果。

什么是GraphQL中的可能破坏性更改？

在GraphQL中，可能破坏性更改发生在API的修改需要客户端更新其查询或逻辑以保持功能时。包括以下示例：

删除字段、类型或参数。
重命名字段、类型或参数。
修改参数的默认值，导致查询或操作的预期结果改变。
更改字段的类型或行为影响兼容性。例如，更改字段的类型（例如，从Int到String）或修改参数的为空性（例如，从可为空到不可为空）。

宣布和管理可能的破坏性更改

我们尽可能地努力避免可能的破坏性更改。然而，在极少情况下出现这种更改，将会如下面通知关于 EoL API中解释那样通知客户。

这些更改可能更频繁地发生在 Beta API 上，但在 GA API 上却很少见。

废弃的 API

被标记为废弃的 API 或字段表明不再建议使用，并且存在更好的替代方案。我们建议您更新脚本和流程，不再使用废弃的 API 和字段以保持预期的行为和功能。

通知关于 EoL API

如果计划移除或替换 API 或字段，它将经历一个生命周期结束 (EoL) 过程。此过程包括以下步骤：

将 API 或字段标记为废弃
1. 计划移除的 API 或字段在卡托网络 GraphQL API 参考中标记为废弃。
2. 此标签会附带消息，指出替代的 API 或字段（如果适用）以及计划的 EoL 日期。
EoL 通知
1. 卡托 API 可能的破坏性更改和 EoL 文章更新为架构将通过更改更新的具体日期。
2. 通知和架构更改之间的时间段如下：
  - GA API：至少提前 3 个月，通常提前 6 个月
  - Beta API：通常为提前 2 周
3. 在EoL通知和EoL日期之间的时间内，客户需更新客户端代码以适应GraphQL的架构更改。

非破坏性架构更改

对GraphQL进行的非破坏性但仍然重要的更改，例如新增API或新字段，通过卡托API更新日志文章宣布。

卡托网络 GraphQL API 参考始终包含完整支持的最新GraphQL架构。