使用 GraphQL 进行自省

GraphQL 是基于类型系统的查询语言。 GraphQL 类型定义受支持的对象，与对象关联的字段以及可查询的内容和方式，所有这些都由 GraphQL 模式定义。为了能够有效使用 GraphQL API ，必须充分了解 Supply Chain Intelligence Suite 数据模型。

准备工作

如果您是 GraphQL的新手，请完成 GraphQL 教程，直到您熟悉 GraphQL API 基础知识为止。
安装 REST 客户机，例如 Insomnia。
确保为 GraphiQL 工具正确配置了浏览器。

关于本任务

学习 Supply Chain Intelligence Suite 数据模型模式的一个好方法是使用 GraphQL 自省。只要您对模式的任何部分有疑问，例如定义了哪些对象，哪些字段与某个类型相关联，枚举的值是什么，支持的查询类型以及可用于查询的参数，模式自省都会有所帮助。

您将学习以下任务:

如何查找所有受支持的类型，例如对象，接口和枚举。
如何查找每种类型的更多详细信息，例如对象的字段或枚举的值。
支持哪些查询以及查询详细信息，例如参数。
支持哪些突变。
如何根据自省结果构造 GraphQL 查询。

您可以在 GraphiQL中使用文档资源管理器。

GraphiQL 工具使用自省逻辑在 UI 中构建交互式模式资源管理器。通过在浏览器中粘贴此 URL 来浏览到 GraphiQL 界面:

https://api.ibm.com/infohub/run/graph/na

请注意文档链接:

单击文档链接时， GraphiQL 会将模式自省请求发送到 GraphQL API ，然后将响应解析为可随后浏览的文档对象模型 (DOM)。然后，将呈示文档资源管理器以及模型中顶级对象的列表，在此示例中，这些对象是 query 和突变。

在此视图中，可以向下钻取以浏览所有对象及其属性。例如，在钻取到查询后，视图将显示查询的 eventParams 属性的 BusinessEventInput 值:

程序

在 GraphQL 可视编辑器中自省模式中定义的所有类型。
1. 通过在浏览器中输入以下 URL 来浏览至 GraphiQL 可视编辑器:
  https://api.ibm.com/infohub/run/graph/na
2. 将以下 GraphQL 查询粘贴到编辑器左侧，然后单击运行。
```
query {
 __schema {
	    types {
		  name
		  description
		  kind
		}
		queryType {
		  fields {
			name
			description
		  }
		}
   }
 }
```
  完成查询后，您可以在编辑器右侧看到查询响应。查看响应并查找 OBJECT ， INTERFACE 和 ENUM 的一些示例。 OBJECT 类型是 GraphQL API 的基础。每个 OBJECT 都有字段，这些字段公开数据并可按名称查询。 INTERFACE 是字段列表，可由 OBJECT 类型实现。 ENUM 类型是离散值的集合。
3. 浏览至响应的底部，并查看受支持的查询列表。
4. 可选: 在 GraphiQL 可视编辑器中，使用右上角的链接来检查模式定义。
在 Insomnia 中运行相同的 GraphQL 模式查询。
1. 打开 Insomnia ，启动名为 Get Intelligence Suite schema info的新请求。
2. 从列表中选择 POST 并输入以下 URL:
  https://api.ibm.com/infohub/run/graph/na
3. 在请求主体部分中，选择 GraphQL ，然后将上一步中的相同查询复制并粘贴到 QUERY 框中。
4. 在 Insomnia 中禁用 SSL 证书验证。
5. 单击发送并在请求的响应部分中查看响应:
  响应必须与上一步中接收到的响应相同。

自省类型详细信息。

在 Insomnia 中输入以下查询:

  query {
    __type(name: "BusinessObjectsCursor") {
  	...FullType
    }
  }

  fragment FullType on __Type {
    kind
    name
    description
    fields(includeDeprecated: true) {
  	name
  	description
  	args {
  	  ...InputValue
  	}
  	type {
  	  ...TypeRef
  	}
  	isDeprecated
  	deprecationReason
    }

    inputFields {
  	...InputValue
    }

    interfaces {
  	...TypeRef
    }

    enumValues(includeDeprecated: true) {
  	name
  	description
  	isDeprecated
  	deprecationReason
    }

    possibleTypes {
  	...TypeRef
    }
  }

  fragment InputValue on __InputValue {
    name
    description
    type {
  	...TypeRef
    }
    defaultValue
  }

  fragment TypeRef on __Type {
    kind
    name
    ofType {
  	kind
  	name
  	ofType {
  	  kind
  	  name
  	  ofType {
  		kind
  		name
  		ofType {
  		  kind
  		  name
  		  ofType {
  			kind
  			name
  			ofType {
  			  kind
  			  name
  			  ofType {
  				kind
  				name
  			  }
  			}
  		  }
  		}
  	  }
  	}
    }
  }

