Endpoints HTTPS Personalizados [Obsoleto]HTTPS endpoints

URL base

Os pontos de conexão em uma aplicação compartilham uma URL base. A URL usa seu ID da aplicação para apontar exclusivamente para sua aplicação.

Aplicações implantadas globalmente utilizam o seguinte formato:

https://data.mongodb-api.com/app/<App ID>/endpoint

Os pontos de extremidade em um aplicativo implantado localmente usam uma URL base específica para a região de sistema do aplicativo (por exemplo, us-east-1)

https://<Region>.aws.data.mongodb-api.com/app/<App ID>/endpoint

Rotas de endpoint

Cada endpoint HTTPS tem uma rota que serve como nome para o endpoint. A rota de um endpoint é arbitrária e específica para sua aplicação. No entanto, ele aparece no caminho da URL do terminal e, portanto, deve representar a ação que a rota executa.

Os nomes de rota devem começar com uma barra (/) e podem conter barras adicionais para indicar um caminho agrupado.

/my/nested/route

Você chama um ponto de conexão anexando sua rota à URL base de sua aplicação e enviando uma requisição HTTP.

https://data.mongodb-api.com/app/<App ID>/endpoint/my/nested/route

Métodos de HTTP

Cada endpoint em sua aplicação lida com um ou mais métodos HTTP para determinada rota. Por exemplo, você pode ter uma única rota que aceite solicitações POST para criar um novo recurso e uma solicitação GET para listar os recursos existentes.

Você pode definir vários endpoints personalizados que atendem à mesma rota, mas manipulam métodos de solicitação diferentes. Alternativamente, você pode definir um único endpoint para a rota que lida com todos os métodos.

Os endpoints personalizados são compatíveis com os seguintes métodos HTTP padrão:

• OBTER

• POSTAR

• COLOCAR

• REMENDO

• EXCLUIR

Autenticação

Os pontos de conexão personalizados são executados no contexto de um usuário específico, o que permite que sua aplicação aplique regras e valide esquemas de documentos para cada solicitação.

Por padrão, os endpoints usam a Autenticação de Aplicativo, que exige que cada solicitação inclua credenciais para um dos usuários do aplicativo, como uma chave API ou JWT. Você também pode configurar outros esquemas de autenticação personalizados para atender às necessidades do seu aplicativo.

Para ver exemplos de como autenticar solicitações, consulte Autenticar Solicitações de API de Dados.

[
  {
    ...,
    "run_as_user_id": "628e47baf4c2ac2796fc8a91"
  }
]

[
  {
    ...,
    "run_as_user_id_script_source": "exports = () => {return \"628e47baf4c2ac2796fc8a91\"}"
  }
]

[
  {
    ...,
    "run_as_system": true
  }
]

Autorização

Um ponto de conexão pode exigir que os usuários autenticados forneçam informações adicionais na solicitação. Você define o esquema de autorização para cada ponto de conexão personalizado configurando a função de ponto de conexão.

Os endpoints oferecem suporte nativo a um conjunto de esquemas de autorização internos que usam uma string secreta para provar que a solicitação está autorizada. Você também pode definir um esquema de autorização personalizado que pode ser usado junto com os esquemas integrados ou em vez deles.

Para saber como configurar a autorização para uma função específica, consulte Definir uma função.

[
  {
     ...,
     "verification_method": "SECRET_AS_QUERY_PARAM",
     "secret_name": "secret_verification_string"
  }
]

[
  {
     ...,
     "can_evaluate": {
       "%%request.requestHeaders.x-secret-key": "my-secret"
     }
  }
]

Dados da solicitação de acesso

Um objeto de endpoint personalizado Request representa a solicitação HTTP que chamou o endpoint. Você pode acessar os cabeçalhos, os parâmetros de query e os dados do corpo da solicitação recebida.

