Quarkus Rest Client调用Azure全球端点报404错误求助

我通过Quarkus Rest Client调用Azure全球设备预配服务（DPS）端点执行设备预配与注册操作，但持续收到404错误。注入的参数、参数值及端点路径均看似正确，授权方式为生成SAS令牌。参考的Azure官方文档是关于设备运行时注册的接口，请问是否遗漏了文档内容，或是文档已过时？

相关代码 #

import jakarta.ws.rs.*;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;
import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;

@RegisterRestClient(configKey = "dps-api")
@Path("/registrations")
public interface AzureRestClient {

    @PUT
    @Consumes(MediaType.APPLICATION_JSON)
    @Produces(MediaType.APPLICATION_JSON)
    @Path("/{registrationId}/register?api-version=2021-10-01")
    Response registerDevice(RegistrationPayload payload, @PathParam("registrationId") String registrationId,
            @HeaderParam("Authorization") String authorization);

}

配置文件（application.properties） #

quarkus.rest-client.dps-api.url=https://global.azure-devices-provisioning.net/0usxxxxxxx

错误信息 #

Caused by: org.jboss.resteasy.reactive.ClientWebApplicationException: Received: 'Not Found, status code 404' when invoking REST Client method: 'com.my.clients.AzureRestClient#registerDevice'
    at org.jboss.resteasy.reactive.client.impl.RestClientRequestContext.unwrapException(RestClientRequestContext.java:205)
    at org.jboss.resteasy.reactive.common.core.AbstractResteasyReactiveContext.handleException(AbstractResteasyReactiveContext.java:331)
    at org.jboss.resteasy.reactive.common.core.AbstractResteasyReactiveContext.run(AbstractResteasyReactiveContext.java:175)
    at org.jboss.resteasy.reactive.client.impl.RestClientRequestContext$1.lambda$execute$0(RestClientRequestContext.java:324)
    at io.vertx.core.impl.ContextInternal.dispatch(ContextInternal.java:270)
    at io.vertx.core.impl.ContextInternal.dispatch(ContextInternal.java:252)
    at io.vertx.core.impl.ContextInternal.lambda$runOnContext$0(ContextInternal.java:50)
    at io.netty.util.concurrent.AbstractEventExecutor.runTask(AbstractEventExecutor.java:173)
    at io.netty.util.concurrent.AbstractEventExecutor.safeExecute(AbstractEventExecutor.java:166)
    at io.netty.util.concurrent.SingleThreadEventExecutor.runAllTasks(SingleThreadEventExecutor.java:469)
    at io.netty.channel.nio.NioEventLoop.run(NioEventLoop.java:566)
    at io.netty.util.concurrent.SingleThreadEventExecutor$4.run(SingleThreadEventExecutor.java:994)
    at io.netty.util.internal.ThreadExecutorMap$2.run(ThreadExecutorMap.java:74)
    ... 2 more

问题排查与解决方案 #

1. 修正API版本参数的传递方式 #

你在@Path注解中直接拼接查询参数?api-version=2021-10-01不符合JAX-RS规范，会导致路径解析错误。正确做法是用@QueryParam单独传递：

修改接口方法：

@PUT
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
@Path("/{registrationId}/register")
Response registerDevice(RegistrationPayload payload, 
                        @PathParam("registrationId") String registrationId,
                        @HeaderParam("Authorization") String authorization,
                        @QueryParam("api-version") @DefaultValue("2021-10-01") String apiVersion);

2. 校验DPS端点URL的完整性 #

Azure DPS的完整端点格式为https://global.azure-devices-provisioning.net/{id-scope}，确认配置中的0usxxxxxxx是正确的ID范围（ID Scope）——如果ID Scope错误，会直接返回404。

3. 验证SAS令牌有效性 #

SAS令牌的资源URI必须严格匹配global.azure-devices-provisioning.net/{id-scope}/registrations/{registrationId}，同时要确保令牌的签名算法、过期时间、权限等参数符合Azure DPS要求，可通过Azure官方工具验证令牌合法性。

4. 文档有效性确认 #

你参考的2021-10-01版本API目前仍处于Azure DPS支持范围内，并未过时，无需担心文档版本问题。

内容的提问来源于stack exchange，提问作者Sam