检查接收到的响应。
BusinessObjectsCursor 是实现 INTERFACE Cursor的 OBJECT 类型。它有三个已定义的字段: edges， pageInfo和 totalCount。字段 edges 是 OBJECT BusinessObjectEdge的 LIST。了解 INTERFACE 有助于简化响应中具有不同 OBJECT 类型的查询。
将查询中的类型名称替换为在步骤 1 或 2中选取的一些其他类型，再次运行查询，然后检查响应以了解类型定义。

与接口关联的自省类型。
虽然可以将步骤 3 中显示的查询用于任何类型，但您可能更喜欢针对特定类型 (例如， INTERFACE 或 ENUM) 的更简单的响应。您可以获取实现特定 INTERFACE 的对象的干净列表。从 GraphQL API 客户机透视图中，了解 OBJECT 实现的 INTERFACE 可帮助简化查询响应。
1. 使用以下查询来查找实现相同 INTERFACE 的所有 OBJECT。
```
query {
__type(name: "Cursor") {
  name
  kind
  description
  possibleTypes {
    name
    kind
    description
  }
}
}  
```
  响应将显示 Supply Chain Intelligence Suite中定义的所有 Cursor OBJECTS。
2. 选取您在步骤 1 或 2中识别的另一个接口，将其放入查询中，然后运行该接口以查找所有关联的 OBJECT。
自省 ENUM 值。
Supply Chain Intelligence Suite 在模式中使用大量 ENUM。 ENUM 类型定义一组离散值，例如， Supply Chain Intelligence Suite ENUM 类型 BusinessObjectType 提供模式中定义的所有业务对象的列表。此步骤显示用于获取 ENUM 的值列表的查询。
1. 将以下查询复制并粘贴到您选择的工具中，然后运行该查询。
```
query {
__type(name: "BusinessObjectType") {
  name
  kind
  description
  enumValues {
    name
    description
  }
}
}
```
  检查结果以查看 ENUM BusinessObjectType下列出的所有对象类型。此列表显示 API 中支持的业务数据对象。
2. 将类型替换为您在步骤 1 或 2 中选取的另一个 ENUM 类型，然后重新运行查询以查看该 ENUM 的值列表。
自省查询定义。
所有受支持的 GraphQL 查询都在模式中的特殊类型 Query 中定义。您可以使用在步骤 4 中定义的查询来获取相关信息。
1. 在 Insomnia 中运行以下 GraphQL 查询:
```
  query {
    __type(name: "Query") {
  	...QueryType
    }
  }

  fragment QueryType on __Type {
    fields {
  	name
  	description
  	type {
  		name
  		kind
  	}
  	args {
  	  name
  	  description
  	  type {
  		  name
  		  kind
  	  }
  	}
    }
  }
```
  检查响应。每个受支持的查询都显示为响应中的一个字段。目前，在模式中总共定义了四个查询。其中一个查询是 businessObjectEvents，它返回 BusinessEventCursor。此查询可以采用五个不同的参数，其中一个参数是 OBJECT 类型 BooleanExp的 advancedFilter 。
自省突变定义。
突变是另一种模式类型，用于定义 API 支持的所有突变。与用于访存数据的 GraphQL 查询 API 不同，提供了 GraphQL 突变 API 来修改服务器上的数据。将步骤 6中使用的查询中的 Query 替换为 Mutation ，并检出所有 InforHub 突变定义，即，通过 Supply Chain Intelligence Suite GraphQL API 支持的数据操作类型。
构造 Supply Chain Intelligence Suite。
现在，您知道如何查找所有受支持的类型以及如何查找每种类型的详细信息。 Sample queries were provided for INTERFACE, ENUM, Query, Mutation, which contain sufficient information to get started on constructing your first Supply Chain Intelligence Suite GraphQL query.
1. 使用步骤 6 中的查询来查找 businessRuleEvents的查询定义。
2. 使用步骤 3 中的查询来查找响应类型的详细信息。
3. 使用步骤 3 中的查询来查找每个查询参数的详细信息。
4. 根据上述步骤的结果，构造 businessRuleEvents的 GraphQL 查询。