{
  "headers": { "<Header>": ["<Header Value>"] },
  "query": { "<Query Parameter>": "<Parameter Value>" },
  "body": <BSON.Binary>
}

{
  "regions": "na&eu",
  "currency": "USD"
}

{
  "Content-Type": ["application/json"],
  "Accept": ["application/json"],
  "X-CustomHeader": ["some-value", "some-other-value"]
}

// Convert the request body to a JSON string
const serialized = request.body.text();
// Parse the string into a usable object
const body = JSON.parse(serialized);

Retornar uma Resposta HTTPS

Um objeto de endpoint personalizado Response permite configurar a resposta HTTPS enviada de volta para o chamador. Você pode definir o código de status, personalizar cabeçalhos e incluir dados no corpo da resposta.

response.setStatusCode(201);

response.setBody(
  "{'message': 'Hello, World!'}"
);

response.setHeader(
  "Content-Type",
  "application/json"
);

response.addHeader(
  "Cache-Control",
  "max-age=600"
);
response.addHeader(
  "Cache-Control",
  "min-fresh=60"
)

Exemplo

Considere uma função de endpoint que analisa o corpo de uma solicitação POST recebida, armazena o corpo analisado em uma coleção MongoDB e, em seguida, responde ao chamador:

exports = async function MyCustomEndpoint(request, response) {
  try {
    // 1. Parse data from the incoming request
    if (request.body === undefined) {
      throw new Error(`Request body was not defined.`);
    }
    const body = JSON.parse(request.body.text());
    // 2. Handle the request
    const { insertedId } = await context.services
      .get("mongodb-atlas")
      .db("myDb")
      .collection("myCollection")
      .insertOne({ date: new Date(), requestBody: body });
    // 3. Configure the response
    response.setStatusCode(201);
    // tip: You can also use EJSON.stringify instead of JSON.stringify.
    response.setBody(
      JSON.stringify({
        insertedId,
        message: "Successfully saved the request body",
      })
    );
  } catch (error) {
    response.setStatusCode(400);
    response.setBody(error.message);
  }
};

A função recebe a seguinte solicitação POST:

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/custom" \
  -X POST \
  -H "Accept: application/json" \
  -H "apiKey: TpqAKQgvhZE4r6AOzpVydJ9a3tB1BLMrgDzLlBLbihKNDzSJWTAHMVbsMoIOpnM6" \
  -d '{
    "type": "event",
    "date": "2024-01-01T00:00:00.000Z",
    "name": "New Year Begins",
    "comment": "Happy New Year!"
  }'

{
  "message": "Successfully saved the request body",
  "insertedId": "639a521bbdec9b85ba94014b"
}

Após a função verificar se o corpo da solicitação de entrada está definido, ela armazena o corpo analisado como um novo documento em uma coleção denominada myCollection. A saída resultante exibe a resposta configurada, que inclui uma mensagem personalizada e o insertedId.

Escolher um Formato de Dados de Resposta

Uma solicitação pode incluir um cabeçalho Accept para solicitar um formato de dados específico para o corpo da resposta, JSON ou EJSON. Se uma solicitação não incluir um cabeçalho Accept válido, a resposta usará o formato de dados padrão especificado na configuração do endpoint

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/hello/latest" \
  -X GET \
  -H "Accept: application/ejson" \
  -H "apiKey: TpqAKQgvhZE4r6AOzpVydJ9a3tB1BLMrgDzLlBLbihKNDzSJWTAHMVbsMoIOpnM6"

{
  "greeting": "Hello, Leafie!",
  "date": { "$date": { "$numberLong": "1654589430998" } }
}

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/hello/latest" \
  -X GET \
  -H "Accept: application/json" \
  -H "apiKey: TpqAKQgvhZE4r6AOzpVydJ9a3tB1BLMrgDzLlBLbihKNDzSJWTAHMVbsMoIOpnM6"

{
  "greeting": "Hello, Leafie!",
  "date": "2022-06-07T08:10:30.998Z"
}

