本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
中的故障診斷和常見錯誤 AWS AppSync
本區段說明一些常見的錯誤,以及如何排除這些問題。
不正確的 DynamoDB 索引鍵映射
如果您的 GraphQL 操作傳回下列錯誤訊息,可能是因為您的請求映射範本結構不符合 Amazon DynamoDB 金鑰結構:
The provided key element does not match the schema (Service: AmazonDynamoDBv2; Status Code: 400; Error Code
例如,如果您的 DynamoDB 資料表有一個名為 的雜湊索引鍵,"id"而您的範本顯示 "PostID",如下列範例所示,這會導致上述錯誤,因為 "id" 不符合 "PostID"。
{ "version" : "2017-02-28", "operation" : "GetItem", "key" : { "PostID" : $util.dynamodb.toDynamoDBJson($ctx.args.id) } }
缺少解析程式
如果您執行查詢等 GraphQL 操作,但是獲得 null 回應,這可能是因為您並未設定解析程式。
如果匯入的結構描述定義了 getCustomer(userId:
ID!): 欄位,但並未針對此欄位設定解析程式,則當您執行像是 getCustomer(userId:"ID123"){...} 的查詢時,將會獲得類似於下列的回應:
{ "data": { "getCustomer": null } }
如果您在變更結構描述後遺失先前設定的解析程式,請參閱 當您移除解析程式的結構描述欄位時,解析程式已移除。
映射範本錯誤
如果未正確設定映射範本,您將會收到 GraphQL 回應,其中的 errorType 為 MappingTemplate。message 欄位應該會指出映射範本的問題所在。
例如,如果請求映射範本未包含 operation 欄位,或是 operation 欄位的名稱不正確,則您將會收到類似下列的回應:
{ "data": { "searchPosts": null }, "errors": [ { "path": [ "searchPosts" ], "errorType": "MappingTemplate", "locations": [ { "line": 2, "column": 3 } ], "message": "Value for field '$[operation]' not found." } ] }
不正確的傳回類型
資料來源所傳來的傳回類型,必須符合結構描述中所定義的物件類型,否則將會出現 GraphQL 錯誤,例如:
"errors": [ { "path": [ "posts" ], "locations": null, "message": "Can't resolve value (/posts) : type mismatch error, expected type LIST, got OBJECT" } ]
例如,下列的查詢定義可能會產生這種錯誤:
type Query { posts: [Post] }
查詢式期望的結果是 [Posts] 物件的清單 (LIST)。例如,如果有使用 Node.JS 的 Lambda 函式,包含類似於下列的程式碼:
const result = { data: data.Items.map(item => { return item ; }) }; callback(err, result);
這將會丟出錯誤,因為 result 是一個物件。您需要將回呼變更為 result.data,或是將結構描述改為不傳回清單 (LIST)。
處理無效的請求
當 AWS AppSync 無法處理並傳送請求 (由於不正確的資料,例如無效的語法) 到欄位解析程式時,回應承載會傳回值設定為 的欄位資料,null以及任何相關的錯誤。
當您移除解析程式的結構描述欄位時,解析程式已移除
解析程式會連接到結構描述中類型的特定欄位。如果您更新結構描述以移除 欄位,或移除已連接解析程式的類型, AWS AppSync 也會移除連接的解析程式。這可讓結構描述及其解析程式保持一致。
如果您稍後還原 欄位 (例如,透過轉返變更),則解析程式不會與其一起還原。接著會傳回 欄位的請求,null因為沒有為其設定解析程式。如需詳細資訊,請參閱缺少解析程式。
與 AWS CloudFormation 和 的互動 AWS CDK
當您使用 CloudFormation 或 管理您的 API 時 AWS CDK,您的結構描述和每個解析程式會定義為個別的資源 (例如 AWS::AppSync::GraphQLSchema和 AWS::AppSync::Resolver)。當結構描述更新移除欄位時, AWS AppSync 會移除連接的解析程式,但此移除不會反映在您的 CloudFormation 堆疊中。 會 CloudFormation 繼續追蹤解析程式,就像它仍然存在一樣。因此:
-
復原堆疊不會重新建立已移除的解析程式。
-
重新部署未變更的範本不會重新建立範本,因為 CloudFormation 不會偵測到解析程式資源的變更。
-
如果結構描述再次參考 欄位,但解析程式遺失,該欄位的請求會傳回
null,而堆疊操作可能會失敗或停止 (例如,狀態為UPDATE_ROLLBACK_FAILED)。
復原已移除的解析程式
-
請確定您的結構描述宣告解析程式所連接的 欄位。
-
重新建立解析程式。由於 CloudFormation 不會對定義未變更的解析程式資源採取行動,因此請進行變更,使其重新建立資源。例如,變更解析程式的邏輯 ID,或移除 ,然後在個別部署中重新新增解析程式資源。或者,使用 AWS AppSync 主控台、
CreateResolverAPI 操作或 直接重新建立解析程式 AWS CLI,然後協調您的範本或 AWS CDK 應用程式。 -
如果堆疊操作停止 (例如,狀態為
UPDATE_ROLLBACK_FAILED),請重新建立缺少的解析程式,讓操作可以完成,然後部署已知良好的範本。
安全地移除或重新命名欄位
-
若要重新命名欄位,請先新增欄位並連接其解析程式、部署變更,然後移除舊欄位。
-
請勿移除您想要保留其解析程式的結構描述欄位。
-
當您刻意移除欄位時,也請在相同的變更中從範本或 AWS CDK 應用程式移除其解析程式資源,讓您的 CloudFormation 狀態保持一致。
-
在開發或測試環境中測試結構描述變更,然後再將其部署到生產環境。