Autenticar a Solicitação

Se um ponto de extremidade estiver configurado para usar a autenticação de aplicativo, você deve incluir um token de acesso de usuário válido ou credenciais de login com cada solicitação.

Em geral, a autenticação de portador com um token de acesso tem uma taxa de transferência mais alta e é mais segura do que os cabeçalhos de credenciais. Use um token de acesso em vez de cabeçalhos de credenciais quando possível. O token permite que você execute várias solicitações sem autenticar o usuário novamente. Ele também permite que você envie solicitações de um navegador da Web que imponha o CORS.

Para usar um token de acesso, primeiro autentique o usuário por meio de um fornecedor de autenticação do App Services. Em seguida, obtenha o token de acesso retornado pelo App Services e inclua-o no cabeçalho de autorização da solicitação usando um esquema de token de portador. Para obter mais informações sobre como adquirir e usar um token de acesso, consulte Autenticação de Token de Portador.

curl -X GET \
   -H 'Authorization: Bearer <AccessToken>' \
   -H 'Content-Type: application/json' \
   https://data.mongodb-api.com/app/myapp-abcde/endpoint/hello

Como alternativa, você pode incluir credenciais de login válidas para o usuário nos cabeçalhos de solicitação.

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/hello" \
  -X POST \
  -H "Accept: application/json" \
  -H "email: bob@example" \
  -H "password: Pa55w0rd!" \
  -d '{ "name": "Bob" }'

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/hello" \
  -X POST \
  -H "Accept: application/json" \
  -H "apiKey: TpqAKQgvhZE4r6AOzpVydJ9a3tB1BLMrgDzLlBLbihKNDzSJWTAHMVbsMoIOpnM6" \
  -d '{ "name": "Alice" }'

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/hello" \
  -X POST \
  -H "Accept: application/json" \
  -H "jwtTokenString: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJ0ZXN0LWN1c3RvbS1lbmRwb2ludHMtZWhtenQiLCJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiZXhwIjoyMTQ1OTE2ODAwfQ.pIMvnXWrcDvmPzmE33ZPrwkBAFSwy-GxW8sP-qLtYiw" \
  -d '{ "name": "Carlos" }'

Autorizar a Solicitação

Dependendo da configuração do endpoint, suas solicitações podem precisar incluir informações de autorização adicionais.

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/passwordRequired?secret=Super5ecr3tPa55w0rd" \
  -X GET \
  -H "Accept: application/json" \
  -H "apiKey: TpqAKQgvhZE4r6AOzpVydJ9a3tB1BLMrgDzLlBLbihKNDzSJWTAHMVbsMoIOpnM6" \
  -d '{ "data": "VGhpcyBpcyBzb21lIGRhdGEgdGhhdCB3YXMgZW5jb2RlZCBhcyBhIEJhc2U2NCBBU0NJSSBzdHJpbmc=" }'

Endpoint-Signature: sha256=<hex encoded hash>

/**
 * Generate an HMAC request signature.
 * @param {string} secret - The secret validation string, e.g. "12345"
 * @param {object} body - The endpoint request body e.g. { "message": "MESSAGE" }
 * @returns {string} The HMAC SHA-256 request signature in hex format.
 */
exports = function signEndpointRequest(secret, body) {
  const payload = EJSON.stringify(body);
  return utils.crypto.hmac(payload, secret, "sha256", "hex");
};

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/sendMessage" \
  -X POST \
  -H "Accept: application/json" \
  -H "apiKey: TpqAKQgvhZE4r6AOzpVydJ9a3tB1BLMrgDzLlBLbihKNDzSJWTAHMVbsMoIOpnM6" \
  -H "Endpoint-Signature: sha256=d4f0537db4e230d7a6028a6f7c3bb1b57c9d16f39176d78697e559ac333e0b36" \
  -d '{ "message": "Hello!" }'